From: PW Hu Date: Thu, 7 Oct 2021 03:40:49 +0000 (+0800) Subject: Fix documentation errors, mainly caused by return values of BIO_ctrl X-Git-Tag: openssl-3.2.0-alpha1~3442 X-Git-Url: https://git.openssl.org/?p=openssl.git;a=commitdiff_plain;h=5001287c0dcd8ca4ffc564b360f86df79bba40c1 Fix documentation errors, mainly caused by return values of BIO_ctrl Reviewed-by: Shane Lontis Reviewed-by: Tomas Mraz (Merged from https://github.com/openssl/openssl/pull/16767) --- diff --git a/doc/man3/ASN1_TYPE_get.pod b/doc/man3/ASN1_TYPE_get.pod index c34572345f..1d87f676f4 100644 --- a/doc/man3/ASN1_TYPE_get.pod +++ b/doc/man3/ASN1_TYPE_get.pod @@ -24,7 +24,7 @@ These functions allow an B structure to be manipulated. The B structure can contain any ASN.1 type or constructed type such as a SEQUENCE: it is effectively equivalent to the ASN.1 ANY type. -ASN1_TYPE_get() returns the type of I. +ASN1_TYPE_get() returns the type of I or 0 if it fails. ASN1_TYPE_set() sets the value of I to I and I. This function uses the pointer I internally so it must B be freed diff --git a/doc/man3/BIO_ctrl.pod b/doc/man3/BIO_ctrl.pod index fdffda7b41..bcdeac6f7b 100644 --- a/doc/man3/BIO_ctrl.pod +++ b/doc/man3/BIO_ctrl.pod @@ -77,26 +77,27 @@ return a size_t type and are functions, BIO_pending() and BIO_wpending() are macros which call BIO_ctrl(). BIO_get_ktls_send() returns 1 if the BIO is using the Kernel TLS data-path for -sending. Otherwise, it returns zero. +sending. Otherwise, it returns zero. It also returns negative values for failure. BIO_get_ktls_recv() returns 1 if the BIO is using the Kernel TLS data-path for -receiving. Otherwise, it returns zero. +receiving. Otherwise, it returns zero. It also returns negative values for failure. =head1 RETURN VALUES -BIO_reset() normally returns 1 for success and 0 or -1 for failure. File +BIO_reset() normally returns 1 for success and <=0 for failure. File BIOs are an exception, they return 0 for success and -1 for failure. BIO_seek() and BIO_tell() both return the current file position on success and -1 for failure, except file BIOs which for BIO_seek() always return 0 for success and -1 for failure. -BIO_flush() returns 1 for success and 0 or -1 for failure. +BIO_flush() returns 1 for success and <=0 for failure. -BIO_eof() returns 1 if EOF has been reached, 0 if not, or -1 for failure. +BIO_eof() returns 1 if EOF has been reached, 0 if not, or negative values for failure. -BIO_set_close() always returns 1. +BIO_set_close() returns 1 on success or <=0 for failure. -BIO_get_close() returns the close flag value: BIO_CLOSE or BIO_NOCLOSE. +BIO_get_close() returns the close flag value: BIO_CLOSE or BIO_NOCLOSE. It also +returns other negative values if an error occurs. BIO_pending(), BIO_ctrl_pending(), BIO_wpending() and BIO_ctrl_wpending() return the amount of pending data. diff --git a/doc/man3/BIO_f_buffer.pod b/doc/man3/BIO_f_buffer.pod index ed32e11d92..2eb6e8eab1 100644 --- a/doc/man3/BIO_f_buffer.pod +++ b/doc/man3/BIO_f_buffer.pod @@ -74,12 +74,13 @@ source/sink BIO is non blocking. BIO_f_buffer() returns the buffering BIO method. -BIO_get_buffer_num_lines() returns the number of lines buffered (may be 0). +BIO_get_buffer_num_lines() returns the number of lines buffered (may be 0) or +a negative value in case of errors. BIO_set_read_buffer_size(), BIO_set_write_buffer_size() and BIO_set_buffer_size() -return 1 if the buffer was successfully resized or 0 for failure. +return 1 if the buffer was successfully resized or <=0 for failure. -BIO_set_buffer_read_data() returns 1 if the data was set correctly or 0 if +BIO_set_buffer_read_data() returns 1 if the data was set correctly or <=0 if there was an error. =head1 SEE ALSO diff --git a/doc/man3/BIO_f_cipher.pod b/doc/man3/BIO_f_cipher.pod index 48f5536039..cb6b14a0c0 100644 --- a/doc/man3/BIO_f_cipher.pod +++ b/doc/man3/BIO_f_cipher.pod @@ -12,8 +12,8 @@ BIO_f_cipher, BIO_set_cipher, BIO_get_cipher_status, BIO_get_cipher_ctx - cipher #include const BIO_METHOD *BIO_f_cipher(void); - void BIO_set_cipher(BIO *b, const EVP_CIPHER *cipher, - unsigned char *key, unsigned char *iv, int enc); + int BIO_set_cipher(BIO *b, const EVP_CIPHER *cipher, + const unsigned char *key, const unsigned char *iv, int enc); int BIO_get_cipher_status(BIO *b); int BIO_get_cipher_ctx(BIO *b, EVP_CIPHER_CTX **pctx); @@ -62,12 +62,12 @@ be achieved by preceding the cipher BIO with a buffering BIO. BIO_f_cipher() returns the cipher BIO method. -BIO_set_cipher() does not return a value. +BIO_set_cipher() returns 1 for success and 0 for failure. -BIO_get_cipher_status() returns 1 for a successful decrypt and 0 +BIO_get_cipher_status() returns 1 for a successful decrypt and <=0 for failure. -BIO_get_cipher_ctx() currently always returns 1. +BIO_get_cipher_ctx() returns 1 for success and <=0 for failure. =head1 COPYRIGHT diff --git a/doc/man3/BIO_f_md.pod b/doc/man3/BIO_f_md.pod index e146427d89..c2b825e352 100644 --- a/doc/man3/BIO_f_md.pod +++ b/doc/man3/BIO_f_md.pod @@ -69,7 +69,7 @@ if the standard calls such as BIO_set_md() are not sufficiently flexible. BIO_f_md() returns the digest BIO method. BIO_set_md(), BIO_get_md() and BIO_md_ctx() return 1 for success and -0 for failure. +<=0 for failure. =head1 EXAMPLES diff --git a/doc/man3/BIO_f_prefix.pod b/doc/man3/BIO_f_prefix.pod index b4d0298b2a..8c7953f472 100644 --- a/doc/man3/BIO_f_prefix.pod +++ b/doc/man3/BIO_f_prefix.pod @@ -46,13 +46,13 @@ implemented as macros. BIO_f_prefix() returns the prefix BIO method. -BIO_set_prefix() returns 1 if the prefix was correctly set, or 0 on +BIO_set_prefix() returns 1 if the prefix was correctly set, or <=0 on failure. -BIO_set_indent() returns 1 if the prefix was correctly set, or 0 on +BIO_set_indent() returns 1 if the prefix was correctly set, or <=0 on failure. -BIO_get_indent() returns the current indentation. +BIO_get_indent() returns the current indentation, or a negative value for failure. =head1 SEE ALSO diff --git a/doc/man3/BIO_s_accept.pod b/doc/man3/BIO_s_accept.pod index e6f9291364..c3826a609f 100644 --- a/doc/man3/BIO_s_accept.pod +++ b/doc/man3/BIO_s_accept.pod @@ -169,16 +169,16 @@ BIO_set_bind_mode(), BIO_get_bind_mode() and BIO_do_accept() are macros. BIO_do_accept(), BIO_set_accept_name(), BIO_set_accept_port(), BIO_set_nbio_accept(), BIO_set_accept_bios(), BIO_set_accept_ip_family(), and BIO_set_bind_mode() -return 1 for success and 0 or -1 for failure. +return 1 for success and <=0 for failure. BIO_get_accept_name() returns the accept name or NULL on error. BIO_get_peer_name() returns the peer name or NULL on error. BIO_get_accept_port() returns the accept port as a string or NULL on error. BIO_get_peer_port() returns the peer port as a string or NULL on error. -BIO_get_accept_ip_family() returns the IP family or -1 on error. +BIO_get_accept_ip_family() returns the IP family or <=0 on error. -BIO_get_bind_mode() returns the set of B flags, or -1 on failure. +BIO_get_bind_mode() returns the set of B flags, or <=0 on failure. BIO_new_accept() returns a BIO or NULL on error. diff --git a/doc/man3/BIO_s_connect.pod b/doc/man3/BIO_s_connect.pod index f31da27fe7..76ed7337ea 100644 --- a/doc/man3/BIO_s_connect.pod +++ b/doc/man3/BIO_s_connect.pod @@ -141,9 +141,9 @@ BIO_set_nbio(), and BIO_do_connect() are macros. BIO_s_connect() returns the connect BIO method. BIO_set_conn_address(), BIO_set_conn_port(), and BIO_set_conn_ip_family() -always return 1. +return 1 or <=0 if an error occurs. -BIO_set_conn_hostname() returns 1 on success and 0 on failure. +BIO_set_conn_hostname() returns 1 on success and <=0 on failure. BIO_get_conn_address() returns the address information or NULL if none was set. @@ -156,10 +156,10 @@ BIO_get_conn_ip_family() returns the address family or -1 if none was set. BIO_get_conn_port() returns a string representing the connected port or NULL if not set. -BIO_set_nbio() always returns 1. +BIO_set_nbio() returns 1 or <=0 if an error occurs. BIO_do_connect() returns 1 if the connection was successfully -established and 0 or -1 if the connection failed. +established and <=0 if the connection failed. =head1 EXAMPLES diff --git a/doc/man3/BIO_s_fd.pod b/doc/man3/BIO_s_fd.pod index 1f7bb0cd30..10aea50d46 100644 --- a/doc/man3/BIO_s_fd.pod +++ b/doc/man3/BIO_s_fd.pod @@ -60,10 +60,10 @@ BIO_set_fd() and BIO_get_fd() are implemented as macros. BIO_s_fd() returns the file descriptor BIO method. -BIO_set_fd() always returns 1. +BIO_set_fd() returns 1 on success or <=0 for failure. BIO_get_fd() returns the file descriptor or -1 if the BIO has not -been initialized. +been initialized. It also returns zero and negative values if other error occurs. BIO_new_fd() returns the newly allocated BIO or NULL is an error occurred. diff --git a/doc/man3/BIO_s_file.pod b/doc/man3/BIO_s_file.pod index aaaf2dc39e..b60a9d8f7a 100644 --- a/doc/man3/BIO_s_file.pod +++ b/doc/man3/BIO_s_file.pod @@ -90,10 +90,9 @@ occurred. BIO_set_fp() and BIO_get_fp() return 1 for success or <=0 for failure (although the current implementation never return 0). -BIO_seek() returns the same value as the underlying fseek() function: -0 for success or -1 for failure. +BIO_seek() returns 0 for success or negative values for failure. -BIO_tell() returns the current file position. +BIO_tell() returns the current file position or negative values for failure. BIO_read_filename(), BIO_write_filename(), BIO_append_filename() and BIO_rw_filename() return 1 for success or <=0 for failure.