BIO_s_connect.pod: Improve doc of BIO_set_conn_hostname() etc.

[thirdparty/openssl.git] / doc / man3 / BIO_s_connect.pod

diff --git a/doc/man3/BIO_s_connect.pod b/doc/man3/BIO_s_connect.pod
index 4714fde160aaad919f0915df29bebb3a5ec5f8ec..9a029066ff12d60cea7f03be25a5dd1321e3de8d 100644 (file)
--- a/doc/man3/BIO_s_connect.pod
+++ b/doc/man3/BIO_s_connect.pod
@@ -2,17 +2,18 @@
 
 =head1 NAME
 
-BIO_set_conn_address, BIO_get_conn_address,
-BIO_s_connect, BIO_new_connect, BIO_set_conn_hostname, BIO_set_conn_port,
-BIO_set_conn_ip_family, BIO_get_conn_ip_family,
+BIO_s_connect, BIO_new_connect,
+BIO_set_conn_hostname, BIO_set_conn_port,
+BIO_set_conn_address, BIO_set_conn_ip_family,
 BIO_get_conn_hostname, BIO_get_conn_port,
+BIO_get_conn_address, BIO_get_conn_ip_family,
 BIO_set_nbio, BIO_do_connect - connect BIO
 
 =head1 SYNOPSIS
 
  #include <openssl/bio.h>
 
- const BIO_METHOD * BIO_s_connect(void);
+ const BIO_METHOD *BIO_s_connect(void);
 
  BIO *BIO_new_connect(char *name);
 
@@ -53,20 +54,18 @@ Calling BIO_reset() on a connect BIO will close any active
 connection and reset the BIO into a state where it can connect
 to the same host again.
 
-BIO_get_fd() places the underlying socket in B<c> if it is not NULL,
-it also returns the socket . If B<c> is not NULL it should be of
-type (int *).
+BIO_new_connect() combines BIO_new() and BIO_set_conn_hostname() into
+a single call: that is it creates a new connect BIO with hostname B<name>.
 
 BIO_set_conn_hostname() uses the string B<name> to set the hostname.
 The hostname can be an IP address; if the address is an IPv6 one, it
-must be enclosed with brackets. The hostname can also include the
-port in the form hostname:port.
+must be enclosed with brackets C<[> and C<]>.
+The hostname can also include the port in the form hostname:port;
+see L<BIO_parse_hostserv(3)> and BIO_set_conn_port() for details.
 
 BIO_set_conn_port() sets the port to B<port>. B<port> can be the
-numerical form or a string such as "http". A string will be looked
-up first using getservbyname() on the host platform but if that
-fails a standard table of port names will be used. This internal
-list is http, telnet, socks, https, ssl, ftp, and gopher.
+numerical form or a service string such as "http", which
+will be mapped to a port number using the system function getservbyname().
 
 BIO_set_conn_address() sets the address and port information using
 a BIO_ADDR(3ssl).
@@ -91,9 +90,6 @@ is set. Blocking I/O is the default. The call to BIO_set_nbio()
 should be made before the connection is established because
 non blocking I/O is set during the connect process.
 
-BIO_new_connect() combines BIO_new() and BIO_set_conn_hostname() into
-a single call: that is it creates a new connect BIO with B<name>.
-
 BIO_do_connect() attempts to connect the supplied BIO.
 This performs an SSL/TLS handshake as far as supported by the BIO.
 For non-SSL BIOs the connection is done typically at TCP level.
@@ -144,9 +140,6 @@ BIO_set_nbio(), and BIO_do_connect() are macros.
 
 BIO_s_connect() returns the connect BIO method.
 
-BIO_get_fd() returns the socket or -1 if the BIO has not
-been initialized.
-
 BIO_set_conn_address(), BIO_set_conn_port(), and BIO_set_conn_ip_family()
 always return 1.
 
@@ -198,7 +191,7 @@ to retrieve a page and copy the result to standard output.
 
 =head1 SEE ALSO
 
-L<BIO_ADDR(3)>
+L<BIO_ADDR(3)>, L<BIO_parse_hostserv(3)>
 
 =head1 HISTORY