X-Git-Url: https://git.openssl.org/?p=openssl.git;a=blobdiff_plain;f=doc%2Fcrypto%2FBIO_s_connect.pod;h=18ece4c91f66fe45ec10bce81b343d302e73e4ed;hp=07370ab250739348476df3a37196977a0a83c99b;hb=687403fb2486eec0502ccb36689d3f57e0a173aa;hpb=8eec1389fb8e649fe971046b4108a66544955017 diff --git a/doc/crypto/BIO_s_connect.pod b/doc/crypto/BIO_s_connect.pod index 07370ab250..18ece4c91f 100644 --- a/doc/crypto/BIO_s_connect.pod +++ b/doc/crypto/BIO_s_connect.pod @@ -2,7 +2,7 @@ =head1 NAME -BIO_s_connect, BIO_set_conn_hostname, BIO_set_conn_port, +BIO_s_connect, BIO_new_connect, BIO_set_conn_hostname, BIO_set_conn_port, BIO_set_conn_ip, BIO_set_conn_int_port, BIO_get_conn_hostname, BIO_get_conn_port, BIO_get_conn_ip, BIO_get_conn_int_port, BIO_set_nbio, BIO_do_connect - connect BIO @@ -13,25 +13,27 @@ BIO_set_nbio, BIO_do_connect - connect BIO BIO_METHOD * BIO_s_connect(void); - #define BIO_set_conn_hostname(b,name) BIO_ctrl(b,BIO_C_SET_CONNECT,0,(char *)name) - #define BIO_set_conn_port(b,port) BIO_ctrl(b,BIO_C_SET_CONNECT,1,(char *)port) - #define BIO_set_conn_ip(b,ip) BIO_ctrl(b,BIO_C_SET_CONNECT,2,(char *)ip) - #define BIO_set_conn_int_port(b,port) BIO_ctrl(b,BIO_C_SET_CONNECT,3,(char *)port) - #define BIO_get_conn_hostname(b) BIO_ptr_ctrl(b,BIO_C_GET_CONNECT,0) - #define BIO_get_conn_port(b) BIO_ptr_ctrl(b,BIO_C_GET_CONNECT,1) - #define BIO_get_conn_ip(b,ip) BIO_ptr_ctrl(b,BIO_C_SET_CONNECT,2) - #define BIO_get_conn_int_port(b,port) BIO_int_ctrl(b,BIO_C_SET_CONNECT,3,port) + BIO *BIO_new_connect(char *name); - #define BIO_set_nbio(b,n) BIO_ctrl(b,BIO_C_SET_NBIO,(n),NULL) + long BIO_set_conn_hostname(BIO *b, char *name); + long BIO_set_conn_port(BIO *b, char *port); + long BIO_set_conn_ip(BIO *b, char *ip); + long BIO_set_conn_int_port(BIO *b, char *port); + char *BIO_get_conn_hostname(BIO *b); + char *BIO_get_conn_port(BIO *b); + char *BIO_get_conn_ip(BIO *b, dummy); + long BIO_get_conn_int_port(BIO *b, int port); - #define BIO_do_connect(b) BIO_do_handshake(b) + long BIO_set_nbio(BIO *b, long n); + + int BIO_do_connect(BIO *b); =head1 DESCRIPTION BIO_s_connect() returns the connect BIO method. This is a wrapper round the platform's TCP/IP socket connection routines. -Using connect BIOs TCP/IP connections can be made and data +Using connect BIOs, TCP/IP connections can be made and data transferred using only BIO routines. In this way any platform specific operations are hidden by the BIO abstraction. @@ -54,7 +56,7 @@ BIO_get_fd() places the underlying socket in B if it is not NULL, it also returns the socket . If B is not NULL it should be of type (int *). -BIO_set_conn_hostname() uses the string B to set the hostname +BIO_set_conn_hostname() uses the string B to set the hostname. The hostname can be an IP address. The hostname can also include the port in the form hostname:port . It is also acceptable to use the form "hostname/any/other/path" or "hostname:port/any/other/path". @@ -66,24 +68,29 @@ fails a standard table of port names will be used. Currently the list is http, telnet, socks, https, ssl, ftp, gopher and wais. BIO_set_conn_ip() sets the IP address to B using binary form, -that is four bytes specifying the IP address in big endian form. +that is four bytes specifying the IP address in big-endian form. BIO_set_conn_int_port() sets the port using B. B should be of type (int *). BIO_get_conn_hostname() returns the hostname of the connect BIO or -NULL if the BIO is initialised but no hostname is set. +NULL if the BIO is initialized but no hostname is set. This return value is an internal pointer which should not be modified. BIO_get_conn_port() returns the port as a string. BIO_get_conn_ip() returns the IP address in binary form. -BIO_get_conn_int_port() returns the host name as an int. +BIO_get_conn_int_port() returns the port as an int. BIO_set_nbio() sets the non blocking I/O flag to B. If B is zero then blocking I/O is set. If B is 1 then non blocking I/O -is set. +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. BIO_do_connect() attempts to connect the supplied BIO. It returns 1 if the connection was established successfully. A zero or negative @@ -91,7 +98,6 @@ 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. - =head1 NOTES If blocking I/O is set then a non positive return value from any @@ -99,15 +105,19 @@ I/O call is caused by an error condition, although a zero return will normally mean that the connection was closed. If the port name is supplied as part of the host name then this will -override any value set with BIO_set_conn_port(). +override any value set with BIO_set_conn_port(). This may be undesirable +if the application does not wish to allow connection to arbitrary +ports. This can be avoided by checking for the presence of the ':' +character in the passed hostname and either indicating an error or +truncating the string at that point. The values returned by BIO_get_conn_hostname(), BIO_get_conn_port(), BIO_get_conn_ip() and BIO_get_conn_int_port() are updated when a connection attempt is made. Before any connection attempt the values returned are those set by the application itself. -Applications do not have to call BIO_do_connect() but can do so to -separate the connection process from other I/O processing. +Applications do not have to call BIO_do_connect() but may wish to do +so to separate the connection process from other I/O processing. If non blocking I/O is set then retries will be requested as appropriate. @@ -115,19 +125,67 @@ It addition to BIO_should_read() and BIO_should_write() it is also possible for BIO_should_io_special() to be true during the initial connection process with the reason BIO_RR_CONNECT. If this is returned then this is an indication that a connection attempt would block, -the application should then take appropiate action to wait until +the application should then take appropriate action to wait until the underlying socket has connected and retry the call. +BIO_set_conn_hostname(), BIO_set_conn_port(), BIO_set_conn_ip(), +BIO_set_conn_int_port(), BIO_get_conn_hostname(), BIO_get_conn_port(), +BIO_get_conn_ip(), BIO_get_conn_int_port(), BIO_set_nbio() and +BIO_do_connect() are macros. + =head1 RETURN VALUES BIO_s_connect() returns the connect BIO method. BIO_get_fd() returns the socket or -1 if the BIO has not -been initialised. +been initialized. -=head1 EXAMPLES +BIO_set_conn_hostname(), BIO_set_conn_port(), BIO_set_conn_ip() and +BIO_set_conn_int_port() always return 1. + +BIO_get_conn_hostname() returns the connected hostname or NULL is +none was set. + +BIO_get_conn_port() returns a string representing the connected +port or NULL if not set. + +BIO_get_conn_ip() returns a pointer to the connected IP address in +binary form or all zeros if not set. + +BIO_get_conn_int_port() returns the connected port or 0 if none was +set. + +BIO_set_nbio() always returns 1. + +BIO_do_connect() returns 1 if the connection was successfully +established and 0 or -1 if the connection failed. + +=head1 EXAMPLE + +This is example connects to a webserver on the local host and attempts +to retrieve a page and copy the result to standard output. + + + BIO *cbio, *out; + int len; + char tmpbuf[1024]; + ERR_load_crypto_strings(); + cbio = BIO_new_connect("localhost:http"); + out = BIO_new_fp(stdout, BIO_NOCLOSE); + if(BIO_do_connect(cbio) <= 0) { + fprintf(stderr, "Error connecting to server\n"); + ERR_print_errors_fp(stderr); + /* whatever ... */ + } + BIO_puts(cbio, "GET / HTTP/1.0\n\n"); + for(;;) { + len = BIO_read(cbio, tmpbuf, 1024); + if(len <= 0) break; + BIO_write(out, tmpbuf, len); + } + BIO_free(cbio); + BIO_free(out); -TBA =head1 SEE ALSO