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)

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

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.

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

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
 

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
 

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
 

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.
 

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
 

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.

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.