Commit d090fc00 authored by Paul Yang's avatar Paul Yang Committed by Dr. Matthias St. Pierre
Browse files

Place return values after examples in doc 



Reviewed-by: default avatarRichard 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: default avatarMatt Caswell <matt@openssl.org>
Reviewed-by: default avatarMatthias St. Pierre <Matthias.St.Pierre@ncp-e.com>
(Merged from https://github.com/openssl/openssl/pull/8736)
parent e861d659

doc/man3/ASN1_TIME_set.pod

+32 −32
Original line number Diff line number Diff line
@@ -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

+7 −7
Original line number Diff line number Diff line
@@ -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

+7 −7
Original line number Diff line number Diff line
@@ -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

+18 −18
Original line number Diff line number Diff line
@@ -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

+6 −6
Original line number Diff line number Diff line
@@ -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)>