[openssl] master update
Richard Levitte
levitte at openssl.org
Wed Jan 13 22:40:51 UTC 2021
The branch master has been updated
via 879365e6d4a53d80e83bbe468fcf2cdd02d30ba1 (commit)
from 0f2380066de6436c0e8debfad1391db134ad4c25 (commit)
- Log -----------------------------------------------------------------
commit 879365e6d4a53d80e83bbe468fcf2cdd02d30ba1
Author: Richard Levitte <levitte at openssl.org>
Date: Tue Jan 12 15:44:43 2021 +0100
Make header references conform with man-pages(7) in all manuals
Details from man-pages(7) that are used:
Formatting conventions (general)
...
Filenames (whether pathnames, or references to header files) are always
in italics (e.g., <stdio.h>), except in the SYNOPSIS section, where in‐
cluded files are in bold (e.g., #include <stdio.h>). When referring to
a standard header file include, specify the header file surrounded by
angle brackets, in the usual C way (e.g., <stdio.h>).
...
Reviewed-by: Tomas Mraz <tmraz at fedoraproject.org>
(Merged from https://github.com/openssl/openssl/pull/13843)
-----------------------------------------------------------------------
Summary of changes:
doc/man3/ASYNC_WAIT_CTX_new.pod | 6 +++---
doc/man3/ASYNC_start_job.pod | 6 +++---
doc/man3/BIO_find_type.pod | 2 +-
doc/man3/BIO_meth_new.pod | 14 +++++++-------
doc/man3/CRYPTO_THREAD_run_once.pod | 13 +++++++------
doc/man3/CRYPTO_get_ex_new_index.pod | 4 ++--
doc/man3/EC_GROUP_copy.pod | 4 ++--
doc/man3/ENGINE_add.pod | 10 +++++-----
doc/man3/OSSL_CRMF_pbmp_new.pod | 2 +-
doc/man3/OSSL_PARAM_BLD.pod | 2 +-
doc/man3/OSSL_trace_enabled.pod | 2 +-
doc/man3/OSSL_trace_set_channel.pod | 2 +-
doc/man3/SSL_CTX_set_tlsext_ticket_key_cb.pod | 2 +-
doc/man3/SSL_get_all_async_fds.pod | 6 +++---
doc/man3/X509_NAME_get_index_by_NID.pod | 4 ++--
doc/man3/X509_verify_cert.pod | 4 ++--
16 files changed, 42 insertions(+), 41 deletions(-)
diff --git a/doc/man3/ASYNC_WAIT_CTX_new.pod b/doc/man3/ASYNC_WAIT_CTX_new.pod
index f1d6a02219..d6e5d38a12 100644
--- a/doc/man3/ASYNC_WAIT_CTX_new.pod
+++ b/doc/man3/ASYNC_WAIT_CTX_new.pod
@@ -192,12 +192,12 @@ ASYNC_WAIT_CTX_get_status() returns the engine status.
=head1 NOTES
-On Windows platforms the openssl/async.h header is dependent on some
-of the types customarily made available by including windows.h. The
+On Windows platforms the F<< <openssl/async.h> >> header is dependent on some
+of the types customarily made available by including F<< <windows.h> >>. The
application developer is likely to require control over when the latter
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.
+F<< <windows.h> >> prior to F<< <openssl/async.h> >>.
=head1 SEE ALSO
diff --git a/doc/man3/ASYNC_start_job.pod b/doc/man3/ASYNC_start_job.pod
index 983fcf9cf4..5335ae281c 100644
--- a/doc/man3/ASYNC_start_job.pod
+++ b/doc/man3/ASYNC_start_job.pod
@@ -167,12 +167,12 @@ otherwise.
=head1 NOTES
-On Windows platforms the openssl/async.h header is dependent on some
-of the types customarily made available by including windows.h. The
+On Windows platforms the F<< <openssl/async.h> >> header is dependent on some
+of the types customarily made available by including F<< <windows.h> >>. The
application developer is likely to require control over when the latter
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.
+F<< <windows.h> >> prior to F<< <openssl/async.h> >>.
=head1 EXAMPLES
diff --git a/doc/man3/BIO_find_type.pod b/doc/man3/BIO_find_type.pod
index 354e347330..32a97c55f1 100644
--- a/doc/man3/BIO_find_type.pod
+++ b/doc/man3/BIO_find_type.pod
@@ -24,7 +24,7 @@ found.
The following general types are defined:
B<BIO_TYPE_DESCRIPTOR>, B<BIO_TYPE_FILTER>, and B<BIO_TYPE_SOURCE_SINK>.
-For a list of the specific types, see the B<openssl/bio.h> header file.
+For a list of the specific types, see the F<< <openssl/bio.h> >> header file.
BIO_next() returns the next BIO in a chain. It can be used to traverse all BIOs
in a chain or used in conjunction with BIO_find_type() to find all BIOs of a
diff --git a/doc/man3/BIO_meth_new.pod b/doc/man3/BIO_meth_new.pod
index b2e2c24692..a2c2848a96 100644
--- a/doc/man3/BIO_meth_new.pod
+++ b/doc/man3/BIO_meth_new.pod
@@ -67,13 +67,13 @@ unique integer B<type> and a string that represents its B<name>.
Use BIO_get_new_index() to get the value for B<type>.
The set of
-standard OpenSSL provided BIO types is provided in B<bio.h>. Some examples
-include B<BIO_TYPE_BUFFER> and B<BIO_TYPE_CIPHER>. Filter BIOs should have a
-type which have the "filter" bit set (B<BIO_TYPE_FILTER>). Source/sink BIOs
-should have the "source/sink" bit set (B<BIO_TYPE_SOURCE_SINK>). File descriptor
-based BIOs (e.g. socket, fd, connect, accept etc) should additionally have the
-"descriptor" bit set (B<BIO_TYPE_DESCRIPTOR>). See the L<BIO_find_type(3)> page for
-more information.
+standard OpenSSL provided BIO types is provided in F<< <openssl/bio.h> >>.
+Some examples include B<BIO_TYPE_BUFFER> and B<BIO_TYPE_CIPHER>. Filter BIOs
+should have a type which have the "filter" bit set (B<BIO_TYPE_FILTER>).
+Source/sink BIOs should have the "source/sink" bit set (B<BIO_TYPE_SOURCE_SINK>).
+File descriptor based BIOs (e.g. socket, fd, connect, accept etc) should
+additionally have the "descriptor" bit set (B<BIO_TYPE_DESCRIPTOR>). See the
+L<BIO_find_type(3)> page for more information.
BIO_meth_free() destroys a B<BIO_METHOD> structure and frees up any memory
associated with it.
diff --git a/doc/man3/CRYPTO_THREAD_run_once.pod b/doc/man3/CRYPTO_THREAD_run_once.pod
index a182359f47..3a46809efe 100644
--- a/doc/man3/CRYPTO_THREAD_run_once.pod
+++ b/doc/man3/CRYPTO_THREAD_run_once.pod
@@ -113,12 +113,13 @@ The other functions return 1 on success, or 0 on error.
=head1 NOTES
On Windows platforms the CRYPTO_THREAD_* types and functions in the
-openssl/crypto.h header are dependent on some of the types customarily
-made available by including windows.h. The application developer is
-likely to require control over when the latter 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
-crypto.h where use of CRYPTO_THREAD_* types and functions is required.
+F<< <openssl/crypto.h> >> header are dependent on some of the types
+customarily made available by including F<< <windows.h> >>. The application
+developer is likely to require control over when the latter is included,
+commonly as one of the first included headers. Therefore, it is defined as an
+application developer's responsibility to include F<< <windows.h> >> prior to
+F<< <openssl/crypto.h> >> where use of CRYPTO_THREAD_* types and functions is
+required.
=head1 EXAMPLES
diff --git a/doc/man3/CRYPTO_get_ex_new_index.pod b/doc/man3/CRYPTO_get_ex_new_index.pod
index 463e2c8646..d53fe8c792 100644
--- a/doc/man3/CRYPTO_get_ex_new_index.pod
+++ b/doc/man3/CRYPTO_get_ex_new_index.pod
@@ -62,8 +62,8 @@ The specific structures are:
In addition, the B<APP> name is reserved for use by application code.
-Each is identified by an B<CRYPTO_EX_INDEX_xxx> define in the B<crypto.h>
-header file. In addition, B<CRYPTO_EX_INDEX_APP> is reserved for
+Each is identified by an B<CRYPTO_EX_INDEX_xxx> define in the header file
+F<< <openssl/crypto.h> >>. In addition, B<CRYPTO_EX_INDEX_APP> is reserved for
applications to use this facility for their own structures.
The API described here is used by OpenSSL to manipulate exdata for specific
diff --git a/doc/man3/EC_GROUP_copy.pod b/doc/man3/EC_GROUP_copy.pod
index 1dd0364d98..f1d8632236 100644
--- a/doc/man3/EC_GROUP_copy.pod
+++ b/doc/man3/EC_GROUP_copy.pod
@@ -214,7 +214,7 @@ EC_GROUP_get_degree() returns the degree for B<group> or 0 if the operation is n
EC_GROUP_get_field_type() returns either B<NID_X9_62_prime_field> for prime curves
or B<NID_X9_62_characteristic_two_field> for binary curves;
-these values are defined in the obj_mac.h header file.
+these values are defined in the F<< <openssl/obj_mac.h> >> header file.
EC_GROUP_check_named_curve() returns the nid of the matching named curve, otherwise it returns 0 for no match, or -1 on error.
@@ -232,7 +232,7 @@ EC_GROUP_set_seed() returns the length of the seed that has been set. If the sup
EC_GROUP_cmp() returns 0 if the curves are equal, 1 if they are not equal, or -1 on error.
-EC_GROUP_get_basis_type() returns the values NID_X9_62_tpBasis or NID_X9_62_ppBasis (as defined in <openssl/obj_mac.h>) for a
+EC_GROUP_get_basis_type() returns the values NID_X9_62_tpBasis or NID_X9_62_ppBasis (as defined in F<< <openssl/obj_mac.h> >>) for a
trinomial or pentanomial respectively. Alternatively in the event of an error a 0 is returned.
=head1 SEE ALSO
diff --git a/doc/man3/ENGINE_add.pod b/doc/man3/ENGINE_add.pod
index 97abc3beb0..279cfdaade 100644
--- a/doc/man3/ENGINE_add.pod
+++ b/doc/man3/ENGINE_add.pod
@@ -247,7 +247,7 @@ released on behalf of the caller.
To clarify a particular function's handling of references, one should
always consult that function's documentation "man" page, or failing that
-the openssl/engine.h header file includes some hints.
+the F<< <openssl/engine.h> >> header file includes some hints.
I<Functional references>
@@ -498,10 +498,10 @@ and input parameters of the control commands supported by an ENGINE using a
structural reference. Note that some control commands are defined by OpenSSL
itself and it will intercept and handle these control commands on behalf of the
ENGINE, i.e. the ENGINE's ctrl() handler is not used for the control command.
-openssl/engine.h defines an index, ENGINE_CMD_BASE, that all control commands
-implemented by ENGINEs should be numbered from. Any command value lower than
-this symbol is considered a "generic" command is handled directly by the
-OpenSSL core routines.
+F<< <openssl/engine.h> >> defines an index, ENGINE_CMD_BASE, that all control
+commands implemented by ENGINEs should be numbered from. Any command value
+lower than this symbol is considered a "generic" command is handled directly
+by the OpenSSL core routines.
It is using these "core" control commands that one can discover the control
commands implemented by a given ENGINE, specifically the commands:
diff --git a/doc/man3/OSSL_CRMF_pbmp_new.pod b/doc/man3/OSSL_CRMF_pbmp_new.pod
index 9b4761b8ba..912426b194 100644
--- a/doc/man3/OSSL_CRMF_pbmp_new.pod
+++ b/doc/man3/OSSL_CRMF_pbmp_new.pod
@@ -42,7 +42,7 @@ for the random number generation (DRBG) and may be NULL for the default.
=head1 NOTES
The algorithms for the OWF (one-way function) and for the MAC (message
-authentication code) may be any with a NID defined in C<openssl/objects.h>.
+authentication code) may be any with a NID defined in F<< <openssl/objects.h> >>.
As specified by RFC 4210, these should include NID_hmac_sha1.
RFC 4210 recommends that the salt SHOULD be at least 8 bytes (64 bits) long,
diff --git a/doc/man3/OSSL_PARAM_BLD.pod b/doc/man3/OSSL_PARAM_BLD.pod
index 844b715820..acb60841e2 100644
--- a/doc/man3/OSSL_PARAM_BLD.pod
+++ b/doc/man3/OSSL_PARAM_BLD.pod
@@ -18,7 +18,7 @@ OSSL_PARAM_BLD_push_octet_string, OSSL_PARAM_BLD_push_octet_ptr
=for openssl generic
- #include "openssl/param_build.h"
+ #include <openssl/param_build.h>
typedef struct OSSL_PARAM_BLD;
diff --git a/doc/man3/OSSL_trace_enabled.pod b/doc/man3/OSSL_trace_enabled.pod
index 26168b45a3..8bf44dce7c 100644
--- a/doc/man3/OSSL_trace_enabled.pod
+++ b/doc/man3/OSSL_trace_enabled.pod
@@ -230,7 +230,7 @@ When the library is built with tracing disabled:
=item *
-The macro B<OPENSSL_NO_TRACE> is defined in C<openssl/opensslconf.h>.
+The macro B<OPENSSL_NO_TRACE> is defined in F<< <openssl/opensslconf.h> >>.
=item *
diff --git a/doc/man3/OSSL_trace_set_channel.pod b/doc/man3/OSSL_trace_set_channel.pod
index 8e88fb75e1..4ca2d1aef3 100644
--- a/doc/man3/OSSL_trace_set_channel.pod
+++ b/doc/man3/OSSL_trace_set_channel.pod
@@ -288,7 +288,7 @@ use the tracing functionality documented here, it is therefore
necessary to configure and build OpenSSL with the 'enable-trace' option.
When the library is built with tracing disabled, the macro
-B<OPENSSL_NO_TRACE> is defined in C<openssl/opensslconf.h> and all
+B<OPENSSL_NO_TRACE> is defined in F<< <openssl/opensslconf.h> >> and all
functions described here are inoperational, i.e. will do nothing.
=head1 HISTORY
diff --git a/doc/man3/SSL_CTX_set_tlsext_ticket_key_cb.pod b/doc/man3/SSL_CTX_set_tlsext_ticket_key_cb.pod
index a81dc76591..2b35cc1d5f 100644
--- a/doc/man3/SSL_CTX_set_tlsext_ticket_key_cb.pod
+++ b/doc/man3/SSL_CTX_set_tlsext_ticket_key_cb.pod
@@ -61,7 +61,7 @@ I<iv>, and set the cipher context I<ctx> and the hash context I<hctx>.
The I<name> is 16 characters long and is used as a key identifier.
The I<iv> length is the length of the IV of the corresponding cipher. The
-maximum IV length is B<EVP_MAX_IV_LENGTH> bytes defined in B<evp.h>.
+maximum IV length is B<EVP_MAX_IV_LENGTH> bytes defined in F<< <openssl/evp.h> >>.
The initialization vector I<iv> should be a random value. The cipher context
I<ctx> should use the initialisation vector I<iv>. The cipher context can be
diff --git a/doc/man3/SSL_get_all_async_fds.pod b/doc/man3/SSL_get_all_async_fds.pod
index c944d315d8..c0a900c436 100644
--- a/doc/man3/SSL_get_all_async_fds.pod
+++ b/doc/man3/SSL_get_all_async_fds.pod
@@ -60,12 +60,12 @@ SSL_get_all_async_fds() and SSL_get_changed_async_fds() return 1 on success or
=head1 NOTES
-On Windows platforms the openssl/async.h header is dependent on some
-of the types customarily made available by including windows.h. The
+On Windows platforms the F<< <openssl/async.h> >> header is dependent on some
+of the types customarily made available by including F<< <windows.h> >>. The
application developer is likely to require control over when the latter
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.
+F<< <windows.h> >> prior to F<< <openssl/async.h> >>.
=head1 SEE ALSO
diff --git a/doc/man3/X509_NAME_get_index_by_NID.pod b/doc/man3/X509_NAME_get_index_by_NID.pod
index e005c146ff..944790377e 100644
--- a/doc/man3/X509_NAME_get_index_by_NID.pod
+++ b/doc/man3/X509_NAME_get_index_by_NID.pod
@@ -65,8 +65,8 @@ X509_NAME_get_entry() on any matching indices and then the
various B<X509_NAME_ENTRY> utility functions on the result.
The list of all relevant B<NID_*> and B<OBJ_* codes> can be found in
-the source code header files E<lt>openssl/obj_mac.hE<gt> and/or
-E<lt>openssl/objects.hE<gt>.
+the source code header files F<< <openssl/obj_mac.h> >> and/or
+F<< <openssl/objects.h> >>.
Applications which could pass invalid NIDs to X509_NAME_get_index_by_NID()
should check for the return value of -2. Alternatively the NID validity
diff --git a/doc/man3/X509_verify_cert.pod b/doc/man3/X509_verify_cert.pod
index 764e4df28e..753477fd74 100644
--- a/doc/man3/X509_verify_cert.pod
+++ b/doc/man3/X509_verify_cert.pod
@@ -46,9 +46,9 @@ examining B<ctx> using, for example L<X509_STORE_CTX_get_error(3)>.
=head1 BUGS
-This function uses the header F<< <x509.h> >>
+This function uses the header F<< <openssl/x509.h> >>
as opposed to most chain verification
-functions which use F<< <x509_vfy.h> >>.
+functions which use F<< <openssl/x509_vfy.h> >>.
=head1 SEE ALSO
More information about the openssl-commits
mailing list