diff options
author | Gustaf Neumann <neumann@wu-wien.ac.at> | 2020-07-17 12:31:26 +0200 |
---|---|---|
committer | Dr. Matthias St. Pierre <matthias.st.pierre@ncp-e.com> | 2020-07-22 09:15:00 +0200 |
commit | 490c87110cc1fd673604fa1b94d5538f9fd852bb (patch) | |
tree | 3edd4a289e298a405dd7785fd1b21e81e8cd55e0 /doc | |
parent | bf19b64aaeeddd5463d911823f9e2c3c40091005 (diff) |
Align documentation with recommendations of Linux Documentation Project
This change applies the recommendation of the Linux Documentation Project
to the documentation files of OpenSSL. Additionally, util/find-doc-nits
was updated accordingly.
The change follows a suggestion of mspncp on https://github.com/openssl/openssl/pull/12370
and incoporates the requested changes on the pull request
Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com>
(Merged from https://github.com/openssl/openssl/pull/12460)
Diffstat (limited to 'doc')
50 files changed, 92 insertions, 92 deletions
diff --git a/doc/internal/man3/ossl_method_construct.pod b/doc/internal/man3/ossl_method_construct.pod index f3d7a64d00..fa151bb92a 100644 --- a/doc/internal/man3/ossl_method_construct.pod +++ b/doc/internal/man3/ossl_method_construct.pod @@ -35,9 +35,9 @@ OSSL_METHOD_CONSTRUCT_METHOD, ossl_method_construct =head1 DESCRIPTION -All libcrypto sub-systems that want to create their own methods based +All libcrypto subsystems that want to create their own methods based on provider dispatch tables need to do so in exactly the same way. -ossl_method_construct() does this while leaving it to the sub-systems +ossl_method_construct() does this while leaving it to the subsystems to define more precisely how the methods are created, stored, etc. It's important to keep in mind that a method is identified by three things: @@ -56,18 +56,18 @@ It's important to keep in mind that a method is identified by three things: ossl_method_construct() creates a method by asking all available providers for a dispatch table given an I<operation_id>, and then -calling the appropriate functions given by the sub-system specific +calling the appropriate functions given by the subsystem specific method creator through I<mcm> and the data in I<mcm_data> (which is passed by ossl_method_construct()). -This function assumes that the sub-system method creator implements +This function assumes that the subsystem method creator implements reference counting and acts accordingly (i.e. it will call the -sub-system destruct() method to decrement the reference count when +subsystem destruct() method to decrement the reference count when appropriate). =head2 Structures -A central part of constructing a sub-system specific method is to give +A central part of constructing a subsystem specific method is to give ossl_method_construct a set of functions, all in the B<OSSL_METHOD_CONSTRUCT_METHOD> structure, which holds the following function pointers: @@ -90,7 +90,7 @@ Remove a temporary store. Look up an already existing method from a store by name. The store may be given with I<store>. -NULL is a valid value and means that a sub-system default store +NULL is a valid value and means that a subsystem default store must be used. This default store should be stored in the library context I<libctx>. @@ -107,7 +107,7 @@ Places the I<method> created by the construct() function (see below) in a store. The store may be given with I<store>. -NULL is a valid value and means that a sub-system default store +NULL is a valid value and means that a subsystem default store must be used. This default store should be stored in the library context I<libctx>. @@ -120,11 +120,11 @@ This function is expected to increment the I<method>'s reference count. =item construct() -Constructs a sub-system method for the given I<name> and the given +Constructs a subsystem method for the given I<name> and the given dispatch table I<fns>. The associated provider object I<prov> is passed as well, to make -it possible for the sub-system constructor to keep a reference, which +it possible for the subsystem constructor to keep a reference, which is recommended. If such a reference is kept, the I<provider object> reference counter must be incremented, using ossl_provider_up_ref(). diff --git a/doc/man1/openssl-cmp.pod.in b/doc/man1/openssl-cmp.pod.in index 6ed11f442f..216db0cb1f 100644 --- a/doc/man1/openssl-cmp.pod.in +++ b/doc/man1/openssl-cmp.pod.in @@ -859,7 +859,7 @@ Act as CMP HTTP server mock-up listening on the given port. =item B<-max_msgs> I<number> Maximum number of CMP (request) messages the CMP HTTP server mock-up -should handle, which must be non-negative. +should handle, which must be nonnegative. The default value is 0, which means that no limit is imposed. In any case the server terminates on internal errors, but not when it detects a CMP-level error that it can successfully answer with an error message. diff --git a/doc/man1/openssl-s_client.pod.in b/doc/man1/openssl-s_client.pod.in index 78f4cc679c..6d8cb5a397 100644 --- a/doc/man1/openssl-s_client.pod.in +++ b/doc/man1/openssl-s_client.pod.in @@ -478,11 +478,11 @@ File to send output of B<-msg> or B<-trace> to, default standard output. =item B<-nbio_test> -Tests non-blocking I/O +Tests nonblocking I/O =item B<-nbio> -Turns on non-blocking I/O +Turns on nonblocking I/O =item B<-crlf> diff --git a/doc/man1/openssl-ts.pod.in b/doc/man1/openssl-ts.pod.in index 7a1ed418ce..d6536374f5 100644 --- a/doc/man1/openssl-ts.pod.in +++ b/doc/man1/openssl-ts.pod.in @@ -90,8 +90,8 @@ value that it had sent to the TSA. =back -There is one DER encoded protocol data unit defined for transporting a time -stamp request to the TSA and one for sending the timestamp response +There is one DER encoded protocol data unit defined for transporting a +timestamp request to the TSA and one for sending the timestamp response back to the client. This command has three main functions: creating a timestamp request based on a data file, creating a timestamp response based on a request, verifying if a @@ -294,8 +294,8 @@ instead of DER. (Optional) =head2 Timestamp Response verification -The B<-verify> command is for verifying if a timestamp response or time -stamp token is valid and matches a particular timestamp request or +The B<-verify> command is for verifying if a timestamp response or +timestamp token is valid and matches a particular timestamp request or data file. The B<-verify> command does not use the configuration file. =over 4 diff --git a/doc/man1/openssl.pod b/doc/man1/openssl.pod index f075e2170b..791bc52341 100644 --- a/doc/man1/openssl.pod +++ b/doc/man1/openssl.pod @@ -612,7 +612,7 @@ Note that the parsing is simple and might fail to parse some legal data. =back The options to specify the format are as follows. Refer to the individual -manpage to see which options are accepted. +man page to see which options are accepted. =over 4 diff --git a/doc/man3/ASYNC_WAIT_CTX_new.pod b/doc/man3/ASYNC_WAIT_CTX_new.pod index c95ceb78a0..f1d6a02219 100644 --- a/doc/man3/ASYNC_WAIT_CTX_new.pod +++ b/doc/man3/ASYNC_WAIT_CTX_new.pod @@ -130,7 +130,7 @@ descriptor is not appropriate. ASYNC_WAIT_CTX_set_callback() sets the callback and the callback argument. The callback will be called to notify user code when an engine completes a cryptography operation. It is a requirement that the callback function is small -and non-blocking as it will be run in the context of a polling mechanism or an +and nonblocking as it will be run in the context of a polling mechanism or an interrupt. ASYNC_WAIT_CTX_get_callback() returns the callback set in the B<ASYNC_WAIT_CTX> diff --git a/doc/man3/BIO_connect.pod b/doc/man3/BIO_connect.pod index 9e0d972ba4..3d51720a9f 100644 --- a/doc/man3/BIO_connect.pod +++ b/doc/man3/BIO_connect.pod @@ -55,7 +55,7 @@ Enables regular sending of keep-alive messages. =item BIO_SOCK_NONBLOCK -Sets the socket to non-blocking mode. +Sets the socket to nonblocking mode. =item BIO_SOCK_NODELAY diff --git a/doc/man3/BIO_f_ssl.pod b/doc/man3/BIO_f_ssl.pod index 61d23c9db7..6a21e0c41c 100644 --- a/doc/man3/BIO_f_ssl.pod +++ b/doc/man3/BIO_f_ssl.pod @@ -102,7 +102,7 @@ If domain name resolution yields multiple IP addresses all of them are tried after connect() failures. The function returns 1 if the connection was established successfully. A zero or negative value is returned if the connection could not be established. -The call BIO_should_retry() should be used for non-blocking connect BIOs +The call BIO_should_retry() should be used for nonblocking connect BIOs to determine if the call should be retried. If a connection has already been established this call has no effect. diff --git a/doc/man3/BIO_read.pod b/doc/man3/BIO_read.pod index 293c1304a4..ccd165189e 100644 --- a/doc/man3/BIO_read.pod +++ b/doc/man3/BIO_read.pod @@ -55,7 +55,7 @@ NUL is not included in the length returned by BIO_gets(). =head1 NOTES A 0 or -1 return is not necessarily an indication of an error. In -particular when the source/sink is non-blocking or of a certain type +particular when the source/sink is nonblocking or of a certain type it may merely be an indication that no data is currently available and that the application should retry the operation later. diff --git a/doc/man3/BIO_s_accept.pod b/doc/man3/BIO_s_accept.pod index e6ad95b4e0..6c091bbb5c 100644 --- a/doc/man3/BIO_s_accept.pod +++ b/doc/man3/BIO_s_accept.pod @@ -143,7 +143,7 @@ however because the accept BIO will still accept additional incoming connections. This can be resolved by using BIO_pop() (see above) and freeing up the accept BIO after the initial connection. -If the underlying accept socket is non-blocking and BIO_do_accept() is +If the underlying accept socket is nonblocking and BIO_do_accept() is called to await an incoming connection it is possible for BIO_should_io_special() with the reason BIO_RR_ACCEPT. If this happens then it is an indication that an accept attempt would block: the application diff --git a/doc/man3/BIO_s_bio.pod b/doc/man3/BIO_s_bio.pod index cf25538fef..653fe4785a 100644 --- a/doc/man3/BIO_s_bio.pod +++ b/doc/man3/BIO_s_bio.pod @@ -167,7 +167,7 @@ without having to go through the SSL-interface. ... As the BIO pair will only buffer the data and never directly access the -connection, it behaves non-blocking and will return as soon as the write +connection, it behaves nonblocking and will return as soon as the write buffer is full or the read buffer is drained. Then the application has to flush the write buffer and/or fill the read buffer. diff --git a/doc/man3/BIO_socket_wait.pod b/doc/man3/BIO_socket_wait.pod index b00a878c9d..f1050f80fb 100644 --- a/doc/man3/BIO_socket_wait.pod +++ b/doc/man3/BIO_socket_wait.pod @@ -34,7 +34,7 @@ Via B<nap_milliseconds> the caller determines the polling granularity. BIO_do_connect_retry() connects via the given B<bio>. It retries BIO_do_connect() as far as needed to reach a definite outcome, i.e., connection succeeded, timeout has been reached, or an error occurred. -For non-blocking and potentially even non-socket BIOs it polls +For nonblocking and potentially even non-socket BIOs it polls every B<nap_milliseconds> and sleeps in between using BIO_wait(). If B<nap_milliseconds> is < 0 then a default value of 100 ms is used. If the B<timeout> parameter is > 0 this indicates the maximum number of seconds diff --git a/doc/man3/BN_add.pod b/doc/man3/BN_add.pod index 1fae2eee99..6f9b923914 100644 --- a/doc/man3/BN_add.pod +++ b/doc/man3/BN_add.pod @@ -68,16 +68,16 @@ For division by powers of 2, use BN_rshift(3). BN_mod() corresponds to BN_div() with I<dv> set to B<NULL>. -BN_nnmod() reduces I<a> modulo I<m> and places the non-negative +BN_nnmod() reduces I<a> modulo I<m> and places the nonnegative remainder in I<r>. -BN_mod_add() adds I<a> to I<b> modulo I<m> and places the non-negative +BN_mod_add() adds I<a> to I<b> modulo I<m> and places the nonnegative result in I<r>. BN_mod_sub() subtracts I<b> from I<a> modulo I<m> and places the -non-negative result in I<r>. +nonnegative result in I<r>. -BN_mod_mul() multiplies I<a> by I<b> and finds the non-negative +BN_mod_mul() multiplies I<a> by I<b> and finds the nonnegative remainder respective to modulus I<m> (C<r=(a*b) mod m>). I<r> may be the same B<BIGNUM> as I<a> or I<b>. For more efficient algorithms for repeated computations using the same modulus, see diff --git a/doc/man3/BN_generate_prime.pod b/doc/man3/BN_generate_prime.pod index cdd7ed0e8e..9827499b39 100644 --- a/doc/man3/BN_generate_prime.pod +++ b/doc/man3/BN_generate_prime.pod @@ -148,7 +148,7 @@ BN_is_prime_fasttest() and BN_is_prime() behave just like BN_is_prime_fasttest_ex() and BN_is_prime_ex() respectively, but with the old style call back. -B<ctx> is a pre-allocated B<BN_CTX> (to save the overhead of allocating and +B<ctx> is a preallocated B<BN_CTX> (to save the overhead of allocating and freeing the structure in a loop), or B<NULL>. If the trial division is done, and no divisors are found and B<cb> diff --git a/doc/man3/BN_mod_mul_montgomery.pod b/doc/man3/BN_mod_mul_montgomery.pod index 5cb2c2c377..24109e2a1d 100644 --- a/doc/man3/BN_mod_mul_montgomery.pod +++ b/doc/man3/BN_mod_mul_montgomery.pod @@ -49,7 +49,7 @@ the result in I<r>. BN_from_montgomery() performs the Montgomery reduction I<r> = I<a>*R^-1. BN_to_montgomery() computes Mont(I<a>,R^2), i.e. I<a>*R. -Note that I<a> must be non-negative and smaller than the modulus. +Note that I<a> must be nonnegative and smaller than the modulus. For all functions, I<ctx> is a previously allocated B<BN_CTX> used for temporary variables. diff --git a/doc/man3/BN_set_bit.pod b/doc/man3/BN_set_bit.pod index 24f7723c0c..323eb7d659 100644 --- a/doc/man3/BN_set_bit.pod +++ b/doc/man3/BN_set_bit.pod @@ -37,11 +37,11 @@ BN_mask_bits() truncates B<a> to an B<n> bit number shorter than B<n> bits. BN_lshift() shifts B<a> left by B<n> bits and places the result in -B<r> (C<r=a*2^n>). Note that B<n> must be non-negative. BN_lshift1() shifts +B<r> (C<r=a*2^n>). Note that B<n> must be nonnegative. BN_lshift1() shifts B<a> left by one and places the result in B<r> (C<r=2*a>). BN_rshift() shifts B<a> right by B<n> bits and places the result in -B<r> (C<r=a/2^n>). Note that B<n> must be non-negative. BN_rshift1() shifts +B<r> (C<r=a/2^n>). Note that B<n> must be nonnegative. BN_rshift1() shifts B<a> right by one and places the result in B<r> (C<r=a/2>). For the shift functions, B<r> and B<a> may be the same variable. diff --git a/doc/man3/DTLSv1_listen.pod b/doc/man3/DTLSv1_listen.pod index aa20918686..13f6f1ff14 100644 --- a/doc/man3/DTLSv1_listen.pod +++ b/doc/man3/DTLSv1_listen.pod @@ -98,7 +98,7 @@ will be set up ready to continue the handshake. the B<peer> value will also be filled in. A return value of 0 indicates a non-fatal error. This could (for -example) be because of non-blocking IO, or some invalid message having been +example) be because of nonblocking IO, or some invalid message having been received from a peer. Errors may be placed on the OpenSSL error queue with further information if appropriate. Typically user code is expected to retry the call to DTLSv1_listen() in the event of a non-fatal error. diff --git a/doc/man3/ERR_new.pod b/doc/man3/ERR_new.pod index e1c71bebaa..ada27ed360 100644 --- a/doc/man3/ERR_new.pod +++ b/doc/man3/ERR_new.pod @@ -49,7 +49,7 @@ do not return any values. =head1 NOTES The library number is unique to each unit that records errors. -OpenSSL has a number of pre-allocated ones for its own uses, but +OpenSSL has a number of preallocated ones for its own uses, but others may allocate their own library number dynamically with L<ERR_get_next_error_library(3)>. diff --git a/doc/man3/EVP_PKEY_gen.pod b/doc/man3/EVP_PKEY_gen.pod index 212ea2a742..979de8601e 100644 --- a/doc/man3/EVP_PKEY_gen.pod +++ b/doc/man3/EVP_PKEY_gen.pod @@ -75,7 +75,7 @@ generation callback. The function EVP_PKEY_CTX_get_keygen_info() returns parameters associated with the generation operation. If I<idx> is -1 the total number of parameters available is returned. Any non negative value returns the value of -that parameter. EVP_PKEY_CTX_gen_keygen_info() with a non-negative value for +that parameter. EVP_PKEY_CTX_gen_keygen_info() with a nonnegative value for I<idx> should only be called within the generation callback. If the callback returns 0 then the key generation operation is aborted and an diff --git a/doc/man3/OPENSSL_init_crypto.pod b/doc/man3/OPENSSL_init_crypto.pod index 0b8f9010c4..bed722abf2 100644 --- a/doc/man3/OPENSSL_init_crypto.pod +++ b/doc/man3/OPENSSL_init_crypto.pod @@ -40,13 +40,13 @@ needs so no explicit initialisation is required. Similarly it will also automatically deinitialise as required. However, there may be situations when explicit initialisation is desirable or -needed, for example when some non-default initialisation is required. The +needed, for example when some nondefault initialisation is required. The function OPENSSL_init_crypto() can be used for this purpose for libcrypto (see also L<OPENSSL_init_ssl(3)> for the libssl equivalent). Numerous internal OpenSSL functions call OPENSSL_init_crypto(). -Therefore, in order to perform non-default initialisation, +Therefore, in order to perform nondefault initialisation, OPENSSL_init_crypto() MUST be called by application code prior to any other OpenSSL function calls. @@ -105,7 +105,7 @@ used by calling OPENSSL_config(). This is a default option. Note that in OpenSSL 1.1.1 this was the default for libssl but not for libcrypto (see L<OPENSSL_init_ssl(3)> for further details about libssl initialisation). -In OpenSSL 1.1.0 this was a non-default option for both libssl and libcrypto. +In OpenSSL 1.1.0 this was a nondefault option for both libssl and libcrypto. See the description of OPENSSL_INIT_new(), below. =item OPENSSL_INIT_NO_LOAD_CONFIG @@ -241,10 +241,10 @@ The filename, application name, and flags can be customized by providing a non-null B<OPENSSL_INIT_SETTINGS> object. The object can be allocated via B<OPENSSL_INIT_new()>. The B<OPENSSL_INIT_set_config_filename()> function can be used to specify a -non-default filename, which is copied and need not refer to persistent storage. +nondefault filename, which is copied and need not refer to persistent storage. Similarly, OPENSSL_INIT_set_config_appname() can be used to specify a -non-default application name. -Finally, OPENSSL_INIT_set_file_flags can be used to specify non-default flags. +nondefault application name. +Finally, OPENSSL_INIT_set_file_flags can be used to specify nondefault flags. If the B<CONF_MFLAGS_IGNORE_RETURN_CODES> flag is not included, any errors in the configuration file will cause an error return from B<OPENSSL_init_crypto> or indirectly L<OPENSSL_init_ssl(3)>. diff --git a/doc/man3/OPENSSL_init_ssl.pod b/doc/man3/OPENSSL_init_ssl.pod index d5a771bbc3..ce6f23042a 100644 --- a/doc/man3/OPENSSL_init_ssl.pod +++ b/doc/man3/OPENSSL_init_ssl.pod @@ -23,14 +23,14 @@ needs so no explicit initialisation is required. Similarly it will also automatically deinitialise as required. However, there may be situations when explicit initialisation is desirable or -needed, for example when some non-default initialisation is required. The +needed, for example when some nondefault initialisation is required. The function OPENSSL_init_ssl() can be used for this purpose. Calling this function will explicitly initialise BOTH libcrypto and libssl. To explicitly initialise ONLY libcrypto see the L<OPENSSL_init_crypto(3)> function. Numerous internal OpenSSL functions call OPENSSL_init_ssl(). -Therefore, in order to perform non-default initialisation, +Therefore, in order to perform nondefault initialisation, OPENSSL_init_ssl() MUST be called by application code prior to any other OpenSSL function calls. diff --git a/doc/man3/OSSL_CMP_CTX_new.pod b/doc/man3/OSSL_CMP_CTX_new.pod index e8237b46e7..cb2d68a44b 100644 --- a/doc/man3/OSSL_CMP_CTX_new.pod +++ b/doc/man3/OSSL_CMP_CTX_new.pod @@ -579,7 +579,7 @@ X.509 certificates received in the caPubs field of last received certificate response message IP/CP/KUP. |