Rename OSSL_SERIALIZER / OSSL_DESERIALIZER to OSSL_ENCODE / OSSL_DECODE

[openssl.git] / doc / man3 / BIO_f_ssl.pod

diff --git a/doc/man3/BIO_f_ssl.pod b/doc/man3/BIO_f_ssl.pod
index 2bc9afea6f2a5b262ce969b1859b52c8ba106a15..6a21e0c41cdf57df219aa278e7086a7078bae4eb 100644 (file)
--- a/doc/man3/BIO_f_ssl.pod
+++ b/doc/man3/BIO_f_ssl.pod
@@ -11,7 +11,7 @@ BIO_ssl_shutdown - SSL BIO
 
 =head1 SYNOPSIS
 
-=for comment multiple includes
+=for openssl multiple includes
 
  #include <openssl/bio.h>
  #include <openssl/ssl.h>
@@ -96,12 +96,15 @@ chain and calling SSL_shutdown() on its internal SSL
 pointer.
 
 BIO_do_handshake() attempts to complete an SSL handshake on the
-supplied BIO and establish the SSL connection. It returns 1
-if the connection was established successfully. A zero or negative
-value is returned if the connection could not be established, the
-call BIO_should_retry() should be used for non blocking connect BIOs
-to determine if the call should be retried. If an SSL connection has
-already been established this call has no effect.
+-supplied BIO and establish the SSL connection.
+For non-SSL BIOs the connection is done typically at TCP level.
+If domain name resolution yields multiple IP addresses all of them are tried
+after connect() failures.
+The function returns 1 if the connection was established successfully.
+A zero or negative value is returned if the connection could not be established.
+The call BIO_should_retry() should be used for nonblocking connect BIOs
+to determine if the call should be retried.
+If a connection has already been established this call has no effect.
 
 =head1 NOTES
 
@@ -129,9 +132,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
 
-This SSL/TLS client example, attempts to retrieve a page from an
+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
 SSL/TLS web server. The I/O routines are identical to those of the
 unencrypted example in L<BIO_s_connect(3)>.
 
@@ -241,12 +260,6 @@ a client and also echoes the request to standard output.
      exit(1);
  }
 
- if (BIO_do_accept(acpt) <= 0) {
-     fprintf(stderr, "Error in connection\n");
-     ERR_print_errors_fp(stderr);
-     exit(1);
- }
-
  /* We only want one connection so remove and free accept BIO */
  sbio = BIO_pop(acpt);
  BIO_free_all(acpt);
@@ -277,9 +290,9 @@ a client and also echoes the request to standard output.
  BIO_flush(sbio);
  BIO_free_all(sbio);
 
-=head1 BUGS
+=head1 HISTORY
 
-In OpenSSL versions before 1.0.0 the BIO_pop() call was handled incorrectly,
+In OpenSSL before 1.0.0 the BIO_pop() call was handled incorrectly,
 the I/O BIO reference count was incorrectly incremented (instead of
 decremented) and dissociated with the SSL BIO even if the SSL BIO was not
 explicitly being popped (e.g. a pop higher up the chain). Applications which
@@ -288,9 +301,9 @@ be modified to handle this fix or they may free up an already freed BIO.
 
 =head1 COPYRIGHT
 
-Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.
 
-Licensed under the OpenSSL license (the "License").  You may not use
+Licensed under the Apache License 2.0 (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy
 in the file LICENSE in the source distribution or at
 L<https://www.openssl.org/source/license.html>.