168651Skris=pod 268651Skris 368651Skris=head1 NAME 468651Skris 568651SkrisBIO_s_connect, BIO_set_conn_hostname, BIO_set_conn_port, 668651SkrisBIO_set_conn_ip, BIO_set_conn_int_port, BIO_get_conn_hostname, 768651SkrisBIO_get_conn_port, BIO_get_conn_ip, BIO_get_conn_int_port, 868651SkrisBIO_set_nbio, BIO_do_connect - connect BIO 968651Skris 1068651Skris=head1 SYNOPSIS 1168651Skris 1268651Skris #include <openssl/bio.h> 1368651Skris 1468651Skris BIO_METHOD * BIO_s_connect(void); 1568651Skris 16109998Smarkm BIO *BIO_new_connect(char *name); 1768651Skris 18109998Smarkm long BIO_set_conn_hostname(BIO *b, char *name); 19109998Smarkm long BIO_set_conn_port(BIO *b, char *port); 20109998Smarkm long BIO_set_conn_ip(BIO *b, char *ip); 21109998Smarkm long BIO_set_conn_int_port(BIO *b, char *port); 22109998Smarkm char *BIO_get_conn_hostname(BIO *b); 23109998Smarkm char *BIO_get_conn_port(BIO *b); 24109998Smarkm char *BIO_get_conn_ip(BIO *b, dummy); 25109998Smarkm long BIO_get_conn_int_port(BIO *b, int port); 2668651Skris 27109998Smarkm long BIO_set_nbio(BIO *b, long n); 2868651Skris 29109998Smarkm int BIO_do_connect(BIO *b); 30109998Smarkm 3168651Skris=head1 DESCRIPTION 3268651Skris 3368651SkrisBIO_s_connect() returns the connect BIO method. This is a wrapper 3468651Skrisround the platform's TCP/IP socket connection routines. 3568651Skris 36109998SmarkmUsing connect BIOs, TCP/IP connections can be made and data 3768651Skristransferred using only BIO routines. In this way any platform 3868651Skrisspecific operations are hidden by the BIO abstraction. 3968651Skris 4068651SkrisRead and write operations on a connect BIO will perform I/O 4168651Skrison the underlying connection. If no connection is established 4268651Skrisand the port and hostname (see below) is set up properly then 4368651Skrisa connection is established first. 4468651Skris 4568651SkrisConnect BIOs support BIO_puts() but not BIO_gets(). 4668651Skris 4768651SkrisIf the close flag is set on a connect BIO then any active 4868651Skrisconnection is shutdown and the socket closed when the BIO 4968651Skrisis freed. 5068651Skris 5168651SkrisCalling BIO_reset() on a connect BIO will close any active 5268651Skrisconnection and reset the BIO into a state where it can connect 5368651Skristo the same host again. 5468651Skris 5568651SkrisBIO_get_fd() places the underlying socket in B<c> if it is not NULL, 5668651Skrisit also returns the socket . If B<c> is not NULL it should be of 5768651Skristype (int *). 5868651Skris 59109998SmarkmBIO_set_conn_hostname() uses the string B<name> to set the hostname. 6068651SkrisThe hostname can be an IP address. The hostname can also include the 6168651Skrisport in the form hostname:port . It is also acceptable to use the 6268651Skrisform "hostname/any/other/path" or "hostname:port/any/other/path". 6368651Skris 6468651SkrisBIO_set_conn_port() sets the port to B<port>. B<port> can be the 6568651Skrisnumerical form or a string such as "http". A string will be looked 6668651Skrisup first using getservbyname() on the host platform but if that 6768651Skrisfails a standard table of port names will be used. Currently the 6868651Skrislist is http, telnet, socks, https, ssl, ftp, gopher and wais. 6968651Skris 7068651SkrisBIO_set_conn_ip() sets the IP address to B<ip> using binary form, 7168651Skristhat is four bytes specifying the IP address in big-endian form. 7268651Skris 7368651SkrisBIO_set_conn_int_port() sets the port using B<port>. B<port> should 7468651Skrisbe of type (int *). 7568651Skris 7668651SkrisBIO_get_conn_hostname() returns the hostname of the connect BIO or 7768651SkrisNULL if the BIO is initialized but no hostname is set. 7868651SkrisThis return value is an internal pointer which should not be modified. 7968651Skris 8068651SkrisBIO_get_conn_port() returns the port as a string. 8168651Skris 8268651SkrisBIO_get_conn_ip() returns the IP address in binary form. 8368651Skris 8468651SkrisBIO_get_conn_int_port() returns the port as an int. 8568651Skris 8668651SkrisBIO_set_nbio() sets the non blocking I/O flag to B<n>. If B<n> is 8768651Skriszero then blocking I/O is set. If B<n> is 1 then non blocking I/O 8868651Skrisis set. Blocking I/O is the default. The call to BIO_set_nbio() 8968651Skrisshould be made before the connection is established because 9068651Skrisnon blocking I/O is set during the connect process. 9168651Skris 92109998SmarkmBIO_new_connect() combines BIO_new() and BIO_set_conn_hostname() into 93109998Smarkma single call: that is it creates a new connect BIO with B<name>. 94109998Smarkm 9568651SkrisBIO_do_connect() attempts to connect the supplied BIO. It returns 1 9668651Skrisif the connection was established successfully. A zero or negative 9768651Skrisvalue is returned if the connection could not be established, the 9868651Skriscall BIO_should_retry() should be used for non blocking connect BIOs 9968651Skristo determine if the call should be retried. 10068651Skris 10168651Skris=head1 NOTES 10268651Skris 10368651SkrisIf blocking I/O is set then a non positive return value from any 10468651SkrisI/O call is caused by an error condition, although a zero return 10568651Skriswill normally mean that the connection was closed. 10668651Skris 10768651SkrisIf the port name is supplied as part of the host name then this will 10868651Skrisoverride any value set with BIO_set_conn_port(). This may be undesirable 10968651Skrisif the application does not wish to allow connection to arbitrary 11068651Skrisports. This can be avoided by checking for the presence of the ':' 11168651Skrischaracter in the passed hostname and either indicating an error or 11268651Skristruncating the string at that point. 11368651Skris 11468651SkrisThe values returned by BIO_get_conn_hostname(), BIO_get_conn_port(), 11568651SkrisBIO_get_conn_ip() and BIO_get_conn_int_port() are updated when a 11668651Skrisconnection attempt is made. Before any connection attempt the values 11768651Skrisreturned are those set by the application itself. 11868651Skris 11968651SkrisApplications do not have to call BIO_do_connect() but may wish to do 12068651Skrisso to separate the connection process from other I/O processing. 12168651Skris 12268651SkrisIf non blocking I/O is set then retries will be requested as appropriate. 12368651Skris 12468651SkrisIt addition to BIO_should_read() and BIO_should_write() it is also 12568651Skrispossible for BIO_should_io_special() to be true during the initial 12668651Skrisconnection process with the reason BIO_RR_CONNECT. If this is returned 12768651Skristhen this is an indication that a connection attempt would block, 12868651Skristhe application should then take appropriate action to wait until 12968651Skristhe underlying socket has connected and retry the call. 13068651Skris 131109998SmarkmBIO_set_conn_hostname(), BIO_set_conn_port(), BIO_set_conn_ip(), 132109998SmarkmBIO_set_conn_int_port(), BIO_get_conn_hostname(), BIO_get_conn_port(), 133109998SmarkmBIO_get_conn_ip(), BIO_get_conn_int_port(), BIO_set_nbio() and 134109998SmarkmBIO_do_connect() are macros. 135109998Smarkm 13668651Skris=head1 RETURN VALUES 13768651Skris 13868651SkrisBIO_s_connect() returns the connect BIO method. 13968651Skris 14068651SkrisBIO_get_fd() returns the socket or -1 if the BIO has not 14168651Skrisbeen initialized. 14268651Skris 14368651SkrisBIO_set_conn_hostname(), BIO_set_conn_port(), BIO_set_conn_ip() and 14468651SkrisBIO_set_conn_int_port() always return 1. 14568651Skris 14668651SkrisBIO_get_conn_hostname() returns the connected hostname or NULL is 14768651Skrisnone was set. 14868651Skris 14968651SkrisBIO_get_conn_port() returns a string representing the connected 15068651Skrisport or NULL if not set. 15168651Skris 15268651SkrisBIO_get_conn_ip() returns a pointer to the connected IP address in 15368651Skrisbinary form or all zeros if not set. 15468651Skris 15568651SkrisBIO_get_conn_int_port() returns the connected port or 0 if none was 15668651Skrisset. 15768651Skris 15868651SkrisBIO_set_nbio() always returns 1. 15968651Skris 16068651SkrisBIO_do_connect() returns 1 if the connection was successfully 16168651Skrisestablished and 0 or -1 if the connection failed. 16268651Skris 16368651Skris=head1 EXAMPLE 16468651Skris 16568651SkrisThis is example connects to a webserver on the local host and attempts 16668651Skristo retrieve a page and copy the result to standard output. 16768651Skris 16868651Skris 16968651Skris BIO *cbio, *out; 17068651Skris int len; 17168651Skris char tmpbuf[1024]; 17268651Skris ERR_load_crypto_strings(); 17368651Skris cbio = BIO_new_connect("localhost:http"); 17468651Skris out = BIO_new_fp(stdout, BIO_NOCLOSE); 17568651Skris if(BIO_do_connect(cbio) <= 0) { 17668651Skris fprintf(stderr, "Error connecting to server\n"); 17768651Skris ERR_print_errors_fp(stderr); 17868651Skris /* whatever ... */ 17968651Skris } 18068651Skris BIO_puts(cbio, "GET / HTTP/1.0\n\n"); 18168651Skris for(;;) { 18268651Skris len = BIO_read(cbio, tmpbuf, 1024); 18368651Skris if(len <= 0) break; 18468651Skris BIO_write(out, tmpbuf, len); 18568651Skris } 18668651Skris BIO_free(cbio); 18768651Skris BIO_free(out); 18868651Skris 18968651Skris 19068651Skris=head1 SEE ALSO 19168651Skris 19268651SkrisTBA 193