The find-doc-nits script only looked for EXAMPLES, not EXAMPLE.
Fix the pattern and then fix the errors that resulted.
Reviewed-by: Richard Levitte <levitte@openssl.org>
Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com>
(Merged from https://github.com/openssl/openssl/pull/9602)
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)>.
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,
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:
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
=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
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.
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
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)>
}
}
-# 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;
}
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]/@;
projects / openssl / commitdiff