Place return values after examples in doc

Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/8338)

diff --git a/doc/internal/man3/openssl_ctx_get_data.pod b/doc/internal/man3/openssl_ctx_get_data.pod
index ee98dc27334a5584fdd26fd270f6a176e376aaad..db066ad9b69176ce0186c7cfe7c3f321d06cf7e8 100644 (file)
--- a/doc/internal/man3/openssl_ctx_get_data.pod
+++ b/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>.
 
 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
 =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);
 
   */
  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)>
 =head1 SEE ALSO
 
 L<OPENSSL_CTX(3)>

diff --git a/doc/man3/ASN1_TIME_set.pod b/doc/man3/ASN1_TIME_set.pod
index 009e6f64c593d8d798e940f52b92842070d01bff..9db9970f5ec00e8d8ffdeb1bf14b5d62e44aaf37 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 1dfe9f7b9bd55ce7c8597bd131825dd52df624ad..0ea71d2b3e56628459af018953c9c930f1db25d4 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 02b6f18182c3f90b72b297918ce5a568bbe43a6d..c5919f3cfdacf163711a3e74323085dfcdcd823b 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 5f0cdbe1052a34041857f780a0db6a91ee137a42..0d6cc98c160a67c402ee9c91863a8b221623b30a 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 037c7f255c793c60700c1c2cf80358f3c0308d3a..c0623eb7215fb4e3e17f7205d44306c711bac852 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 67471c9f56118ccdf4bd2ae0838c846529571d20..868e3372c8d4e9f516fadeb856a8bcc825faea3d 100644 (file)
--- a/doc/man3/EVP_PKEY_set1_RSA.pod
+++ b/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.
 
 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


@@ -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.
 
 
 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 0345062d9fd70864d3730e84f2349fa235787d83..79923d1ce8120f26d66ecd1e7c47364cb65b0918 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/OPENSSL_s390xcap.pod b/doc/man3/OPENSSL_s390xcap.pod
index cf5cf8e46712e8104f8a778d697224b1182ab495..34c029a40c67f1a7ee696685a5ec19c9d65a7c3e 100644 (file)
--- a/doc/man3/OPENSSL_s390xcap.pod
+++ b/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
       :
 
       # 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:
 =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"
 
 
  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
 =head1 SEE ALSO
 
 [1] z/Architecture Principles of Operation, SA22-7832-11

diff --git a/doc/man3/PEM_read_bio_PrivateKey.pod b/doc/man3/PEM_read_bio_PrivateKey.pod
index 1f538155fd41e1cbb582a7b66dcfb2af79328f50..54dc27e184d99c8b6f4b0ccb998fd5c4977f8cd8 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 5759c7f12551f43318c1af845dbf58ab2f99a6a6..5c58268f497dbb141c998dd0469f4e646c6f5091 100644 (file)
--- a/doc/man3/SSL_CONF_cmd.pod
+++ b/doc/man3/SSL_CONF_cmd.pod
@@ -598,6 +598,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:


@@ -644,23 +661,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 03dec156066711e183e2796345bc227849b7ca91..b955c60eede09dc9495f354bd86f1345a8c33ade 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 642f71a75c584a872143b67c36a7670daf1c5e2c..eb3100634626fca5368d36ce3188239e984f8ab5 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 37ecd026847daf869946e01c630230cf1eff89be..8bf8e152d5e86acb00957b8e14d029dbbd811427 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 9013abc2a2c68d283ae45742d929bcd809a9c87a..88e70c5fa23591f308edcc014970cae4b94e1dac 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 f69c37cd22ede2b981d4593c6778f03fa9133bc7..bc1dafa53b0087a4dee632339b99d65aed01e5db 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 e1922d5fb464cfb786d908651e56265d55a980ba..23449dd3c32300d7002040eb69e1b98eda398916 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 a7b123573fbd46fbfe7949db791d9141a88d6c07..7f5296612165cdbbe8c0003461b3fe9a8d934f4c 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 12843736fafad1062a1fa595a57e07d1f790bf8d..f287849c0ed9b1b9635a691122fd0869e93e446e 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 c11da95178d8ef996c90f7c6aa86db77842e162e..23dc73c33622960a75544b766fc93d04bfbd5ff9 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.