Place return values after examples in doc

Reviewed-by: Richard Levitte <levitte@openssl.org>
(cherry picked from commit 4564e77ae9dd1866e8a033f03511b6a1792c024e)

 Conflicts:
	doc/internal/man3/openssl_ctx_get_data.pod (non-existant)
	doc/man3/OPENSSL_s390xcap.pod (non-existant)

Reviewed-by: Matt Caswell <matt@openssl.org>
Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com>
(Merged from https://github.com/openssl/openssl/pull/8736)

diff --git a/doc/man3/ASN1_TIME_set.pod b/doc/man3/ASN1_TIME_set.pod
index a083ebfd1bd422deed1206beacbe42b150d2e64f..66525f95b9a0108759e20203e9c304b2f9708e01 100644 (file)
--- a/doc/man3/ASN1_TIME_set.pod
+++ b/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.
 
 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(),
 =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.
 
 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.
 =head1 HISTORY
 
 The ASN1_TIME_to_tm() function was added in OpenSSL 1.1.1.

diff --git a/doc/man3/ASN1_generate_nconf.pod b/doc/man3/ASN1_generate_nconf.pod
index bf29af62f7295b772c2cc0171b132938feddeab9..df371678b27aa0a6d2d7923eef3430bae52c9944 100644 (file)
--- a/doc/man3/ASN1_generate_nconf.pod
+++ b/doc/man3/ASN1_generate_nconf.pod
@@ -162,6 +162,13 @@ bits are zero.
 
 =back
 
 
 =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:
 =head1 EXAMPLES
 
 A simple IA5String:


@@ -247,13 +254,6 @@ structure:
 
  e=INTEGER:0x010001
 
 
  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)>
 =head1 SEE ALSO
 
 L<ERR_get_error(3)>

diff --git a/doc/man3/BIO_push.pod b/doc/man3/BIO_push.pod
index ce56db9836ff6b2de06143dc8d047658fb27614f..480b73c4607bebcab263cb96b85de9c1aa4e29ac 100644 (file)
--- a/doc/man3/BIO_push.pod
+++ b/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.
 
 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
 =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.
 
 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>
 =head1 SEE ALSO
 
 L<bio>

diff --git a/doc/man3/BIO_s_file.pod b/doc/man3/BIO_s_file.pod
index 23cdc9b684a68f32306948969c2e5669663f96cc..54193159b2baecb99fa181fa687565371ea10492 100644 (file)
--- a/doc/man3/BIO_s_file.pod
+++ b/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.
 
 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":
 =head1 EXAMPLES
 
 File BIO "hello world":


@@ -122,24 +140,6 @@ Alternative technique:
  BIO_printf(out, "Hello World\n");
  BIO_free(out);
 
  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
 =head1 BUGS
 
 BIO_reset() and BIO_seek() are implemented using fseek() on the underlying

diff --git a/doc/man3/CONF_modules_load_file.pod b/doc/man3/CONF_modules_load_file.pod
index 485cf797b12e9da07ec64a4ce15d3c700507a8a8..04fbd60f40b7cf5bf333454715c4ffe04da4ab83 100644 (file)
--- a/doc/man3/CONF_modules_load_file.pod
+++ b/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.
 
 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
 =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);
  }
 
      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)>
 =head1 SEE ALSO
 
 L<config(5)>, L<OPENSSL_config(3)>

diff --git a/doc/man3/EVP_PKEY_set1_RSA.pod b/doc/man3/EVP_PKEY_set1_RSA.pod
index 352e068c236461f9d8cf9203e723fc69718b1db7..a4d672132f3bf1b9c87c2bd8529eb513f123759a 100644 (file)
--- a/doc/man3/EVP_PKEY_set1_RSA.pod
+++ b/doc/man3/EVP_PKEY_set1_RSA.pod
@@ -114,13 +114,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.
 
 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
 =head1 RETURN VALUES
 
 EVP_PKEY_set1_RSA(), EVP_PKEY_set1_DSA(), EVP_PKEY_set1_DH() and


@@ -141,6 +134,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.
 
 
 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)>
 =head1 SEE ALSO
 
 L<EVP_PKEY_new(3)>

diff --git a/doc/man3/OBJ_nid2obj.pod b/doc/man3/OBJ_nid2obj.pod
index cbf889f2c7114c6fe598e7baad5671fe9cebcce4..2c2e42ffe483508db038752bc691a8a6699921a9 100644 (file)
--- a/doc/man3/OBJ_nid2obj.pod
+++ b/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.
 
 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>:
 =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.
 
 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)>
 =head1 SEE ALSO
 
 L<ERR_get_error(3)>

diff --git a/doc/man3/PEM_read_bio_PrivateKey.pod b/doc/man3/PEM_read_bio_PrivateKey.pod
index 744a46f81ed9362d992b1bbd60c6c5c4d9132b87..434861fd3975c0267bf540654bdfeba8e54d7e47 100644 (file)
--- a/doc/man3/PEM_read_bio_PrivateKey.pod
+++ b/doc/man3/PEM_read_bio_PrivateKey.pod
@@ -298,71 +298,6 @@ arbitrary data to be passed to the callback by the application
 B<must> return the number of characters in the passphrase or -1 if
 an error occurred.
 
 B<must> return the number of characters in the passphrase or -1 if
 an error occurred.
 

-=head1 EXAMPLES
-
-Although the PEM routines take several arguments in almost all applications
-most of them are set to 0 or NULL.
-
-Read a certificate in PEM format from a BIO:
-
- X509 *x;
-
- x = PEM_read_bio_X509(bp, NULL, 0, NULL);
- if (x == NULL)
-     /* Error */
-
-Alternative method:
-
- X509 *x = NULL;
-
- if (!PEM_read_bio_X509(bp, &x, 0, NULL))
-     /* Error */
-
-Write a certificate to a BIO:
-
- if (!PEM_write_bio_X509(bp, x))
-     /* Error */
-
-Write a private key (using traditional format) to a BIO using
-triple DES encryption, the pass phrase is prompted for:
-
- if (!PEM_write_bio_PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, NULL))
-     /* Error */
-
-Write a private key (using PKCS#8 format) to a BIO using triple
-DES encryption, using the pass phrase "hello":
-
- if (!PEM_write_bio_PKCS8PrivateKey(bp, key, EVP_des_ede3_cbc(),
-                                    NULL, 0, 0, "hello"))
-     /* Error */
-
-Read a private key from a BIO using a pass phrase callback:
-
- key = PEM_read_bio_PrivateKey(bp, NULL, pass_cb, "My Private Key");
- if (key == NULL)
-     /* Error */
-
-Skeleton pass phrase callback:
-
- int pass_cb(char *buf, int size, int rwflag, void *u)
- {
-
-     /* We'd probably do something else if 'rwflag' is 1 */
-     printf("Enter pass phrase for \"%s\"\n", (char *)u);
-
-     /* get pass phrase, length 'len' into 'tmp' */
-     char *tmp = "hello";
-     if (tmp == NULL) /* An error occurred */
-         return -1;
-
-     size_t len = strlen(tmp);
-
-     if (len > size)
-         len = size;
-     memcpy(buf, tmp, len);
-     return len;
- }
-

 =head1 NOTES
 
 The old B<PrivateKey> write routines are retained for compatibility.
 =head1 NOTES
 
 The old B<PrivateKey> write routines are retained for compatibility.


@@ -460,6 +395,71 @@ if an error occurred.
 
 The write routines return 1 for success or 0 for failure.
 
 
 The write routines return 1 for success or 0 for failure.
 

+=head1 EXAMPLES
+
+Although the PEM routines take several arguments in almost all applications
+most of them are set to 0 or NULL.
+
+Read a certificate in PEM format from a BIO:
+
+ X509 *x;
+
+ x = PEM_read_bio_X509(bp, NULL, 0, NULL);
+ if (x == NULL)
+     /* Error */
+
+Alternative method:
+
+ X509 *x = NULL;
+
+ if (!PEM_read_bio_X509(bp, &x, 0, NULL))
+     /* Error */
+
+Write a certificate to a BIO:
+
+ if (!PEM_write_bio_X509(bp, x))
+     /* Error */
+
+Write a private key (using traditional format) to a BIO using
+triple DES encryption, the pass phrase is prompted for:
+
+ if (!PEM_write_bio_PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, NULL))
+     /* Error */
+
+Write a private key (using PKCS#8 format) to a BIO using triple
+DES encryption, using the pass phrase "hello":
+
+ if (!PEM_write_bio_PKCS8PrivateKey(bp, key, EVP_des_ede3_cbc(),
+                                    NULL, 0, 0, "hello"))
+     /* Error */
+
+Read a private key from a BIO using a pass phrase callback:
+
+ key = PEM_read_bio_PrivateKey(bp, NULL, pass_cb, "My Private Key");
+ if (key == NULL)
+     /* Error */
+
+Skeleton pass phrase callback:
+
+ int pass_cb(char *buf, int size, int rwflag, void *u)
+ {
+
+     /* We'd probably do something else if 'rwflag' is 1 */
+     printf("Enter pass phrase for \"%s\"\n", (char *)u);
+
+     /* get pass phrase, length 'len' into 'tmp' */
+     char *tmp = "hello";
+     if (tmp == NULL) /* An error occurred */
+         return -1;
+
+     size_t len = strlen(tmp);
+
+     if (len > size)
+         len = size;
+     memcpy(buf, tmp, len);
+     return len;
+ }
+

 =head1 HISTORY
 
 The old Netscape certificate sequences were no longer documented
 =head1 HISTORY
 
 The old Netscape certificate sequences were no longer documented

diff --git a/doc/man3/SSL_CONF_cmd.pod b/doc/man3/SSL_CONF_cmd.pod
index a74e7284f9deaf92cd56eb197a96b57ff599a93b..7f2449e379b932e3ce14156215c59fae6c7cbb09 100644 (file)
--- a/doc/man3/SSL_CONF_cmd.pod
+++ b/doc/man3/SSL_CONF_cmd.pod
@@ -594,6 +594,23 @@ checking or translation of the command value. For example if the return
 value is B<SSL_CONF_TYPE_FILE> an application could translate a relative
 pathname to an absolute pathname.
 
 value is B<SSL_CONF_TYPE_FILE> an application could translate a relative
 pathname to an absolute pathname.
 

+=head1 RETURN VALUES
+
+SSL_CONF_cmd() returns 1 if the value of B<cmd> is recognised and B<value> is
+B<NOT> used and 2 if both B<cmd> and B<value> are used. In other words it
+returns the number of arguments processed. This is useful when processing
+command lines.
+
+A return value of -2 means B<cmd> is not recognised.
+
+A return value of -3 means B<cmd> is recognised and the command requires a
+value but B<value> is NULL.
+
+A return code of 0 indicates that both B<cmd> and B<value> are valid but an
+error occurred attempting to perform the operation: for example due to an
+error in the syntax of B<value> in this case the error queue may provide
+additional information.
+

 =head1 EXAMPLES
 
 Set supported signature algorithms:
 =head1 EXAMPLES
 
 Set supported signature algorithms:


@@ -640,23 +657,6 @@ Set supported curves to P-256, P-384:
 
  SSL_CONF_cmd(ctx, "Curves", "P-256:P-384");
 
 
  SSL_CONF_cmd(ctx, "Curves", "P-256:P-384");
 

-=head1 RETURN VALUES
-
-SSL_CONF_cmd() returns 1 if the value of B<cmd> is recognised and B<value> is
-B<NOT> used and 2 if both B<cmd> and B<value> are used. In other words it
-returns the number of arguments processed. This is useful when processing
-command lines.
-
-A return value of -2 means B<cmd> is not recognised.
-
-A return value of -3 means B<cmd> is recognised and the command requires a
-value but B<value> is NULL.
-
-A return code of 0 indicates that both B<cmd> and B<value> are valid but an
-error occurred attempting to perform the operation: for example due to an
-error in the syntax of B<value> in this case the error queue may provide
-additional information.
-

 =head1 SEE ALSO
 
 L<SSL_CONF_CTX_new(3)>,
 =head1 SEE ALSO
 
 L<SSL_CONF_CTX_new(3)>,

diff --git a/doc/man3/SSL_CTX_load_verify_locations.pod b/doc/man3/SSL_CTX_load_verify_locations.pod
index a96aafed5f766acd8f6918aa1e027ada2b14e335..e2637d239bf02ad3833f1acda2f449671eefd2e5 100644 (file)
--- a/doc/man3/SSL_CTX_load_verify_locations.pod
+++ b/doc/man3/SSL_CTX_load_verify_locations.pod
@@ -100,23 +100,6 @@ with different expiration dates. If a "certificate expired" verification
 error occurs, no other certificate will be searched. Make sure to not
 have expired certificates mixed with valid ones.
 
 error occurs, no other certificate will be searched. Make sure to not
 have expired certificates mixed with valid ones.
 

-=head1 EXAMPLES
-
-Generate a CA certificate file with descriptive text from the CA certificates
-ca1.pem ca2.pem ca3.pem:
-
- #!/bin/sh
- rm CAfile.pem
- for i in ca1.pem ca2.pem ca3.pem ; do
-     openssl x509 -in $i -text >> CAfile.pem
- done
-
-Prepare the directory /some/where/certs containing several CA certificates
-for use as B<CApath>:
-
- cd /some/where/certs
- c_rehash .
-

 =head1 RETURN VALUES
 
 For SSL_CTX_load_verify_locations the following return values can occur:
 =head1 RETURN VALUES
 
 For SSL_CTX_load_verify_locations the following return values can occur:


@@ -139,6 +122,23 @@ SSL_CTX_set_default_verify_paths(), SSL_CTX_set_default_verify_dir() and
 SSL_CTX_set_default_verify_file() all return 1 on success or 0 on failure. A
 missing default location is still treated as a success.
 
 SSL_CTX_set_default_verify_file() all return 1 on success or 0 on failure. A
 missing default location is still treated as a success.
 

+=head1 EXAMPLES
+
+Generate a CA certificate file with descriptive text from the CA certificates
+ca1.pem ca2.pem ca3.pem:
+
+ #!/bin/sh
+ rm CAfile.pem
+ for i in ca1.pem ca2.pem ca3.pem ; do
+     openssl x509 -in $i -text >> CAfile.pem
+ done
+
+Prepare the directory /some/where/certs containing several CA certificates
+for use as B<CApath>:
+
+ cd /some/where/certs
+ c_rehash .
+

 =head1 SEE ALSO
 
 L<ssl(7)>,
 =head1 SEE ALSO
 
 L<ssl(7)>,

diff --git a/doc/man3/SSL_CTX_set1_sigalgs.pod b/doc/man3/SSL_CTX_set1_sigalgs.pod
index 93d5320d965a4e8bd42040b1fccce7ebb31a27b0..335ad338a34a0326273726bde760c5b37811040b 100644 (file)
--- a/doc/man3/SSL_CTX_set1_sigalgs.pod
+++ b/doc/man3/SSL_CTX_set1_sigalgs.pod
@@ -83,6 +83,10 @@ be used with the B<_list> forms of the API.
 
 The use of MD5 as a digest is strongly discouraged due to security weaknesses.
 
 
 The use of MD5 as a digest is strongly discouraged due to security weaknesses.
 

+=head1 RETURN VALUES
+
+All these functions return 1 for success and 0 for failure.
+

 =head1 EXAMPLES
 
 Set supported signature algorithms to SHA256 with ECDSA and SHA256 with RSA
 =head1 EXAMPLES
 
 Set supported signature algorithms to SHA256 with ECDSA and SHA256 with RSA


@@ -97,10 +101,6 @@ using a string:
 
  SSL_CTX_set1_sigalgs_list(ctx, "ECDSA+SHA256:RSA+SHA256");
 
 
  SSL_CTX_set1_sigalgs_list(ctx, "ECDSA+SHA256:RSA+SHA256");
 

-=head1 RETURN VALUES
-
-All these functions return 1 for success and 0 for failure.
-

 =head1 SEE ALSO
 
 L<ssl(7)>, L<SSL_get_shared_sigalgs(3)>,
 =head1 SEE ALSO
 
 L<ssl(7)>, L<SSL_get_shared_sigalgs(3)>,

diff --git a/doc/man3/SSL_CTX_set_generate_session_id.pod b/doc/man3/SSL_CTX_set_generate_session_id.pod
index 2bee351a4dbc5664a841e1b766911c33d56c3bf0..9242af6a37850a1ce0e3e270e7930f244b672439 100644 (file)
--- a/doc/man3/SSL_CTX_set_generate_session_id.pod
+++ b/doc/man3/SSL_CTX_set_generate_session_id.pod
@@ -82,6 +82,14 @@ and the same race condition applies.
 The callback must return 0 if it cannot generate a session id for whatever
 reason and return 1 on success.
 
 The callback must return 0 if it cannot generate a session id for whatever
 reason and return 1 on success.
 

+=head1 RETURN VALUES
+
+SSL_CTX_set_generate_session_id() and SSL_set_generate_session_id()
+always return 1.
+
+SSL_has_matching_session_id() returns 1 if another session with the
+same id is already in the cache.
+

 =head1 EXAMPLES
 
 The callback function listed will generate a session id with the
 =head1 EXAMPLES
 
 The callback function listed will generate a session id with the


@@ -114,14 +122,6 @@ server id given, and will fill the rest with pseudo random bytes:
  }
 
 
  }
 
 

-=head1 RETURN VALUES
-
-SSL_CTX_set_generate_session_id() and SSL_set_generate_session_id()
-always return 1.
-
-SSL_has_matching_session_id() returns 1 if another session with the
-same id is already in the cache.
-

 =head1 SEE ALSO
 
 L<ssl(7)>, L<SSL_get_version(3)>
 =head1 SEE ALSO
 
 L<ssl(7)>, L<SSL_get_version(3)>

diff --git a/doc/man3/SSL_CTX_set_tlsext_ticket_key_cb.pod b/doc/man3/SSL_CTX_set_tlsext_ticket_key_cb.pod
index 7a4bb3427027eab55fa245d743187bb51096d38a..9ef0bffcf5bea17d9e89ff807de3b89d1bf105b8 100644 (file)
--- a/doc/man3/SSL_CTX_set_tlsext_ticket_key_cb.pod
+++ b/doc/man3/SSL_CTX_set_tlsext_ticket_key_cb.pod
@@ -121,6 +121,10 @@ For example if a cipher suite uses 256 bit ciphers but only a 128 bit ticket key
 the overall security is only 128 bits because breaking the ticket key will
 enable an attacker to obtain the session keys.
 
 the overall security is only 128 bits because breaking the ticket key will
 enable an attacker to obtain the session keys.
 

+=head1 RETURN VALUES
+
+returns 0 to indicate the callback function was set.
+

 =head1 EXAMPLES
 
 Reference Implementation:
 =head1 EXAMPLES
 
 Reference Implementation:


@@ -175,10 +179,6 @@ Reference Implementation:
      }
  }
 
      }
  }
 

-=head1 RETURN VALUES
-
-returns 0 to indicate the callback function was set.
-

 =head1 SEE ALSO
 
 L<ssl(7)>, L<SSL_set_session(3)>,
 =head1 SEE ALSO
 
 L<ssl(7)>, L<SSL_set_session(3)>,

diff --git a/doc/man3/SSL_CTX_set_tmp_dh_callback.pod b/doc/man3/SSL_CTX_set_tmp_dh_callback.pod
index a2ac1c0adbbc5a31d799cbb4e9173e358c0ec071..521d8b4a7fcdff404773b783e9d4fb71a49e521f 100644 (file)
--- a/doc/man3/SSL_CTX_set_tmp_dh_callback.pod
+++ b/doc/man3/SSL_CTX_set_tmp_dh_callback.pod
@@ -81,6 +81,14 @@ are advised to either use SSL_CTX_set_tmp_dh() or alternatively, use
 the callback but ignore B<keylength> and B<is_export> and simply
 supply at least 2048-bit parameters in the callback.
 
 the callback but ignore B<keylength> and B<is_export> and simply
 supply at least 2048-bit parameters in the callback.
 

+=head1 RETURN VALUES
+
+SSL_CTX_set_tmp_dh_callback() and SSL_set_tmp_dh_callback() do not return
+diagnostic output.
+
+SSL_CTX_set_tmp_dh() and SSL_set_tmp_dh() do return 1 on success and 0
+on failure. Check the error queue to find out the reason of failure.
+

 =head1 EXAMPLES
 
 Setup DH parameters with a key length of 2048 bits. (Error handling
 =head1 EXAMPLES
 
 Setup DH parameters with a key length of 2048 bits. (Error handling


@@ -109,14 +117,6 @@ Code for setting up parameters during server initialization:
      /* Error. */
  ...
 
      /* Error. */
  ...
 

-=head1 RETURN VALUES
-
-SSL_CTX_set_tmp_dh_callback() and SSL_set_tmp_dh_callback() do not return
-diagnostic output.
-
-SSL_CTX_set_tmp_dh() and SSL_set_tmp_dh() do return 1 on success and 0
-on failure. Check the error queue to find out the reason of failure.
-

 =head1 SEE ALSO
 
 L<ssl(7)>, L<SSL_CTX_set_cipher_list(3)>,
 =head1 SEE ALSO
 
 L<ssl(7)>, L<SSL_CTX_set_cipher_list(3)>,

diff --git a/doc/man3/SSL_load_client_CA_file.pod b/doc/man3/SSL_load_client_CA_file.pod
index 412b1a098ca4c0c52fffef7035e419a4448dd892..4372f9f6c1a8c8ca575af19e08efafe0b3dc75fb 100644 (file)
--- a/doc/man3/SSL_load_client_CA_file.pod
+++ b/doc/man3/SSL_load_client_CA_file.pod
@@ -23,21 +23,6 @@ the specific usage as support function for
 L<SSL_CTX_set_client_CA_list(3)>,
 it is not limited to CA certificates.
 
 L<SSL_CTX_set_client_CA_list(3)>,
 it is not limited to CA certificates.
 

-=head1 EXAMPLES
-
-Load names of CAs from file and use it as a client CA list:
-
- SSL_CTX *ctx;
- STACK_OF(X509_NAME) *cert_names;
-
- ...
- cert_names = SSL_load_client_CA_file("/path/to/CAfile.pem");
- if (cert_names != NULL)
-     SSL_CTX_set_client_CA_list(ctx, cert_names);
- else
-     /* error */
- ...
-

 =head1 RETURN VALUES
 
 The following return values can occur:
 =head1 RETURN VALUES
 
 The following return values can occur:


@@ -54,6 +39,21 @@ Pointer to the subject names of the successfully read certificates.
 
 =back
 
 
 =back
 

+=head1 EXAMPLES
+
+Load names of CAs from file and use it as a client CA list:
+
+ SSL_CTX *ctx;
+ STACK_OF(X509_NAME) *cert_names;
+
+ ...
+ cert_names = SSL_load_client_CA_file("/path/to/CAfile.pem");
+ if (cert_names != NULL)
+     SSL_CTX_set_client_CA_list(ctx, cert_names);
+ else
+     /* error */
+ ...
+

 =head1 SEE ALSO
 
 L<ssl(7)>,
 =head1 SEE ALSO
 
 L<ssl(7)>,

diff --git a/doc/man3/X509_NAME_add_entry_by_txt.pod b/doc/man3/X509_NAME_add_entry_by_txt.pod
index b48f0908e813418f57d17e25042d7df6373205fe..f6f61aafe256865249306d3c643075dc4eb905b3 100644 (file)
--- a/doc/man3/X509_NAME_add_entry_by_txt.pod
+++ b/doc/man3/X509_NAME_add_entry_by_txt.pod
@@ -74,6 +74,15 @@ structure respectively. This will then be a multivalued RDN:
 since multivalues RDNs are very seldom used B<set> is almost
 always set to zero.
 
 since multivalues RDNs are very seldom used B<set> is almost
 always set to zero.
 

+=head1 RETURN VALUES
+
+X509_NAME_add_entry_by_txt(), X509_NAME_add_entry_by_OBJ(),
+X509_NAME_add_entry_by_NID() and X509_NAME_add_entry() return 1 for
+success of 0 if an error occurred.
+
+X509_NAME_delete_entry() returns either the deleted B<X509_NAME_ENTRY>
+structure of B<NULL> if an error occurred.
+

 =head1 EXAMPLES
 
 Create an B<X509_NAME> structure:
 =head1 EXAMPLES
 
 Create an B<X509_NAME> structure:


@@ -95,15 +104,6 @@ Create an B<X509_NAME> structure:
                                  "Joe Bloggs", -1, -1, 0))
      /* Error */
 
                                  "Joe Bloggs", -1, -1, 0))
      /* Error */
 

-=head1 RETURN VALUES
-
-X509_NAME_add_entry_by_txt(), X509_NAME_add_entry_by_OBJ(),
-X509_NAME_add_entry_by_NID() and X509_NAME_add_entry() return 1 for
-success of 0 if an error occurred.
-
-X509_NAME_delete_entry() returns either the deleted B<X509_NAME_ENTRY>
-structure of B<NULL> if an error occurred.
-

 =head1 BUGS
 
 B<type> can still be set to B<V_ASN1_APP_CHOOSE> to use a
 =head1 BUGS
 
 B<type> can still be set to B<V_ASN1_APP_CHOOSE> to use a

diff --git a/doc/man3/X509_NAME_get_index_by_NID.pod b/doc/man3/X509_NAME_get_index_by_NID.pod
index 5621806bb5305afd3143a42fc8bb958b4779f340..0012276ddde1c3b6f3004f094c8626b325c72612 100644 (file)
--- a/doc/man3/X509_NAME_get_index_by_NID.pod
+++ b/doc/man3/X509_NAME_get_index_by_NID.pod
@@ -69,6 +69,18 @@ Applications which could pass invalid NIDs to X509_NAME_get_index_by_NID()
 should check for the return value of -2. Alternatively the NID validity
 can be determined first by checking OBJ_nid2obj(nid) is not NULL.
 
 should check for the return value of -2. Alternatively the NID validity
 can be determined first by checking OBJ_nid2obj(nid) is not NULL.
 

+=head1 RETURN VALUES
+
+X509_NAME_get_index_by_NID() and X509_NAME_get_index_by_OBJ()
+return the index of the next matching entry or -1 if not found.
+X509_NAME_get_index_by_NID() can also return -2 if the supplied
+NID is invalid.
+
+X509_NAME_entry_count() returns the total number of entries.
+
+X509_NAME_get_entry() returns an B<X509_NAME> pointer to the
+requested entry or B<NULL> if the index is invalid.
+

 =head1 EXAMPLES
 
 Process all entries:
 =head1 EXAMPLES
 
 Process all entries:


@@ -94,18 +106,6 @@ Process all commonName entries:
      /* Do something with e */
  }
 
      /* Do something with e */
  }
 

-=head1 RETURN VALUES
-
-X509_NAME_get_index_by_NID() and X509_NAME_get_index_by_OBJ()
-return the index of the next matching entry or -1 if not found.
-X509_NAME_get_index_by_NID() can also return -2 if the supplied
-NID is invalid.
-
-X509_NAME_entry_count() returns the total number of entries.
-
-X509_NAME_get_entry() returns an B<X509_NAME> pointer to the
-requested entry or B<NULL> if the index is invalid.
-

 =head1 SEE ALSO
 
 L<ERR_get_error(3)>, L<d2i_X509_NAME(3)>
 =head1 SEE ALSO
 
 L<ERR_get_error(3)>, L<d2i_X509_NAME(3)>

diff --git a/doc/man3/d2i_X509.pod b/doc/man3/d2i_X509.pod
index 71985a44edf430b2a53fc11cba9eb8197b716342..04688a1145c894f92bf5875edef4fe6d188fe7cf 100644 (file)
--- a/doc/man3/d2i_X509.pod
+++ b/doc/man3/d2i_X509.pod
@@ -496,6 +496,19 @@ Represents the B<DigestInfo> structure defined in PKCS#1 and PKCS#7.
 
 =back
 
 
 =back
 

+=head1 RETURN VALUES
+
+d2i_TYPE(), d2i_TYPE_bio() and d2i_TYPE_fp() return a valid B<TYPE> structure
+or B<NULL> if an error occurs.  If the "reuse" capability has been used with
+a valid structure being passed in via B<a>, then the object is not freed in
+the event of error but may be in a potentially invalid or inconsistent state.
+
+i2d_TYPE() returns the number of bytes successfully encoded or a negative
+value if an error occurs.
+
+i2d_TYPE_bio() and i2d_TYPE_fp() return 1 for success and 0 if an error
+occurs.
+

 =head1 EXAMPLES
 
 Allocate and encode the DER encoding of an X509 structure:
 =head1 EXAMPLES
 
 Allocate and encode the DER encoding of an X509 structure:


@@ -586,19 +599,6 @@ structure has been modified after deserialization or previous
 serialization. This is because some objects cache the encoding for
 efficiency reasons.
 
 serialization. This is because some objects cache the encoding for
 efficiency reasons.
 

-=head1 RETURN VALUES
-
-d2i_TYPE(), d2i_TYPE_bio() and d2i_TYPE_fp() return a valid B<TYPE> structure
-or B<NULL> if an error occurs.  If the "reuse" capability has been used with
-a valid structure being passed in via B<a>, then the object is not freed in
-the event of error but may be in a potentially invalid or inconsistent state.
-
-i2d_TYPE() returns the number of bytes successfully encoded or a negative
-value if an error occurs.
-
-i2d_TYPE_bio() and i2d_TYPE_fp() return 1 for success and 0 if an error
-occurs.
-

 =head1 COPYRIGHT
 
 Copyright 1998-2018 The OpenSSL Project Authors. All Rights Reserved.
 =head1 COPYRIGHT
 
 Copyright 1998-2018 The OpenSSL Project Authors. All Rights Reserved.