Place return values after examples in doc

Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from openssl#8338)

doc/internal/man3/openssl_ctx_get_data.pod

@@ -39,6 +39,14 @@ context is freed.
 openssl_ctx_get_data() is used to retrieve a pointer to the data in
 the library context C<ctx> associated with the given C<index>.
 
+=head1 RETURN VALUES
+
+openssl_ctx_new_index() returns -1 on error, otherwise the allocated
+index number.
+
+openssl_ctx_get_data() returns a pointer on success, or C<NULL> on
+failure.
+
 =head1 EXAMPLES
 
 =head2 Initialization
@@ -88,14 +96,6 @@ To get and use the data stored in the library context, simply do this:
   */
  FOO *data = openssl_ctx_get_data(ctx, foo_index);
 
-=head1 RETURN VALUES
-
-openssl_ctx_new_index() returns -1 on error, otherwise the allocated
-index number.
-
-openssl_ctx_get_data() returns a pointer on success, or C<NULL> on
-failure.
-
 =head1 SEE ALSO
 
 L<OPENSSL_CTX(3)>

doc/man3/ASN1_TIME_set.pod

@@ -173,38 +173,6 @@ certificates complying with RFC5280 et al use GMT anyway.
 Use the ASN1_TIME_normalize() function to normalize the time value before
 printing to get GMT results.
 
-=head1 EXAMPLES
-
-Set a time structure to one hour after the current time and print it out:
-
- #include <time.h>
- #include <openssl/asn1.h>
-
- ASN1_TIME *tm;
- time_t t;
- BIO *b;
-
- t = time(NULL);
- tm = ASN1_TIME_adj(NULL, t, 0, 60 * 60);
- b = BIO_new_fp(stdout, BIO_NOCLOSE);
- ASN1_TIME_print(b, tm);
- ASN1_STRING_free(tm);
- BIO_free(b);
-
-Determine if one time is later or sooner than the current time:
-
- int day, sec;
-
- if (!ASN1_TIME_diff(&day, &sec, NULL, to))
-     /* Invalid time format */
-
- if (day > 0 || sec > 0)
-     printf("Later\n");
- else if (day < 0 || sec < 0)
-     printf("Sooner\n");
- else
-     printf("Same\n");
-
 =head1 RETURN VALUES
 
 ASN1_TIME_set(), ASN1_UTCTIME_set(), ASN1_GENERALIZEDTIME_set(), ASN1_TIME_adj(),
@@ -238,6 +206,38 @@ ASN1_TIME_compare() returns -1 if B<a> is before B<b>, 0 if B<a> equals B<b>, or
 ASN1_TIME_to_generalizedtime() returns a pointer to
 the appropriate time structure on success or NULL if an error occurred.
 
+=head1 EXAMPLES
+
+Set a time structure to one hour after the current time and print it out:
+
+ #include <time.h>
+ #include <openssl/asn1.h>
+
+ ASN1_TIME *tm;
+ time_t t;
+ BIO *b;
+
+ t = time(NULL);
+ tm = ASN1_TIME_adj(NULL, t, 0, 60 * 60);
+ b = BIO_new_fp(stdout, BIO_NOCLOSE);
+ ASN1_TIME_print(b, tm);
+ ASN1_STRING_free(tm);
+ BIO_free(b);
+
+Determine if one time is later or sooner than the current time:
+
+ int day, sec;
+
+ if (!ASN1_TIME_diff(&day, &sec, NULL, to))
+     /* Invalid time format */
+
+ if (day > 0 || sec > 0)
+     printf("Later\n");
+ else if (day < 0 || sec < 0)
+     printf("Sooner\n");
+ else
+     printf("Same\n");
+
 =head1 HISTORY
 
 The ASN1_TIME_to_tm() function was added in OpenSSL 1.1.1.

doc/man3/ASN1_generate_nconf.pod

@@ -162,6 +162,13 @@ bits are zero.
 
 =back
 
+=head1 RETURN VALUES
+
+ASN1_generate_nconf() and ASN1_generate_v3() return the encoded
+data as an B<ASN1_TYPE> structure or B<NULL> if an error occurred.
+
+The error codes that can be obtained by L<ERR_get_error(3)>.
+
 =head1 EXAMPLES
 
 A simple IA5String:
@@ -247,13 +254,6 @@ structure:
 
  e=INTEGER:0x010001
 
-=head1 RETURN VALUES
-
-ASN1_generate_nconf() and ASN1_generate_v3() return the encoded
-data as an B<ASN1_TYPE> structure or B<NULL> if an error occurred.
-
-The error codes that can be obtained by L<ERR_get_error(3)>.
-
 =head1 SEE ALSO
 
 L<ERR_get_error(3)>

doc/man3/BIO_push.pod

@@ -36,6 +36,13 @@ The process of calling BIO_push() and BIO_pop() on a BIO may have additional
 consequences (a control call is made to the affected BIOs) any effects will
 be noted in the descriptions of individual BIOs.
 
+=head1 RETURN VALUES
+
+BIO_push() returns the end of the chain, B<b>.
+
+BIO_pop() returns the next BIO in the chain, or NULL if there is no next
+BIO.
+
 =head1 EXAMPLES
 
 For these examples suppose B<md1> and B<md2> are digest BIOs, B<b64> is
@@ -62,13 +69,6 @@ by B<md1> and B<md2>. If the call:
 The call will return B<b64> and the new chain will be B<md1-b64-f> data can
 be written to B<md1> as before.
 
-=head1 RETURN VALUES
-
-BIO_push() returns the end of the chain, B<b>.
-
-BIO_pop() returns the next BIO in the chain, or NULL if there is no next
-BIO.
-
 =head1 SEE ALSO
 
 L<bio>

doc/man3/BIO_s_file.pod

@@ -80,6 +80,24 @@ On Windows BIO_new_files reserves for the filename argument to be
 UTF-8 encoded. In other words if you have to make it work in multi-
 lingual environment, encode file names in UTF-8.
 
+=head1 RETURN VALUES
+
+BIO_s_file() returns the file BIO method.
+
+BIO_new_file() and BIO_new_fp() return a file BIO or NULL if an error
+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_tell() returns the current file position.
+
+BIO_read_filename(), BIO_write_filename(), BIO_append_filename() and
+BIO_rw_filename() return 1 for success or 0 for failure.
+
 =head1 EXAMPLES
 
 File BIO "hello world":
@@ -122,24 +140,6 @@ Alternative technique:
  BIO_printf(out, "Hello World\n");
  BIO_free(out);
 
-=head1 RETURN VALUES
-
-BIO_s_file() returns the file BIO method.
-
-BIO_new_file() and BIO_new_fp() return a file BIO or NULL if an error
-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_tell() returns the current file position.
-
-BIO_read_filename(), BIO_write_filename(), BIO_append_filename() and
-BIO_rw_filename() return 1 for success or 0 for failure.
-
 =head1 BUGS
 
 BIO_reset() and BIO_seek() are implemented using fseek() on the underlying

doc/man3/CONF_modules_load_file.pod

@@ -67,6 +67,12 @@ Applications can use the CONF_modules_load() function if they wish to load a
 configuration file themselves and have finer control over how errors are
 treated.
 
+=head1 RETURN VALUES
+
+These functions return 1 for success and a zero or negative value for
+failure. If module errors are not ignored the return code will reflect the
+return value of the failing module (this will always be zero or negative).
+
 =head1 EXAMPLES
 
 Load a configuration file and print out any errors and exit (missing file
@@ -122,12 +128,6 @@ Load and parse configuration file manually, custom error handling:
      NCONF_free(cnf);
  }
 
-=head1 RETURN VALUES
-
-These functions return 1 for success and a zero or negative value for
-failure. If module errors are not ignored the return code will reflect the
-return value of the failing module (this will always be zero or negative).
-
 =head1 SEE ALSO
 
 L<config(5)>, L<OPENSSL_config(3)>

doc/man3/EVP_PKEY_set1_RSA.pod

@@ -111,13 +111,6 @@ is no longer possible: the equivalent is EVP_PKEY_base_id(pkey).
 EVP_PKEY_set1_engine() is typically used by an ENGINE returning an HSM
 key as part of its routine to load a private key.
 
-=head1 EXAMPLES
-
-After loading an ECC key, it is possible to convert it to using SM2
-algorithms with EVP_PKEY_set_alias_type:
-
- EVP_PKEY_set_alias_type(pkey, EVP_PKEY_SM2);
-
 =head1 RETURN VALUES
 
 EVP_PKEY_set1_RSA(), EVP_PKEY_set1_DSA(), EVP_PKEY_set1_DH() and
@@ -138,6 +131,13 @@ EVP_PKEY_set1_engine() returns 1 for success and 0 for failure.
 
 EVP_PKEY_set_alias_type() returns 1 for success and 0 for error.
 
+=head1 EXAMPLES
+
+After loading an ECC key, it is possible to convert it to using SM2
+algorithms with EVP_PKEY_set_alias_type:
+
+ EVP_PKEY_set_alias_type(pkey, EVP_PKEY_SM2);
+
 =head1 SEE ALSO
 
 L<EVP_PKEY_new(3)>

doc/man3/OBJ_nid2obj.pod

@@ -130,6 +130,17 @@ These functions cannot return B<const> because an B<ASN1_OBJECT> can
 represent both an internal, constant, OID and a dynamically-created one.
 The latter cannot be constant because it needs to be freed after use.
 
+=head1 RETURN VALUES
+
+OBJ_nid2obj() returns an B<ASN1_OBJECT> structure or B<NULL> is an
+error occurred.
+
+OBJ_nid2ln() and OBJ_nid2sn() returns a valid string or B<NULL>
+on error.
+
+OBJ_obj2nid(), OBJ_ln2nid(), OBJ_sn2nid() and OBJ_txt2nid() return
+a NID or B<NID_undef> on error.
+
 =head1 EXAMPLES
 
 Create an object for B<commonName>:
@@ -159,17 +170,6 @@ Instead B<buf> must point to a valid buffer and B<buf_len> should
 be set to a positive value. A buffer length of 80 should be more
 than enough to handle any OID encountered in practice.
 
-=head1 RETURN VALUES
-
-OBJ_nid2obj() returns an B<ASN1_OBJECT> structure or B<NULL> is an
-error occurred.
-
-OBJ_nid2ln() and OBJ_nid2sn() returns a valid string or B<NULL>
-on error.
-
-OBJ_obj2nid(), OBJ_ln2nid(), OBJ_sn2nid() and OBJ_txt2nid() return
-a NID or B<NID_undef> on error.
-
 =head1 SEE ALSO
 
 L<ERR_get_error(3)>

doc/man3/OPENSSL_s390xcap.pod

@@ -139,6 +139,10 @@ the numbering is continuous across 64-bit mask boundaries.
       # 20    1<<43    KMA-GCM-AES-256
       :
 
+=head1 RETURN VALUES
+
+Not available.
+
 =head1 EXAMPLES
 
 Disables all instruction set extensions which the z196 processor does not implement:
@@ -153,10 +157,6 @@ Disables the KM-XTS-AES and and the KIMD-SHAKE function codes:
 
  OPENSSL_s390xcap="km:~0x2800:~0;kimd:~0xc000000:~0"
 
-=head1 RETURN VALUES
-
-Not available.
-
 =head1 SEE ALSO
 
 [1] z/Architecture Principles of Operation, SA22-7832-11