The branch master has been updated
via 5e0d9c861bc44070c61b9b109884dc8aa5e2e8d1 (commit)
via cda774223d9a886ece480f304be40797bb73bcd7 (commit)
via 39a117d17963d0cd4a8f3a3351c0844c325e905c (commit)
from e0249827b3fa81ff6c59fb14ef85d38361dd5e31 (commit)
- Log -----------------------------------------------------------------
commit 5e0d9c861bc44070c61b9b109884dc8aa5e2e8d1
Author: Rich Salz <rs...@akamai.com>
Date: Sun Aug 18 11:38:25 2019 -0400
Use WARNINGS heading not WARNING
Also update find-doc-nits to reject "=head1 WARNING"
Reviewed-by: Richard Levitte <levi...@openssl.org>
Reviewed-by: Matthias St. Pierre <matthias.st.pie...@ncp-e.com>
(Merged from https://github.com/openssl/openssl/pull/9602)
commit cda774223d9a886ece480f304be40797bb73bcd7
Author: Rich Salz <rs...@akamai.com>
Date: Thu Aug 15 14:26:08 2019 -0400
Use EXAMPLES not EXAMPLE for section title
And update find-doc-nits to complain if "=head1 EXAMPLE" is found.
Reviewed-by: Richard Levitte <levi...@openssl.org>
Reviewed-by: Matthias St. Pierre <matthias.st.pie...@ncp-e.com>
(Merged from https://github.com/openssl/openssl/pull/9602)
commit 39a117d17963d0cd4a8f3a3351c0844c325e905c
Author: Rich Salz <rs...@akamai.com>
Date: Thu Aug 15 13:52:41 2019 -0400
Fix some pod-page ordering nits
The find-doc-nits script only looked for EXAMPLES, not EXAMPLE.
Fix the pattern and then fix the errors that resulted.
Reviewed-by: Richard Levitte <levi...@openssl.org>
Reviewed-by: Matthias St. Pierre <matthias.st.pie...@ncp-e.com>
(Merged from https://github.com/openssl/openssl/pull/9602)
-----------------------------------------------------------------------
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_MAC.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/OSSL_CMP_ITAV_set0.pod | 2 +-
doc/man3/OSSL_CRMF_pbmp_new.pod | 2 +-
doc/man3/OSSL_PARAM_construct_from_text.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/EVP_KDF_HKDF.pod | 2 +-
doc/man7/EVP_KDF_SCRYPT.pod | 2 +-
doc/man7/EVP_KDF_SS.pod | 6 +----
doc/man7/EVP_KDF_SSHKDF.pod | 2 +-
doc/man7/EVP_KDF_TLS1_PRF.pod | 2 +-
doc/man7/EVP_KDF_X942.pod | 2 +-
doc/man7/EVP_KDF_X963.pod | 2 +-
doc/man7/Ed25519.pod | 2 +-
doc/man7/SM2.pod | 2 +-
doc/man7/X25519.pod | 2 +-
doc/man7/bio.pod | 2 +-
util/find-doc-nits | 28 ++++++++++++----------
53 files changed, 105 insertions(+), 105 deletions(-)
diff --git a/doc/man1/engine.pod b/doc/man1/engine.pod
index 446b1981b6..e0f881ae9c 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 ba6fc81496..9ba20914a9 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 048a1f2e8b..32dbe51e89 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 5ac368d3ff..c8c30bfed6 100644
--- a/doc/man3/ASYNC_start_job.pod
+++ b/doc/man3/ASYNC_start_job.pod
@@ -174,7 +174,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 ba44133023..82bb16c5ba 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 7a84b6de85..354e347330 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 db1e06069d..d75e63bbec 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 c50d32f931..e6ad95b4e0 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 a45715390f..0f4ea77d6d 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 eb11557b64..01fae195fc 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 c9d29bc612..f4f4239fe9 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 7cb9efa92c..b7c6fdf860 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 a420267a4c..9537a2e168 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 bb11c426c0..5cb2c2c377 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 8ccd05e5e7..ee413e7672 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 1cc07b159e..bdc48c3a4b 100644
--- a/doc/man3/EVP_DigestInit.pod
+++ b/doc/man3/EVP_DigestInit.pod
@@ -494,7 +494,7 @@ as 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_MAC.pod b/doc/man3/EVP_MAC.pod
index 6cc28a7355..4358ca319a 100644
--- a/doc/man3/EVP_MAC.pod
+++ b/doc/man3/EVP_MAC.pod
@@ -272,7 +272,7 @@ If it isn't set, a call to EVP_MAC_init() should get it set.
EVP_MAC_do_all_ex() returns nothing at all.
-=head1 EXAMPLE
+=head1 EXAMPLES
#include <stdlib.h>
#include <stdio.h>
diff --git a/doc/man3/EVP_PKEY_CTX_set_hkdf_md.pod
b/doc/man3/EVP_PKEY_CTX_set_hkdf_md.pod
index 72a5b0ff51..7fc833e056 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 cc87c00ae1..e0629accc7 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 a2363af206..a78c1ee8e4 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 8d5432688b..d6516e7933 100644
--- a/doc/man3/EVP_PKEY_derive.pod
+++ b/doc/man3/EVP_PKEY_derive.pod
@@ -56,7 +56,7 @@ 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 1e9742de7a..73ca8bae3e 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 b9211b83db..d48edb5025 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 5b0d15a755..0212202514 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 22538fd01a..2b425a3852 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 db670dca8d..e9d260fec1 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/OSSL_CMP_ITAV_set0.pod b/doc/man3/OSSL_CMP_ITAV_set0.pod
index 082b0bfe76..348f47f1b6 100644
--- a/doc/man3/OSSL_CMP_ITAV_set0.pod
+++ b/doc/man3/OSSL_CMP_ITAV_set0.pod
@@ -59,7 +59,7 @@ return the respective pointer or NULL if their input is NULL.
OSSL_CMP_ITAV_push0_stack_item() returns 1 on success, 0 on error.
-=head1 EXAMPLE
+=head1 EXAMPLES
The following code creates and sets a structure representing a generic
InfoTypeAndValue sequence, using an OID created from text as type, and an
diff --git a/doc/man3/OSSL_CRMF_pbmp_new.pod b/doc/man3/OSSL_CRMF_pbmp_new.pod
index cdd30ffca1..4ebfa69d46 100644
--- a/doc/man3/OSSL_CRMF_pbmp_new.pod
+++ b/doc/man3/OSSL_CRMF_pbmp_new.pod
@@ -49,7 +49,7 @@ OSSL_CRMF_pbm_new() returns 1 on success, 0 on error.
OSSL_CRMF_pbmp_new() returns a new and initialized OSSL_CRMF_PBMPARAMETER
structure, or NULL on error.
-=head1 EXAMPLE
+=head1 EXAMPLES
OSSL_CRMF_PBMPARAMETER *pbm = NULL;
unsigned char *msg = "Hello";
diff --git a/doc/man3/OSSL_PARAM_construct_from_text.pod
b/doc/man3/OSSL_PARAM_construct_from_text.pod
index 5dc08bd325..6c7ff81ef4 100644
--- a/doc/man3/OSSL_PARAM_construct_from_text.pod
+++ b/doc/man3/OSSL_PARAM_construct_from_text.pod
@@ -81,7 +81,7 @@ All other attributes are ignored.
The I<data_size> attribute can be zero, meaning that the parameter it
describes expects arbitrary length data.
-=head1 EXAMPLE
+=head1 EXAMPLES
Code that looked like this:
diff --git a/doc/man3/PKCS12_newpass.pod b/doc/man3/PKCS12_newpass.pod
index 14cfcdf185..491fbcbbee 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 40eb8f94a9..6e679bba0f 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 9c75944cae..09f26ebc07 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 a05009e542..dfdc3d210d 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 f051c5a3eb..c43d6f90dc 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 ff9706455f..19e7f189a2 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 ff49a83e6f..1b56c3b8aa 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 3fc6ec37d5..98bc6fd48c 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 04cc46b27a..56a8c8b172 100644
--- a/doc/man3/SSL_write.pod
+++ b/doc/man3/SSL_write.pod
@@ -66,7 +66,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 6e4624671f..64ccefa7ff 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 d8ee7f671f..1b5aaa62ca 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 b8fc00ed2d..f9e4b1f7aa 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/EVP_KDF_HKDF.pod b/doc/man7/EVP_KDF_HKDF.pod
index 2188b136f1..c511c7c705 100644
--- a/doc/man7/EVP_KDF_HKDF.pod
+++ b/doc/man7/EVP_KDF_HKDF.pod
@@ -126,7 +126,7 @@ the intermediate fixed-length pseudorandom key otherwise an
error will occur.
For that mode, the fixed output size can be looked up by calling EVP_KDF_size()
after setting the mode and digest on the C<EVP_KDF_CTX>.
-=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/man7/EVP_KDF_SCRYPT.pod b/doc/man7/EVP_KDF_SCRYPT.pod
index a44dc63dec..aa50164e06 100644
--- a/doc/man7/EVP_KDF_SCRYPT.pod
+++ b/doc/man7/EVP_KDF_SCRYPT.pod
@@ -78,7 +78,7 @@ A context for scrypt can be obtained by calling:
The output length of an scrypt key derivation is specified via the
B<keylen> parameter to the L<EVP_KDF_derive(3)> function.
-=head1 EXAMPLE
+=head1 EXAMPLES
This example derives a 64-byte long test vector using scrypt with the password
"password", salt "NaCl" and N = 1024, r = 8, p = 16.
diff --git a/doc/man7/EVP_KDF_SS.pod b/doc/man7/EVP_KDF_SS.pod
index 958089d24a..5c56fbd1b0 100644
--- a/doc/man7/EVP_KDF_SS.pod
+++ b/doc/man7/EVP_KDF_SS.pod
@@ -102,7 +102,7 @@ EVP_KDF_CTX *kctx = EVP_KDF_CTX_new_id(EVP_KDF_SS);
The output length of an SSKDF is specified via the C<keylen>
parameter to the L<EVP_KDF_derive(3)> function.
-=head1 EXAMPLE
+=head1 EXAMPLES
This example derives 10 bytes using H(x) = SHA-256, with the secret key
"secret"
and fixedinfo value "label":
@@ -127,8 +127,6 @@ and fixedinfo value "label":
EVP_KDF_CTX_free(kctx);
-=head1 EXAMPLE
-
This example derives 10 bytes using H(x) = HMAC(SHA-256), with the secret key
"secret",
fixedinfo value "label" and salt "salt":
@@ -158,8 +156,6 @@ fixedinfo value "label" and salt "salt":
EVP_KDF_CTX_free(kctx);
-=head1 EXAMPLE
-
This example derives 10 bytes using H(x) = KMAC128(x,salt,outlen), with the
secret key "secret"
fixedinfo value "label", salt of "salt" and KMAC outlen of 20:
diff --git a/doc/man7/EVP_KDF_SSHKDF.pod b/doc/man7/EVP_KDF_SSHKDF.pod
index e233e86f03..04a646c866 100644
--- a/doc/man7/EVP_KDF_SSHKDF.pod
+++ b/doc/man7/EVP_KDF_SSHKDF.pod
@@ -120,7 +120,7 @@ to obtain the requisite length is not meaningful. The
caller must
allocate a buffer of the desired length, and pass that buffer to the
L<EVP_KDF_derive(3)> function along with the desired length.
-=head1 EXAMPLE
+=head1 EXAMPLES
This example derives an 8 byte IV using SHA-256 with a 1K "key" and appropriate
"xcghash" and "session_id" values:
diff --git a/doc/man7/EVP_KDF_TLS1_PRF.pod b/doc/man7/EVP_KDF_TLS1_PRF.pod
index 4c73139546..02331ece5e 100644
--- a/doc/man7/EVP_KDF_TLS1_PRF.pod
+++ b/doc/man7/EVP_KDF_TLS1_PRF.pod
@@ -97,7 +97,7 @@ an error will occur.
The output length of the PRF is specified by the C<keylen> parameter to the
EVP_KDF_derive() function.
-=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/man7/EVP_KDF_X942.pod b/doc/man7/EVP_KDF_X942.pod
index df93e861f9..644cad8cbe 100644
--- a/doc/man7/EVP_KDF_X942.pod
+++ b/doc/man7/EVP_KDF_X942.pod
@@ -90,7 +90,7 @@ EVP_KDF_CTX *kctx = EVP_KDF_CTX_new_id(EVP_KDF_X942);
The output length of an X942KDF is specified via the C<keylen>
parameter to the L<EVP_KDF_derive(3)> function.
-=head1 EXAMPLE
+=head1 EXAMPLES
This example derives 24 bytes, with the secret key "secret" and a random user
keying material:
diff --git a/doc/man7/EVP_KDF_X963.pod b/doc/man7/EVP_KDF_X963.pod
index 77b878f6ba..130c9235a9 100644
--- a/doc/man7/EVP_KDF_X963.pod
+++ b/doc/man7/EVP_KDF_X963.pod
@@ -81,7 +81,7 @@ EVP_KDF_CTX *kctx = EVP_KDF_CTX_new_id(EVP_KDF_X963);
The output length of an X963KDF is specified via the C<keylen>
parameter to the L<EVP_KDF_derive(3)> function.
-=head1 EXAMPLE
+=head1 EXAMPLES
This example derives 10 bytes, with the secret key "secret" and sharedinfo
value "label":
diff --git a/doc/man7/Ed25519.pod b/doc/man7/Ed25519.pod
index 12bc64b3f7..8269f2feaa 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 05c8a345fd..31f58db416 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 7f0bdff276..6af40c6afe 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 18f1125045..bc1fb1e45e 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/util/find-doc-nits b/util/find-doc-nits
index 499a68fdc4..1b9a2333a3 100755
--- a/util/find-doc-nits
+++ b/util/find-doc-nits
@@ -151,17 +151,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;
}
@@ -178,15 +178,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@man[157]/@;
@@ -197,6 +197,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"
