diff options
| -rw-r--r-- | doc/man3/BIO_f_ssl.pod | 36 | ||||
| -rw-r--r-- | doc/man3/BIO_s_mem.pod | 19 | ||||
| -rw-r--r-- | doc/man3/BIO_set_callback.pod | 10 | ||||
| -rw-r--r-- | doc/man3/SSL_CTX_get0_param.pod | 14 | ||||
| -rwxr-xr-x | util/find-doc-nits | 24 |
5 files changed, 52 insertions, 51 deletions
diff --git a/doc/man3/BIO_f_ssl.pod b/doc/man3/BIO_f_ssl.pod index ba44133023..82bb16c5ba 100644 --- a/doc/man3/BIO_f_ssl.pod +++ b/doc/man3/BIO_f_ssl.pod @@ -129,9 +129,25 @@ BIO_set_ssl(), BIO_get_ssl(), BIO_set_ssl_mode(), BIO_set_ssl_renegotiate_bytes(), BIO_set_ssl_renegotiate_timeout(), BIO_get_num_renegotiates(), and BIO_do_handshake() are implemented as macros. -=head1 EXAMPLE +=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 EXAMPLES -This SSL/TLS client example, attempts to retrieve a page from an +This SSL/TLS client example attempts to retrieve a page from an SSL/TLS web server. The I/O routines are identical to those of the unencrypted example in L<BIO_s_connect(3)>. @@ -271,22 +287,6 @@ 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, diff --git a/doc/man3/BIO_s_mem.pod b/doc/man3/BIO_s_mem.pod index 7cb9efa92c..b7c6fdf860 100644 --- a/doc/man3/BIO_s_mem.pod +++ b/doc/man3/BIO_s_mem.pod @@ -118,7 +118,16 @@ BIO_FLAGS_NONCLEAR_RST set has the same effect as a write operation. There should be an option to set the maximum size of a memory BIO. -=head1 EXAMPLE +=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 EXAMPLES Create a memory BIO and write some data to it: @@ -139,14 +148,6 @@ 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 diff --git a/doc/man3/BIO_set_callback.pod b/doc/man3/BIO_set_callback.pod index a420267a4c..afa482d4a6 100644 --- a/doc/man3/BIO_set_callback.pod +++ b/doc/man3/BIO_set_callback.pod @@ -211,11 +211,6 @@ the actual call parameter, see B<BIO_callback_ctrl>. =back -=head1 EXAMPLE - -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 @@ -228,6 +223,11 @@ 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 EXAMPLE + +The BIO_debug_callback() function is a good example, its source is +in crypto/bio/bio_cb.c + =head1 COPYRIGHT Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved. diff --git a/doc/man3/SSL_CTX_get0_param.pod b/doc/man3/SSL_CTX_get0_param.pod index ff9706455f..795bbf03b1 100644 --- a/doc/man3/SSL_CTX_get0_param.pod +++ b/doc/man3/SSL_CTX_get0_param.pod @@ -29,13 +29,6 @@ Typically parameters are retrieved from an B<SSL_CTX> or B<SSL> structure using SSL_CTX_get0_param() or SSL_get0_param() and an application modifies them to suit its needs: for example to add a hostname check. -=head1 EXAMPLE - -Check hostname matches "www.foo.com" in peer certificate: - - X509_VERIFY_PARAM *vpm = SSL_get0_param(ssl); - X509_VERIFY_PARAM_set1_host(vpm, "www.foo.com", 0); - =head1 RETURN VALUES SSL_CTX_get0_param() and SSL_get0_param() return a pointer to an @@ -44,6 +37,13 @@ B<X509_VERIFY_PARAM> structure. SSL_CTX_set1_param() and SSL_set1_param() return 1 for success and 0 for failure. +=head1 EXAMPLE + +Check hostname matches "www.foo.com" in peer certificate: + + X509_VERIFY_PARAM *vpm = SSL_get0_param(ssl); + X509_VERIFY_PARAM_set1_host(vpm, "www.foo.com", 0); + =head1 SEE ALSO L<X509_VERIFY_PARAM_set_flags(3)> diff --git a/util/find-doc-nits b/util/find-doc-nits index 499a68fdc4..563a6956a7 100755 --- a/util/find-doc-nits +++ b/util/find-doc-nits @@ -151,17 +151,17 @@ sub name_synopsis() } } -# Check if SECTION is located before BEFORE +# Check if SECTION ($3) is located before BEFORE ($4) sub check_section_location() { - my $filename = shift; + my $id = shift; my $contents = shift; my $section = shift; my $before = shift; - return unless $contents =~ /=head1 $section/ - and $contents =~ /=head1 $before/; - print "$filename: $section should be placed before $before section\n" + return + unless $contents =~ /=head1 $section/ and $contents =~ /=head1 $before/; + print "$id $section should be placed before $before section\n" if $contents =~ /=head1 $before.*=head1 $section/ms; } @@ -178,15 +178,15 @@ sub check() close POD; } - # Check if EXAMPLES is located after RETURN VALUES section. - &check_section_location($filename, $contents, "RETURN VALUES", "EXAMPLES") if $filename =~ m|man3/|; - # Check if HISTORY is located after SEE ALSO - &check_section_location($filename, $contents, "SEE ALSO", "HISTORY") if $filename =~ m|man3/|; - # Check if SEE ALSO is located after EXAMPLES - &check_section_location($filename, $contents, "EXAMPLES", "SEE ALSO") if $filename =~ m|man3/|; - my $id = "${filename}:1:"; + # Check ordering of some sections in man3 + if ( $filename =~ m|man3/| ) { + &check_section_location($id, $contents, "RETURN VALUES", "EXAMPLE"); + &check_section_location($id, $contents, "SEE ALSO", "HISTORY"); + &check_section_location($id, $contents, "EXAMPLE", "SEE ALSO"); + } + &name_synopsis($id, $filename, $contents) unless $contents =~ /=for comment generic/ or $filename =~ m@man[157]/@; |