Fix documentation errors, mainly caused by return values of BIO_ctrl

Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/16767)

(cherry picked from commit 5001287c0dcd8ca4ffc564b360f86df79bba40c1)

10 files changed, 33 insertions, 32 deletions

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<ASN1_TYPE> structure to be manipulated. The
 B<ASN1_TYPE> 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<a>.
+ASN1_TYPE_get() returns the type of I<a> or 0 if it fails.
 
 ASN1_TYPE_set() sets the value of I<a> to I<type> and I<value>. This
 function uses the pointer I<value> internally so it must B<not> 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 <openssl/evp.h>
 
  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<BIO_BIND> flags, or -1 on failure.
+BIO_get_bind_mode() returns the set of B<BIO_BIND> 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.