Add missing 'RETURN VALUES' sections in doc

All missing sections are added.

Reviewed-by: Andy Polyakov <appro@openssl.org>
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/4976)

59 files changed, 476 insertions, 61 deletions

diff --git a/doc/man3/ASN1_STRING_length.pod b/doc/man3/ASN1_STRING_length.pod
index 26cb176142..1c80162b6c 100644
--- a/doc/man3/ASN1_STRING_length.pod
+++ b/doc/man3/ASN1_STRING_length.pod
@@ -77,13 +77,33 @@ character in big endian format, UTF8String will be in UTF8 format.
 Similar care should be take to ensure the data is in the correct format
 when calling ASN1_STRING_set().
 
+=head1 RETURN VALUES
+
+ASN1_STRING_length() returns the length of the content of B<x>.
+
+ASN1_STRING_get0_data() and ASN1_STRING_data() return an internal pointer to
+the data of B<x>.
+
+ASN1_STRING_dup() returns a valid B<ASN1_STRING> structure or B<NULL> if an
+error occurred.
+
+ASN1_STRING_cmp() returns an integer greater than, equal to, or less than 0,
+according to whether B<a> is greater than, equal to, or less than B<b>.
+
+ASN1_STRING_set() returns 1 on success or 0 on error.
+
+ASN1_STRING_type() returns the type of B<x>.
+
+ASN1_STRING_to_UTF8() returns the number of bytes in output string B<out> or a
+negative value if an error occurred.
+
 =head1 SEE ALSO
 
 L<ERR_get_error(3)>
 
 =head1 COPYRIGHT
 
-Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2002-2017 The OpenSSL Project Authors. All Rights Reserved.
 
 Licensed under the OpenSSL license (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy
diff --git a/doc/man3/ASN1_STRING_print_ex.pod b/doc/man3/ASN1_STRING_print_ex.pod
index 401de9b5d6..5c6a580629 100644
--- a/doc/man3/ASN1_STRING_print_ex.pod
+++ b/doc/man3/ASN1_STRING_print_ex.pod
@@ -89,6 +89,15 @@ equivalent to:
  ASN1_STRFLGS_ESC_2253 | ASN1_STRFLGS_ESC_CTRL | ASN1_STRFLGS_ESC_MSB |
  ASN1_STRFLGS_UTF8_CONVERT | ASN1_STRFLGS_DUMP_UNKNOWN ASN1_STRFLGS_DUMP_DER
 
+=head1 RETURN VALUES
+
+ASN1_STRING_print_ex() and ASN1_STRING_print_ex_fp() return the number of
+characters written or -1 if an error occurred.
+
+ASN1_STRING_print() returns 1 on success or 0 on error.
+
+ASN1_tag2str() returns a human-readable name of the specified ASN.1 B<tag>.
+
 =head1 SEE ALSO
 
 L<X509_NAME_print_ex(3)>,
diff --git a/doc/man3/BIO_f_ssl.pod b/doc/man3/BIO_f_ssl.pod
index 571584c148..4119fc9195 100644
--- a/doc/man3/BIO_f_ssl.pod
+++ b/doc/man3/BIO_f_ssl.pod
@@ -271,6 +271,22 @@ a client and also echoes the request to standard output.
  BIO_flush(sbio);
  BIO_free_all(sbio);
 
+=head1 RETURN VALUES
+
+BIO_f_ssl() returns the SSL B<BIO_METHOD> structure.
+
+BIO_set_ssl(), BIO_get_ssl(), BIO_set_ssl_mode(), BIO_set_ssl_renegotiate_bytes(),
+BIO_set_ssl_renegotiate_timeout() and BIO_get_num_renegotiates() return 1 on
+success or a value which is less than or equal to 0 if an error occurred.
+
+BIO_new_ssl(), BIO_new_ssl_connect() and BIO_new_buffer_ssl_connect() return
+a valid B<BIO> structure on success or B<NULL> if an error occurred.
+
+BIO_ssl_copy_session_id() returns 1 on success or 0 on error.
+
+BIO_do_handshake() returns 1 if the connection was established successfully.
+A zero or negative value is returned if the connection could not be established.
+
 =head1 HISTORY
 
 In OpenSSL before 1.0.0 the BIO_pop() call was handled incorrectly,
@@ -282,7 +298,7 @@ be modified to handle this fix or they may free up an already freed BIO.
 
 =head1 COPYRIGHT
 
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
 
 Licensed under the OpenSSL license (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy
diff --git a/doc/man3/BIO_get_ex_new_index.pod b/doc/man3/BIO_get_ex_new_index.pod
index 5833e6ad0a..438ea4e64a 100644
--- a/doc/man3/BIO_get_ex_new_index.pod
+++ b/doc/man3/BIO_get_ex_new_index.pod
@@ -48,6 +48,14 @@ an offset into the opaque exdata part of the TYPE object.
 TYPE_get_ex_data() is a function that calls CRYPTO_get_ex_data() with
 an offset into the opaque exdata part of the TYPE object.
 
+=head1 RETURN VALUES
+
+TYPE_get_new_ex_index() returns a new index on success or -1 on error.
+
+TYPE_set_ex_data() returns 1 on success or 0 on error.
+
+TYPE_get_ex_data() returns the application data or NULL if an error occurred.
+
 =head1 SEE ALSO
 
 L<CRYPTO_get_ex_new_index(3)>.
diff --git a/doc/man3/BIO_meth_new.pod b/doc/man3/BIO_meth_new.pod
index c86568365e..73826eb713 100644
--- a/doc/man3/BIO_meth_new.pod
+++ b/doc/man3/BIO_meth_new.pod
@@ -133,6 +133,17 @@ the L<BIO_callback_ctrl(3)> page for more information. This function will be cal
 in response to the application calling BIO_callback_ctrl(). The parameters for
 the function have the same meaning as for BIO_callback_ctrl().
 
+=head1 RETURN VALUES
+
+BIO_get_new_index() returns the new BIO type value or -1 if an error occurred.
+
+BIO_meth_new(int type, const char *name) returns a valid B<BIO_METHOD> or NULL
+if an error occurred.
+
+The B<BIO_meth_set> functions return 1 on success or 0 on error.
+
+The B<BIO_meth_get> functions return the corresponding function pointers.
+
 =head1 SEE ALSO
 
 L<bio>, L<BIO_find_type>, L<BIO_ctrl>, L<BIO_read_ex>, L<BIO_new>
diff --git a/doc/man3/BIO_parse_hostserv.pod b/doc/man3/BIO_parse_hostserv.pod
index 426e4de999..8403470cf5 100644
--- a/doc/man3/BIO_parse_hostserv.pod
+++ b/doc/man3/BIO_parse_hostserv.pod
@@ -58,13 +58,17 @@ and B<hostserv_prio>, as follows:
  when hostserv_prio == BIO_PARSE_PRIO_SERV
  service              => *host untouched, *service = "service"
 
+=head1 RETURN VALUES
+
+BIO_parse_hostserv() returns 1 on success or 0 on error.
+
 =head1 SEE ALSO
 
 L<BIO_ADDRINFO(3)>
 
 =head1 COPYRIGHT
 
-Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2016-2017 The OpenSSL Project Authors. All Rights Reserved.
 
 Licensed under the OpenSSL license (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy
diff --git a/doc/man3/BIO_s_mem.pod b/doc/man3/BIO_s_mem.pod
index 0b559e57a5..c53a11a66a 100644
--- a/doc/man3/BIO_s_mem.pod
+++ b/doc/man3/BIO_s_mem.pod
@@ -22,7 +22,7 @@ BIO_get_mem_ptr, BIO_new_mem_buf - memory BIO
 
 =head1 DESCRIPTION
 
-BIO_s_mem() return the memory BIO method function.
+BIO_s_mem() returns the memory BIO method function.
 
 A memory BIO is a source/sink BIO which uses memory for its I/O. Data
 written to a memory BIO is stored in a BUF_MEM structure which is extended
@@ -113,9 +113,18 @@ Extract the BUF_MEM structure from a memory BIO and then free up the BIO:
  BIO_set_close(mem, BIO_NOCLOSE); /* So BIO_free() leaves BUF_MEM alone */
  BIO_free(mem);
 
+=head1 RETURN VALUES
+
+BIO_s_mem() and BIO_s_secmem() return a valid memory B<BIO_METHOD> structure.
+
+BIO_set_mem_eof_return(), BIO_get_mem_data(), BIO_set_mem_buf() and BIO_get_mem_ptr()
+return 1 on success or a value which is less than or equal to 0 if an error occurred.
+
+BIO_new_mem_buf() returns a valid B<BIO> structure on success or NULL on error.
+
 =head1 COPYRIGHT
 
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
 
 Licensed under the OpenSSL license (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy
diff --git a/doc/man3/BIO_set_callback.pod b/doc/man3/BIO_set_callback.pod
index c6a626770b..99db4c70d4 100644
--- a/doc/man3/BIO_set_callback.pod
+++ b/doc/man3/BIO_set_callback.pod
@@ -212,9 +212,21 @@ after.
 The BIO_debug_callback() function is a good example, its source is
 in crypto/bio/bio_cb.c
 
+=head1 RETURN VALUES
+
+BIO_get_callback_ex() and BIO_get_callback() return the callback function
+previously set by a call to BIO_set_callback_ex() and BIO_set_callback()
+respectively.
+
+BIO_get_callback_arg() returns a B<char> pointer to the value previously set
+via a call to BIO_set_callback_arg().
+
+BIO_debug_callback() returns 1 or B<ret> if it's called after specific BIO
+operations.
+
 =head1 COPYRIGHT
 
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
 
 Licensed under the OpenSSL license (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy
diff --git a/doc/man3/BIO_should_retry.pod b/doc/man3/BIO_should_retry.pod
index 4d2d599e13..2becaca5ad 100644
--- a/doc/man3/BIO_should_retry.pod
+++ b/doc/man3/BIO_should_retry.pod
@@ -111,6 +111,19 @@ that is they cannot retry after a partial read or write. This is usually
 worked around by only passing the relevant data to ASN1 functions when
 the entire structure can be read or written.
 
+=head1 RETURN VALUES
+
+BIO_should_read(), BIO_should_write(), BIO_should_io_special(), and
+BIO_should_retry() return either 1 or 0 based on the actual conditions
+of the B<BIO>.
+
+BIO_retry_type() returns a flag combination presenting the cause of a retry
+condition or false if there is no retry condition.
+
+BIO_get_retry_BIO() returns a valid B<BIO> structure.
+
+BIO_get_retry_reason() returns the reason for a special condition.
+
 =head1 SEE ALSO
 
 L<bio>
@@ -122,7 +135,7 @@ OpenSSL 1.1.0.
 
 =head1 COPYRIGHT
 
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
 
 Licensed under the OpenSSL license (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy
diff --git a/doc/man3/BN_swap.pod b/doc/man3/BN_swap.pod
index 9f77f22744..3a88ab6b07 100644
--- a/doc/man3/BN_swap.pod
+++ b/doc/man3/BN_swap.pod
@@ -14,6 +14,10 @@ BN_swap - exchange BIGNUMs
 
 BN_swap() exchanges the values of I<a> and I<b>.
 
+=head1 RETURN VALUES
+
+BN_swap() does not return a value.
+
 =head1 COPYRIGHT
 
 Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
diff --git a/doc/man3/CONF_modules_free.pod b/doc/man3/CONF_modules_free.pod
index aacbc62bbc..ee9ee512ed 100644
--- a/doc/man3/CONF_modules_free.pod
+++ b/doc/man3/CONF_modules_free.pod
@@ -32,7 +32,7 @@ CONF_modules_unload() finishes and unloads configuration modules. If
 B<all> is set to B<0> only modules loaded from DSOs will be unloads. If
 B<all> is B<1> all modules, including builtin modules will be unloaded.
 
-=head1 RETURN VALUE
+=head1 RETURN VALUES
 
 None of the functions return a value.
 
@@ -48,7 +48,7 @@ For more information see L<OPENSSL_init_crypto(3)>.
 
 =head1 COPYRIGHT
 
-Copyright 2004-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2004-2017 The OpenSSL Project Authors. All Rights Reserved.
 
 Licensed under the OpenSSL license (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy
diff --git a/doc/man3/DES_random_key.pod b/doc/man3/DES_random_key.pod
index 748ea381d6..b986a1093f 100644
--- a/doc/man3/DES_random_key.pod
+++ b/doc/man3/DES_random_key.pod
@@ -243,6 +243,9 @@ third parameter.  This mostly emulates the normal non-thread-safe semantics
 of crypt(3).
 The B<salt> must be two ASCII characters.
 
+The values returned by DES_fcrypt() and DES_crypt() are terminated by NUL
+character.
+
 DES_enc_write() writes I<len> bytes to file descriptor I<fd> from
 buffer I<buf>. The data is encrypted via I<pcbc_encrypt> (default)
 using I<sched> for the key and I<iv> as a starting vector.  The actual
@@ -282,6 +285,17 @@ functions directly.
 Single-key DES is insecure due to its short key size.  ECB mode is
 not suitable for most applications; see L<des_modes(7)>.
 
+=head1 RETURN VALUES
+
+DES_set_key(), DES_key_sched(), DES_set_key_checked() and DES_is_weak_key()
+return 0 on success or negative values on error.
+
+DES_cbc_cksum() and DES_quad_cksum() return 4-byte integer representing the
+last 4 bytes of the checksum of the input.
+
+DES_fcrypt() returns a pointer to the caller-provided buffer and DES_crypt() -
+to a static buffer on success; otherwise they return NULL.
+
 =head1 HISTORY
 
 The requirement that the B<salt> parameter to DES_crypt() and DES_fcrypt()
@@ -297,7 +311,7 @@ L<EVP_EncryptInit(3)>
 
 =head1 COPYRIGHT
 
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
 
 Licensed under the OpenSSL license (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy
diff --git a/doc/man3/DH_size.pod b/doc/man3/DH_size.pod
index 2421558d1f..c5b0a9fb33 100644
--- a/doc/man3/DH_size.pod
+++ b/doc/man3/DH_size.pod
@@ -28,7 +28,7 @@ B<dh> and B<dh-E<gt>p> must not be B<NULL>.
 DH_security_bits() returns the number of security bits of the given B<dh>
 key. See L<BN_security_bits(3)>.
 
-=head1 RETURN VALUE
+=head1 RETURN VALUES
 
 DH_size() returns the prime size of Diffie-Hellman in bytes.
 
diff --git a/doc/man3/DSA_dup_DH.pod b/doc/man3/DSA_dup_DH.pod
index ecc9fdf71a..c4f7ce7d66 100644
--- a/doc/man3/DSA_dup_DH.pod
+++ b/doc/man3/DSA_dup_DH.pod
@@ -16,7 +16,7 @@ DSA_dup_DH() duplicates DSA parameters/keys as DH parameters/keys. q
 is lost during that conversion, but the resulting DH parameters
 contain its length.
 
-=head1 RETURN VALUE
+=head1 RETURN VALUES
 
 DSA_dup_DH() returns the new B<DH> structure, and NULL on error. The
 error codes can be obtained by L<ERR_get_error(3)>.
@@ -31,7 +31,7 @@ L<DH_new(3)>, L<DSA_new(3)>, L<ERR_get_error(3)>
 
 =head1 COPYRIGHT
 
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
 
 Licensed under the OpenSSL license (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy
diff --git a/doc/man3/DSA_generate_key.pod b/doc/man3/DSA_generate_key.pod
index 65f053179c..7a28abfac6 100644
--- a/doc/man3/DSA_generate_key.pod
+++ b/doc/man3/DSA_generate_key.pod
@@ -17,7 +17,7 @@ a new key pair and stores it in B<a-E<gt>pub_key> and B<a-E<gt>priv_key>.
 
 The PRNG must be seeded prior to calling DSA_generate_key().
 
-=head1 RETURN VALUE
+=head1 RETURN VALUES
 
 DSA_generate_key() returns 1 on success, 0 otherwise.
 The error codes can be obtained by L<ERR_get_error(3)>.
@@ -29,7 +29,7 @@ L<DSA_generate_parameters_ex(3)>
 
 =head1 COPYRIGHT
 
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
 
 Licensed under the OpenSSL license (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy
diff --git a/doc/man3/DSA_generate_parameters.pod b/doc/man3/DSA_generate_parameters.pod
index b01af2cc59..c5204a2fc7 100644
--- a/doc/man3/DSA_generate_parameters.pod
+++ b/doc/man3/DSA_generate_parameters.pod
@@ -92,7 +92,7 @@ When the generator has been found, B<BN_GENCB_call(cb, 3, 1)> is called.
 
 =back
 
-=head1 RETURN VALUE
+=head1 RETURN VALUES
 
 DSA_generate_parameters_ex() returns a 1 on success, or 0 otherwise.
 The error codes can be obtained by L<ERR_get_error(3)>.
@@ -116,7 +116,7 @@ DSA_generate_parameters_ex() instead.
 
 =head1 COPYRIGHT
 
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2017 The OpenSSL Project Authors. All Rights Reserved.
 
 Licensed under the OpenSSL license (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy
diff --git a/doc/man3/DSA_size.pod b/doc/man3/DSA_size.pod
index d48f24ed6e..ee446b55d8 100644
--- a/doc/man3/DSA_size.pod
+++ b/doc/man3/DSA_size.pod
@@ -26,7 +26,7 @@ of bits in the B<p> parameter.
 DSA_security_bits() returns the number of security bits of the given B<dsa>
 key. See L<BN_security_bits(3)>.
 
-=head1 RETURN VALUE
+=head1 RETURN VALUES
 
 DSA_size() returns the signature size in bytes.
 
diff --git a/doc/man3/ENGINE_add.pod b/doc/man3/ENGINE_add.pod
index 2be34938ec..b009949d6e 100644
--- a/doc/man3/ENGINE_add.pod
+++ b/doc/man3/ENGINE_add.pod
@@ -571,6 +571,78 @@ The path to the engines directory.
 
 =back
 
+=head1 RETURN VALUES
+
+ENGINE_get_first(), ENGINE_get_last(), ENGINE_get_next() and ENGINE_get_prev()
+return a valid B<ENGINE> structure or NULL if an error occurred.
+
+ENGINE_add() and ENGINE_remove() return 1 on success or 0 on error.
+
+ENGINE_by_id() returns a valid B<ENGINE> structure or NULL if an error occurred.
+
+ENGINE_init() and ENGINE_finish() return 1 on success or 0 on error.
+
+All ENGINE_get_default_TYPE() functions, ENGINE_get_cipher_engine() and
+ENGINE_get_digest_engine() return a valid B<ENGINE> structure on success or NULL
+if an error occurred.
+
+All ENGINE_set_default_TYPE() functions return 1 on success or 0 on error.
+
+ENGINE_set_default() returns 1 on success or 0 on error.
+
+ENGINE_get_table_flags() returns an unsigned integer value representing the
+global table flags which are used to control the registration behaviour of
+B<ENGINE> implementations.
+
+All ENGINE_register_TYPE() functions return 1 on success or 0 on error.
+
+ENGINE_register_complete() and ENGINE_register_all_complete() return 1 on success
+or 0 on error.
+
+ENGINE_ctrl() returns a positive value on success or others on error.
+
+ENGINE_cmd_is_executable() returns 1 if B<cmd> is executable or 0 otherwise.
+
+ENGINE_ctrl_cmd() and ENGINE_ctrl_cmd_string() return 1 on success or 0 on error.
+
+ENGINE_new() retu