[openssl] OpenSSL_1_1_1-stable update

Richard Levitte levitte at openssl.org
Mon Aug 19 05:50:34 UTC 2019


The branch OpenSSL_1_1_1-stable has been updated
       via  40cb2be7c5e2755733201ef8feb6edc27c40ad64 (commit)
      from  be4660f8d483d5824b52135251899cee5c231456 (commit)


- Log -----------------------------------------------------------------
commit 40cb2be7c5e2755733201ef8feb6edc27c40ad64
Author: Rich Salz <rsalz at akamai.com>
Date:   Sun Aug 18 20:20:37 2019 -0400

    Fix some pod-page ordering nits
    
    Backport of https://github.com/openssl/openssl/pull/9602
    
    Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre at ncp-e.com>
    Reviewed-by: Richard Levitte <levitte at openssl.org>
    (Merged from https://github.com/openssl/openssl/pull/9632)

-----------------------------------------------------------------------

Summary of changes:
 doc/man1/engine.pod                       |  2 +-
 doc/man1/errstr.pod                       |  2 +-
 doc/man1/pkeyparam.pod                    |  2 +-
 doc/man3/ASYNC_start_job.pod              |  2 +-
 doc/man3/BIO_f_ssl.pod                    | 36 +++++++++++++++----------------
 doc/man3/BIO_find_type.pod                |  2 +-
 doc/man3/BIO_new.pod                      |  2 +-
 doc/man3/BIO_s_accept.pod                 |  2 +-
 doc/man3/BIO_s_bio.pod                    |  4 ++--
 doc/man3/BIO_s_connect.pod                |  2 +-
 doc/man3/BIO_s_fd.pod                     |  2 +-
 doc/man3/BIO_s_mem.pod                    | 19 ++++++++--------
 doc/man3/BIO_set_callback.pod             | 10 ++++-----
 doc/man3/BN_mod_mul_montgomery.pod        |  2 +-
 doc/man3/CRYPTO_THREAD_run_once.pod       |  2 +-
 doc/man3/EVP_DigestInit.pod               |  2 +-
 doc/man3/EVP_PKEY_CTX_set_hkdf_md.pod     |  2 +-
 doc/man3/EVP_PKEY_CTX_set_tls1_prf_md.pod |  2 +-
 doc/man3/EVP_PKEY_decrypt.pod             |  2 +-
 doc/man3/EVP_PKEY_derive.pod              |  2 +-
 doc/man3/EVP_PKEY_encrypt.pod             |  2 +-
 doc/man3/EVP_PKEY_sign.pod                |  2 +-
 doc/man3/EVP_PKEY_verify.pod              |  2 +-
 doc/man3/EVP_PKEY_verify_recover.pod      |  2 +-
 doc/man3/OCSP_REQUEST_new.pod             |  2 +-
 doc/man3/PKCS12_newpass.pod               |  2 +-
 doc/man3/RSA_padding_add_PKCS1_type_1.pod |  2 +-
 doc/man3/RSA_public_encrypt.pod           |  2 +-
 doc/man3/SSL_CTX_config.pod               |  2 +-
 doc/man3/SSL_CTX_dane_enable.pod          |  2 +-
 doc/man3/SSL_CTX_get0_param.pod           | 14 ++++++------
 doc/man3/SSL_library_init.pod             |  2 +-
 doc/man3/SSL_set1_host.pod                |  2 +-
 doc/man3/SSL_write.pod                    |  2 +-
 doc/man3/X509_STORE_CTX_set_verify_cb.pod |  2 +-
 doc/man3/X509_VERIFY_PARAM_set_flags.pod  |  2 +-
 doc/man5/x509v3_config.pod                |  3 +--
 doc/man7/Ed25519.pod                      |  2 +-
 doc/man7/SM2.pod                          |  2 +-
 doc/man7/X25519.pod                       |  2 +-
 doc/man7/bio.pod                          |  2 +-
 doc/man7/scrypt.pod                       |  2 +-
 util/find-doc-nits                        | 28 +++++++++++++-----------
 43 files changed, 95 insertions(+), 91 deletions(-)

diff --git a/doc/man1/engine.pod b/doc/man1/engine.pod
index 24f1b32cdb..42d9fdc4f1 100644
--- a/doc/man1/engine.pod
+++ b/doc/man1/engine.pod
@@ -64,7 +64,7 @@ See the example below.
 
 =back
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 To list all the commands available to a dynamic engine:
 
diff --git a/doc/man1/errstr.pod b/doc/man1/errstr.pod
index 3c89b8f5cf..9f46777a3e 100644
--- a/doc/man1/errstr.pod
+++ b/doc/man1/errstr.pod
@@ -20,7 +20,7 @@ second colon.
 
 None.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 The error code:
 
diff --git a/doc/man1/pkeyparam.pod b/doc/man1/pkeyparam.pod
index 50949657c8..0a66184ddf 100644
--- a/doc/man1/pkeyparam.pod
+++ b/doc/man1/pkeyparam.pod
@@ -60,7 +60,7 @@ This option checks the correctness of parameters.
 
 =back
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 Print out text version of parameters:
 
diff --git a/doc/man3/ASYNC_start_job.pod b/doc/man3/ASYNC_start_job.pod
index 9bd1044b26..7c2595926e 100644
--- a/doc/man3/ASYNC_start_job.pod
+++ b/doc/man3/ASYNC_start_job.pod
@@ -170,7 +170,7 @@ is included, commonly as one of the first included headers. Therefore
 it is defined as an application developer's responsibility to include
 windows.h prior to async.h.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 The following example demonstrates how to use most of the core async APIs:
 
diff --git a/doc/man3/BIO_f_ssl.pod b/doc/man3/BIO_f_ssl.pod
index e069594fd1..596b7231d8 100644
--- a/doc/man3/BIO_f_ssl.pod
+++ b/doc/man3/BIO_f_ssl.pod
@@ -129,9 +129,25 @@ BIO_set_ssl(), BIO_get_ssl(), BIO_set_ssl_mode(),
 BIO_set_ssl_renegotiate_bytes(), BIO_set_ssl_renegotiate_timeout(),
 BIO_get_num_renegotiates(), and BIO_do_handshake() are implemented as macros.
 
-=head1 EXAMPLE
+=head1 RETURN VALUES
+
+BIO_f_ssl() returns the SSL B<BIO_METHOD> structure.
+
+BIO_set_ssl(), BIO_get_ssl(), BIO_set_ssl_mode(), BIO_set_ssl_renegotiate_bytes(),
+BIO_set_ssl_renegotiate_timeout() and BIO_get_num_renegotiates() return 1 on
+success or a value which is less than or equal to 0 if an error occurred.
+
+BIO_new_ssl(), BIO_new_ssl_connect() and BIO_new_buffer_ssl_connect() return
+a valid B<BIO> structure on success or B<NULL> if an error occurred.
+
+BIO_ssl_copy_session_id() returns 1 on success or 0 on error.
+
+BIO_do_handshake() returns 1 if the connection was established successfully.
+A zero or negative value is returned if the connection could not be established.
+
+=head1 EXAMPLES
 
-This SSL/TLS client example, attempts to retrieve a page from an
+This SSL/TLS client example attempts to retrieve a page from an
 SSL/TLS web server. The I/O routines are identical to those of the
 unencrypted example in L<BIO_s_connect(3)>.
 
@@ -271,22 +287,6 @@ a client and also echoes the request to standard output.
  BIO_flush(sbio);
  BIO_free_all(sbio);
 
-=head1 RETURN VALUES
-
-BIO_f_ssl() returns the SSL B<BIO_METHOD> structure.
-
-BIO_set_ssl(), BIO_get_ssl(), BIO_set_ssl_mode(), BIO_set_ssl_renegotiate_bytes(),
-BIO_set_ssl_renegotiate_timeout() and BIO_get_num_renegotiates() return 1 on
-success or a value which is less than or equal to 0 if an error occurred.
-
-BIO_new_ssl(), BIO_new_ssl_connect() and BIO_new_buffer_ssl_connect() return
-a valid B<BIO> structure on success or B<NULL> if an error occurred.
-
-BIO_ssl_copy_session_id() returns 1 on success or 0 on error.
-
-BIO_do_handshake() returns 1 if the connection was established successfully.
-A zero or negative value is returned if the connection could not be established.
-
 =head1 HISTORY
 
 In OpenSSL before 1.0.0 the BIO_pop() call was handled incorrectly,
diff --git a/doc/man3/BIO_find_type.pod b/doc/man3/BIO_find_type.pod
index b8171942ef..8288bce5b4 100644
--- a/doc/man3/BIO_find_type.pod
+++ b/doc/man3/BIO_find_type.pod
@@ -40,7 +40,7 @@ BIO_next() returns the next BIO in a chain.
 
 BIO_method_type() returns the type of the BIO B<b>.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 Traverse a chain looking for digest BIOs:
 
diff --git a/doc/man3/BIO_new.pod b/doc/man3/BIO_new.pod
index 2712be0dab..37022c5d8e 100644
--- a/doc/man3/BIO_new.pod
+++ b/doc/man3/BIO_new.pod
@@ -53,7 +53,7 @@ on it other than the discarded return value.
 
 BIO_set() was removed in OpenSSL 1.1.0 as BIO type is now opaque.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 Create a memory BIO:
 
diff --git a/doc/man3/BIO_s_accept.pod b/doc/man3/BIO_s_accept.pod
index 45b864e5e6..65400b0e6c 100644
--- a/doc/man3/BIO_s_accept.pod
+++ b/doc/man3/BIO_s_accept.pod
@@ -174,7 +174,7 @@ BIO_get_bind_mode() returns the set of B<BIO_BIND> flags, or -1 on failure.
 
 BIO_new_accept() returns a BIO or NULL on error.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 This example accepts two connections on port 4444, sends messages
 down each and finally closes both down.
diff --git a/doc/man3/BIO_s_bio.pod b/doc/man3/BIO_s_bio.pod
index dfafa351e4..d0dc666030 100644
--- a/doc/man3/BIO_s_bio.pod
+++ b/doc/man3/BIO_s_bio.pod
@@ -133,7 +133,7 @@ locations for B<bio1> and B<bio2>. Check the error stack for more information.
 
 [XXXXX: More return values need to be added here]
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 The BIO pair can be used to have full control over the network access of an
 application. The application can call select() on the socket as required
@@ -176,7 +176,7 @@ and must be transferred to the network. Use BIO_ctrl_get_read_request() to
 find out, how many bytes must be written into the buffer before the
 SSL_operation() can successfully be continued.
 
-=head1 WARNING
+=head1 WARNINGS
 
 As the data is buffered, SSL_operation() may return with an ERROR_SSL_WANT_READ
 condition, but there is still data in the write buffer. An application must
diff --git a/doc/man3/BIO_s_connect.pod b/doc/man3/BIO_s_connect.pod
index d5cc553f25..6b920f8f49 100644
--- a/doc/man3/BIO_s_connect.pod
+++ b/doc/man3/BIO_s_connect.pod
@@ -163,7 +163,7 @@ BIO_set_nbio() always returns 1.
 BIO_do_connect() returns 1 if the connection was successfully
 established and 0 or -1 if the connection failed.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 This is example connects to a webserver on the local host and attempts
 to retrieve a page and copy the result to standard output.
diff --git a/doc/man3/BIO_s_fd.pod b/doc/man3/BIO_s_fd.pod
index 8ebf563cf6..cdfe19f265 100644
--- a/doc/man3/BIO_s_fd.pod
+++ b/doc/man3/BIO_s_fd.pod
@@ -68,7 +68,7 @@ been initialized.
 BIO_new_fd() returns the newly allocated BIO or NULL is an error
 occurred.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 This is a file descriptor BIO version of "Hello World":
 
diff --git a/doc/man3/BIO_s_mem.pod b/doc/man3/BIO_s_mem.pod
index 6517177d4b..90c352b460 100644
--- a/doc/man3/BIO_s_mem.pod
+++ b/doc/man3/BIO_s_mem.pod
@@ -118,7 +118,16 @@ BIO_FLAGS_NONCLEAR_RST set has the same effect as a write operation.
 
 There should be an option to set the maximum size of a memory BIO.
 
-=head1 EXAMPLE
+=head1 RETURN VALUES
+
+BIO_s_mem() and BIO_s_secmem() return a valid memory B<BIO_METHOD> structure.
+
+BIO_set_mem_eof_return(), BIO_get_mem_data(), BIO_set_mem_buf() and BIO_get_mem_ptr()
+return 1 on success or a value which is less than or equal to 0 if an error occurred.
+
+BIO_new_mem_buf() returns a valid B<BIO> structure on success or NULL on error.
+
+=head1 EXAMPLES
 
 Create a memory BIO and write some data to it:
 
@@ -139,14 +148,6 @@ Extract the BUF_MEM structure from a memory BIO and then free up the BIO:
  BIO_set_close(mem, BIO_NOCLOSE); /* So BIO_free() leaves BUF_MEM alone */
  BIO_free(mem);
 
-=head1 RETURN VALUES
-
-BIO_s_mem() and BIO_s_secmem() return a valid memory B<BIO_METHOD> structure.
-
-BIO_set_mem_eof_return(), BIO_get_mem_data(), BIO_set_mem_buf() and BIO_get_mem_ptr()
-return 1 on success or a value which is less than or equal to 0 if an error occurred.
-
-BIO_new_mem_buf() returns a valid B<BIO> structure on success or NULL on error.
 
 =head1 COPYRIGHT
 
diff --git a/doc/man3/BIO_set_callback.pod b/doc/man3/BIO_set_callback.pod
index 0a9b6edb65..7f06e48d40 100644
--- a/doc/man3/BIO_set_callback.pod
+++ b/doc/man3/BIO_set_callback.pod
@@ -211,11 +211,6 @@ the actual call parameter, see B<BIO_callback_ctrl>.
 
 =back
 
-=head1 EXAMPLE
-
-The BIO_debug_callback() function is a good example, its source is
-in crypto/bio/bio_cb.c
-
 =head1 RETURN VALUES
 
 BIO_get_callback_ex() and BIO_get_callback() return the callback function
@@ -228,6 +223,11 @@ via a call to BIO_set_callback_arg().
 BIO_debug_callback() returns 1 or B<ret> if it's called after specific BIO
 operations.
 
+=head1 EXAMPLES
+
+The BIO_debug_callback() function is a good example, its source is
+in crypto/bio/bio_cb.c
+
 =head1 COPYRIGHT
 
 Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
diff --git a/doc/man3/BN_mod_mul_montgomery.pod b/doc/man3/BN_mod_mul_montgomery.pod
index 4dfcb21d9a..20c5975394 100644
--- a/doc/man3/BN_mod_mul_montgomery.pod
+++ b/doc/man3/BN_mod_mul_montgomery.pod
@@ -64,7 +64,7 @@ BN_MONT_CTX_free() has no return value.
 For the other functions, 1 is returned for success, 0 on error.
 The error codes can be obtained by L<ERR_get_error(3)>.
 
-=head1 WARNING
+=head1 WARNINGS
 
 The inputs must be reduced modulo B<m>, otherwise the result will be
 outside the expected range.
diff --git a/doc/man3/CRYPTO_THREAD_run_once.pod b/doc/man3/CRYPTO_THREAD_run_once.pod
index 3277613193..76d4be45be 100644
--- a/doc/man3/CRYPTO_THREAD_run_once.pod
+++ b/doc/man3/CRYPTO_THREAD_run_once.pod
@@ -97,7 +97,7 @@ one of the first included headers. Therefore it is defined as an
 application developer's responsibility to include windows.h prior to
 crypto.h where use of CRYPTO_THREAD_* types and functions is required.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 This example safely initializes and uses a lock.
 
diff --git a/doc/man3/EVP_DigestInit.pod b/doc/man3/EVP_DigestInit.pod
index 37bc10d380..f346d494bd 100644
--- a/doc/man3/EVP_DigestInit.pod
+++ b/doc/man3/EVP_DigestInit.pod
@@ -304,7 +304,7 @@ macros.
 EVP_MD_CTX_ctrl() sends commands to message digests for additional configuration
 or control.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 This example digests the data "Test Message\n" and "Hello World\n", using the
 digest name passed on the command line.
diff --git a/doc/man3/EVP_PKEY_CTX_set_hkdf_md.pod b/doc/man3/EVP_PKEY_CTX_set_hkdf_md.pod
index e8f19cfc99..45669e6a19 100644
--- a/doc/man3/EVP_PKEY_CTX_set_hkdf_md.pod
+++ b/doc/man3/EVP_PKEY_CTX_set_hkdf_md.pod
@@ -121,7 +121,7 @@ All these functions return 1 for success and 0 or a negative value for failure.
 In particular a return value of -2 indicates the operation is not supported by
 the public key algorithm.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 This example derives 10 bytes using SHA-256 with the secret key "secret",
 salt value "salt" and info value "label":
diff --git a/doc/man3/EVP_PKEY_CTX_set_tls1_prf_md.pod b/doc/man3/EVP_PKEY_CTX_set_tls1_prf_md.pod
index 30e50bc63e..59592c80cc 100644
--- a/doc/man3/EVP_PKEY_CTX_set_tls1_prf_md.pod
+++ b/doc/man3/EVP_PKEY_CTX_set_tls1_prf_md.pod
@@ -70,7 +70,7 @@ All these functions return 1 for success and 0 or a negative value for failure.
 In particular a return value of -2 indicates the operation is not supported by
 the public key algorithm.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 This example derives 10 bytes using SHA-256 with the secret key "secret"
 and seed value "seed":
diff --git a/doc/man3/EVP_PKEY_decrypt.pod b/doc/man3/EVP_PKEY_decrypt.pod
index 2e3d266541..879cff65ce 100644
--- a/doc/man3/EVP_PKEY_decrypt.pod
+++ b/doc/man3/EVP_PKEY_decrypt.pod
@@ -41,7 +41,7 @@ EVP_PKEY_decrypt_init() and EVP_PKEY_decrypt() return 1 for success and 0
 or a negative value for failure. In particular a return value of -2
 indicates the operation is not supported by the public key algorithm.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 Decrypt data using OAEP (for RSA keys):
 
diff --git a/doc/man3/EVP_PKEY_derive.pod b/doc/man3/EVP_PKEY_derive.pod
index a74065e31f..65bff3e20a 100644
--- a/doc/man3/EVP_PKEY_derive.pod
+++ b/doc/man3/EVP_PKEY_derive.pod
@@ -42,7 +42,7 @@ EVP_PKEY_derive_init() and EVP_PKEY_derive() return 1 for success and 0
 or a negative value for failure. In particular a return value of -2
 indicates the operation is not supported by the public key algorithm.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 Derive shared secret (for example DH or EC keys):
 
diff --git a/doc/man3/EVP_PKEY_encrypt.pod b/doc/man3/EVP_PKEY_encrypt.pod
index 3718910464..29b8cdb5e1 100644
--- a/doc/man3/EVP_PKEY_encrypt.pod
+++ b/doc/man3/EVP_PKEY_encrypt.pod
@@ -41,7 +41,7 @@ EVP_PKEY_encrypt_init() and EVP_PKEY_encrypt() return 1 for success and 0
 or a negative value for failure. In particular a return value of -2
 indicates the operation is not supported by the public key algorithm.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 Encrypt data using OAEP (for RSA keys). See also L<PEM_read_PUBKEY(3)> or
 L<d2i_X509(3)> for means to load a public key. You may also simply
diff --git a/doc/man3/EVP_PKEY_sign.pod b/doc/man3/EVP_PKEY_sign.pod
index 1672831ff0..7d84d3de76 100644
--- a/doc/man3/EVP_PKEY_sign.pod
+++ b/doc/man3/EVP_PKEY_sign.pod
@@ -46,7 +46,7 @@ EVP_PKEY_sign_init() and EVP_PKEY_sign() return 1 for success and 0
 or a negative value for failure. In particular a return value of -2
 indicates the operation is not supported by the public key algorithm.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 Sign data using RSA with PKCS#1 padding and SHA256 digest:
 
diff --git a/doc/man3/EVP_PKEY_verify.pod b/doc/man3/EVP_PKEY_verify.pod
index cdbb80b99d..95eb742cdb 100644
--- a/doc/man3/EVP_PKEY_verify.pod
+++ b/doc/man3/EVP_PKEY_verify.pod
@@ -44,7 +44,7 @@ A negative value indicates an error other that signature verification failure.
 In particular a return value of -2 indicates the operation is not supported by
 the public key algorithm.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 Verify signature using PKCS#1 and SHA256 digest:
 
diff --git a/doc/man3/EVP_PKEY_verify_recover.pod b/doc/man3/EVP_PKEY_verify_recover.pod
index 2513606561..9b12e3ea4b 100644
--- a/doc/man3/EVP_PKEY_verify_recover.pod
+++ b/doc/man3/EVP_PKEY_verify_recover.pod
@@ -49,7 +49,7 @@ EVP_PKEY_verify_recover_init() and EVP_PKEY_verify_recover() return 1 for succes
 and 0 or a negative value for failure. In particular a return value of -2
 indicates the operation is not supported by the public key algorithm.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 Recover digest originally signed using PKCS#1 and SHA256 digest:
 
diff --git a/doc/man3/OCSP_REQUEST_new.pod b/doc/man3/OCSP_REQUEST_new.pod
index a382b16ed3..ee9b21bfee 100644
--- a/doc/man3/OCSP_REQUEST_new.pod
+++ b/doc/man3/OCSP_REQUEST_new.pod
@@ -75,7 +75,7 @@ corresponding to each certificate.
 OCSP_request_onereq_count() and OCSP_request_onereq_get0() are mainly used by
 OCSP responders.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 Create an B<OCSP_REQUEST> structure for certificate B<cert> with issuer
 B<issuer>:
diff --git a/doc/man3/PKCS12_newpass.pod b/doc/man3/PKCS12_newpass.pod
index 1c34ee5449..335fb04fcd 100644
--- a/doc/man3/PKCS12_newpass.pod
+++ b/doc/man3/PKCS12_newpass.pod
@@ -34,7 +34,7 @@ L<UI_OpenSSL(3)>, for example.
 PKCS12_newpass() returns 1 on success or 0 on failure. Applications can
 retrieve the most recent error from PKCS12_newpass() with ERR_get_error().
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 This example loads a PKCS#12 file, changes its password and writes out
 the result to a new file.
diff --git a/doc/man3/RSA_padding_add_PKCS1_type_1.pod b/doc/man3/RSA_padding_add_PKCS1_type_1.pod
index 407eec8c90..d0d42ce265 100644
--- a/doc/man3/RSA_padding_add_PKCS1_type_1.pod
+++ b/doc/man3/RSA_padding_add_PKCS1_type_1.pod
@@ -123,7 +123,7 @@ The RSA_padding_check_xxx() functions return the length of the
 recovered data, -1 on error. Error codes can be obtained by calling
 L<ERR_get_error(3)>.
 
-=head1 WARNING
+=head1 WARNINGS
 
 The result of RSA_padding_check_PKCS1_type_2() is a very sensitive
 information which can potentially be used to mount a Bleichenbacher
diff --git a/doc/man3/RSA_public_encrypt.pod b/doc/man3/RSA_public_encrypt.pod
index d91c6884b1..384c4823cb 100644
--- a/doc/man3/RSA_public_encrypt.pod
+++ b/doc/man3/RSA_public_encrypt.pod
@@ -81,7 +81,7 @@ means only that the plaintext was empty.
 On error, -1 is returned; the error codes can be
 obtained by L<ERR_get_error(3)>.
 
-=head1 WARNING
+=head1 WARNINGS
 
 Decryption failures in the RSA_PKCS1_PADDING mode leak information
 which can potentially be used to mount a Bleichenbacher padding oracle
diff --git a/doc/man3/SSL_CTX_config.pod b/doc/man3/SSL_CTX_config.pod
index 90d86746ce..398a0d5139 100644
--- a/doc/man3/SSL_CTX_config.pod
+++ b/doc/man3/SSL_CTX_config.pod
@@ -33,7 +33,7 @@ file syntax.
 SSL_CTX_config() and SSL_config() return 1 for success or 0 if an error
 occurred.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 If the file "config.cnf" contains the following:
 
diff --git a/doc/man3/SSL_CTX_dane_enable.pod b/doc/man3/SSL_CTX_dane_enable.pod
index d1b3c1aad7..73572971a9 100644
--- a/doc/man3/SSL_CTX_dane_enable.pod
+++ b/doc/man3/SSL_CTX_dane_enable.pod
@@ -181,7 +181,7 @@ The functions SSL_CTX_dane_set_flags(), SSL_CTX_dane_clear_flags(),
 SSL_dane_set_flags() and SSL_dane_clear_flags() return the B<flags> in effect
 before they were called.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 Suppose "smtp.example.com" is the MX host of the domain "example.com", and has
 DNSSEC-validated TLSA records.
diff --git a/doc/man3/SSL_CTX_get0_param.pod b/doc/man3/SSL_CTX_get0_param.pod
index 8b99dc330a..37dc130f05 100644
--- a/doc/man3/SSL_CTX_get0_param.pod
+++ b/doc/man3/SSL_CTX_get0_param.pod
@@ -29,13 +29,6 @@ Typically parameters are retrieved from an B<SSL_CTX> or B<SSL> structure
 using SSL_CTX_get0_param() or SSL_get0_param() and an application modifies
 them to suit its needs: for example to add a hostname check.
 
-=head1 EXAMPLE
-
-Check hostname matches "www.foo.com" in peer certificate:
-
- X509_VERIFY_PARAM *vpm = SSL_get0_param(ssl);
- X509_VERIFY_PARAM_set1_host(vpm, "www.foo.com", 0);
-
 =head1 RETURN VALUES
 
 SSL_CTX_get0_param() and SSL_get0_param() return a pointer to an
@@ -44,6 +37,13 @@ B<X509_VERIFY_PARAM> structure.
 SSL_CTX_set1_param() and SSL_set1_param() return 1 for success and 0
 for failure.
 
+=head1 EXAMPLES
+
+Check hostname matches "www.foo.com" in peer certificate:
+
+ X509_VERIFY_PARAM *vpm = SSL_get0_param(ssl);
+ X509_VERIFY_PARAM_set1_host(vpm, "www.foo.com", 0);
+
 =head1 SEE ALSO
 
 L<X509_VERIFY_PARAM_set_flags(3)>
diff --git a/doc/man3/SSL_library_init.pod b/doc/man3/SSL_library_init.pod
index 85768a1028..d0c11724ba 100644
--- a/doc/man3/SSL_library_init.pod
+++ b/doc/man3/SSL_library_init.pod
@@ -25,7 +25,7 @@ implemented as a macro.
 SSL_library_init() must be called before any other action takes place.
 SSL_library_init() is not reentrant.
 
-=head1 WARNING
+=head1 WARNINGS
 
 SSL_library_init() adds ciphers and digests used directly and indirectly by
 SSL/TLS.
diff --git a/doc/man3/SSL_set1_host.pod b/doc/man3/SSL_set1_host.pod
index a2c9f133ee..d1e540851e 100644
--- a/doc/man3/SSL_set1_host.pod
+++ b/doc/man3/SSL_set1_host.pod
@@ -71,7 +71,7 @@ applicable (as with RFC7671 DANE-EE(3)), or no trusted peername was
 matched.  Otherwise, it returns the matched peername.  To determine
 whether verification succeeded call L<SSL_get_verify_result(3)>.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 Suppose "smtp.example.com" is the MX host of the domain "example.com".
 The calls below will arrange to match either the MX hostname or the
diff --git a/doc/man3/SSL_write.pod b/doc/man3/SSL_write.pod
index 84eb948cc6..a76ffbb8fd 100644
--- a/doc/man3/SSL_write.pod
+++ b/doc/man3/SSL_write.pod
@@ -57,7 +57,7 @@ operation is considered completed. The bytes are sent and a new write call with
 a new buffer (with the already sent bytes removed) must be started. A partial
 write is performed with the size of a message block, which is 16kB.
 
-=head1 WARNING
+=head1 WARNINGS
 
 When a write function call has to be repeated because L<SSL_get_error(3)>
 returned B<SSL_ERROR_WANT_READ> or B<SSL_ERROR_WANT_WRITE>, it must be repeated
diff --git a/doc/man3/X509_STORE_CTX_set_verify_cb.pod b/doc/man3/X509_STORE_CTX_set_verify_cb.pod
index 647ed2f174..8fe4655325 100644
--- a/doc/man3/X509_STORE_CTX_set_verify_cb.pod
+++ b/doc/man3/X509_STORE_CTX_set_verify_cb.pod
@@ -76,7 +76,7 @@ from the corresponding B<X509_STORE>, please see
 L<X509_STORE_set_verify(3)> for more information.
 
 
-=head1 WARNING
+=head1 WARNINGS
 
 In general a verification callback should B<NOT> unconditionally return 1 in
 all circumstances because this will allow verification to succeed no matter
diff --git a/doc/man3/X509_VERIFY_PARAM_set_flags.pod b/doc/man3/X509_VERIFY_PARAM_set_flags.pod
index f45467cace..2b20dae6f6 100644
--- a/doc/man3/X509_VERIFY_PARAM_set_flags.pod
+++ b/doc/man3/X509_VERIFY_PARAM_set_flags.pod
@@ -346,7 +346,7 @@ If CRLs checking is enable CRLs are expected to be available in the
 corresponding B<X509_STORE> structure. No attempt is made to download
 CRLs from the CRL distribution points extension.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 Enable CRL checking when performing certificate verification during SSL
 connections associated with an B<SSL_CTX> structure B<ctx>:
diff --git a/doc/man5/x509v3_config.pod b/doc/man5/x509v3_config.pod
index a35b4ccfff..06d0aea974 100644
--- a/doc/man5/x509v3_config.pod
+++ b/doc/man5/x509v3_config.pod
@@ -483,7 +483,7 @@ For example:
 
  basicConstraints=critical,DER:00:01:02:03
 
-=head1 WARNING
+=head1 WARNINGS
 
 There is no guarantee that a specific implementation will process a given
 extension. It may therefore be sometimes possible to use certificates for
@@ -493,7 +493,6 @@ not recognize or honour the values of the relevant extensions.
 The DER and ASN1 options should be used with caution. It is possible to create
 totally invalid extensions if they are not used carefully.
 
-
 =head1 NOTES
 
 If an extension is multi-value and a field value must contain a comma the long
diff --git a/doc/man7/Ed25519.pod b/doc/man7/Ed25519.pod
index 3f54217918..fd04dbb2d1 100644
--- a/doc/man7/Ed25519.pod
+++ b/doc/man7/Ed25519.pod
@@ -53,7 +53,7 @@ Ed25519 and Ed448 can be tested within L<speed(1)> application since version 1.1
 Valid algorithm names are B<ed25519>, B<ed448> and B<eddsa>. If B<eddsa> is
 specified, then both Ed25519 and Ed448 are benchmarked.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 This example generates an B<ED25519> private key and writes it to standard
 output in PEM format:
diff --git a/doc/man7/SM2.pod b/doc/man7/SM2.pod
index 029dc736cb..0cd6ad0aa2 100644
--- a/doc/man7/SM2.pod
+++ b/doc/man7/SM2.pod
@@ -41,7 +41,7 @@ done by calling:
 And normally there is no need to pass a B<pctx> parameter to EVP_DigestSignInit()
 or EVP_DigestVerifyInit() in such a scenario.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 This example demonstrates the calling sequence for using an B<EVP_PKEY> to verify
 a message with the SM2 signature algorithm and the SM3 hash algorithm:
diff --git a/doc/man7/X25519.pod b/doc/man7/X25519.pod
index 7cb6ff6b3b..cdb56599d1 100644
--- a/doc/man7/X25519.pod
+++ b/doc/man7/X25519.pod
@@ -37,7 +37,7 @@ X25519 or X448 public keys can be set directly using
 L<EVP_PKEY_new_raw_public_key(3)> or loaded from a SubjectPublicKeyInfo
 structure in a PEM file using L<PEM_read_bio_PUBKEY(3)> (or similar function).
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 This example generates an B<X25519> private key and writes it to standard
 output in PEM format:
diff --git a/doc/man7/bio.pod b/doc/man7/bio.pod
index 45ef2f7704..98f2caa4e7 100644
--- a/doc/man7/bio.pod
+++ b/doc/man7/bio.pod
@@ -52,7 +52,7 @@ pointer to a BIO_METHOD. There is a naming convention for such functions:
 a source/sink BIO is normally called BIO_s_*() and a filter BIO
 BIO_f_*();
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 Create a memory BIO:
 
diff --git a/doc/man7/scrypt.pod b/doc/man7/scrypt.pod
index 94ff3ab53f..89a816e625 100644
--- a/doc/man7/scrypt.pod
+++ b/doc/man7/scrypt.pod
@@ -38,7 +38,7 @@ A context for scrypt can be obtained by calling:
 The output length of an scrypt key derivation is specified via the
 length parameter to the L<EVP_PKEY_derive(3)> function.
 
-=head1 EXAMPLE
+=head1 EXAMPLES
 
 This example derives a 64-byte long test vector using scrypt using the password
 "password", salt "NaCl" and N = 1024, r = 8, p = 16.
diff --git a/util/find-doc-nits b/util/find-doc-nits
index 7340782662..699887a267 100755
--- a/util/find-doc-nits
+++ b/util/find-doc-nits
@@ -137,17 +137,17 @@ sub name_synopsis()
     }
 }
 
-# Check if SECTION is located before BEFORE
+# Check if SECTION ($3) is located before BEFORE ($4)
 sub check_section_location()
 {
-    my $filename = shift;
+    my $id = shift;
     my $contents = shift;
     my $section = shift;
     my $before = shift;
 
-    return unless $contents =~ /=head1 $section/
-        and $contents =~ /=head1 $before/;
-    print "$filename: $section should be placed before $before section\n"
+    return
+        unless $contents =~ /=head1 $section/ and $contents =~ /=head1 $before/;
+    print "$id $section should be placed before $before section\n"
         if $contents =~ /=head1 $before.*=head1 $section/ms;
 }
 
@@ -164,15 +164,15 @@ sub check()
         close POD;
     }
 
-    # Check if EXAMPLES is located after RETURN VALUES section.
-    &check_section_location($filename, $contents, "RETURN VALUES", "EXAMPLES") if $filename =~ m|man3/|;
-    # Check if HISTORY is located after SEE ALSO
-    &check_section_location($filename, $contents, "SEE ALSO", "HISTORY") if $filename =~ m|man3/|;
-    # Check if SEE ALSO is located after EXAMPLES
-    &check_section_location($filename, $contents, "EXAMPLES", "SEE ALSO") if $filename =~ m|man3/|;
-
     my $id = "${filename}:1:";
 
+    # Check ordering of some sections in man3
+    if ( $filename =~ m|man3/| ) {
+        &check_section_location($id, $contents, "RETURN VALUES", "EXAMPLES");
+        &check_section_location($id, $contents, "SEE ALSO", "HISTORY");
+        &check_section_location($id, $contents, "EXAMPLES", "SEE ALSO");
+    }
+
     &name_synopsis($id, $filename, $contents)
         unless $contents =~ /=for comment generic/
             or $filename =~ m at man[157]/@;
@@ -183,6 +183,10 @@ sub check()
         if $contents !~ /=cut\n$/;
     print "$id more than one cut line.\n"
         if $contents =~ /=cut.*=cut/ms;
+    print "$id EXAMPLE not EXAMPLES section.\n"
+        if $contents =~ /=head1 EXAMPLE[^S]/;
+    print "$id WARNING not WARNINGS section.\n"
+        if $contents =~ /=head1 WARNING[^S]/;
     print "$id missing copyright\n"
         if $contents !~ /Copyright .* The OpenSSL Project Authors/;
     print "$id copyright not last\n"


More information about the openssl-commits mailing list