diff options
author | Dr. David von Oheimb <David.von.Oheimb@siemens.com> | 2021-04-21 12:47:35 +0200 |
---|---|---|
committer | Dr. David von Oheimb <dev@ddvo.net> | 2021-04-22 20:40:24 +0200 |
commit | 75f036c6c5cf3608a63ddc6598698e82bcfdb9bf (patch) | |
tree | 3b06ab11fc85dbfaba41c19dc181097930e15bd9 /doc/man3 | |
parent | ef203432f7b551382216e9aa7de00039e6d45ac0 (diff) |
BIO_s_connect.pod: Improve doc of BIO_set_conn_hostname() etc.
Reviewed-by: Paul Dale <pauli@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/14967)
Diffstat (limited to 'doc/man3')
-rw-r--r-- | doc/man3/BIO_parse_hostserv.pod | 3 | ||||
-rw-r--r-- | doc/man3/BIO_s_connect.pod | 33 | ||||
-rw-r--r-- | doc/man3/BIO_s_fd.pod | 4 |
3 files changed, 17 insertions, 23 deletions
diff --git a/doc/man3/BIO_parse_hostserv.pod b/doc/man3/BIO_parse_hostserv.pod index ca5a82376b..27d4735b50 100644 --- a/doc/man3/BIO_parse_hostserv.pod +++ b/doc/man3/BIO_parse_hostserv.pod @@ -38,7 +38,8 @@ The syntax the BIO_parse_hostserv() recognises is: The host part can be a name or an IP address. If it's a IPv6 address, it MUST be enclosed in brackets, such as '[::1]'. -The service part can be a service name or its port number. +The service part can be a service name or its port number. A service name +will be mapped to a port number using the system function getservbyname(). The returned values will depend on the given B<hostserv> string and B<hostserv_prio>, as follows: diff --git a/doc/man3/BIO_s_connect.pod b/doc/man3/BIO_s_connect.pod index 4714fde160..9a029066ff 100644 --- 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 diff --git a/doc/man3/BIO_s_fd.pod b/doc/man3/BIO_s_fd.pod index f4f4239fe9..40a223b61d 100644 --- a/doc/man3/BIO_s_fd.pod +++ b/doc/man3/BIO_s_fd.pod @@ -38,8 +38,8 @@ B<lseek(fd, 0, 1)>. BIO_set_fd() sets the file descriptor of BIO B<b> to B<fd> and the close flag to B<c>. -BIO_get_fd() places the file descriptor in B<c> if it is not NULL, it also -returns the file descriptor. +BIO_get_fd() places the file descriptor of BIO B<b> in B<c> if it is not NULL. +It also returns the file descriptor. BIO_new_fd() returns a file descriptor BIO using B<fd> and B<close_flag>. |