1*2175Sjp161948=pod 2*2175Sjp161948 3*2175Sjp161948=head1 NAME 4*2175Sjp161948 5*2175Sjp161948BIO_s_connect, BIO_set_conn_hostname, BIO_set_conn_port, 6*2175Sjp161948BIO_set_conn_ip, BIO_set_conn_int_port, BIO_get_conn_hostname, 7*2175Sjp161948BIO_get_conn_port, BIO_get_conn_ip, BIO_get_conn_int_port, 8*2175Sjp161948BIO_set_nbio, BIO_do_connect - connect BIO 9*2175Sjp161948 10*2175Sjp161948=head1 SYNOPSIS 11*2175Sjp161948 12*2175Sjp161948 #include <openssl/bio.h> 13*2175Sjp161948 14*2175Sjp161948 BIO_METHOD * BIO_s_connect(void); 15*2175Sjp161948 16*2175Sjp161948 BIO *BIO_new_connect(char *name); 17*2175Sjp161948 18*2175Sjp161948 long BIO_set_conn_hostname(BIO *b, char *name); 19*2175Sjp161948 long BIO_set_conn_port(BIO *b, char *port); 20*2175Sjp161948 long BIO_set_conn_ip(BIO *b, char *ip); 21*2175Sjp161948 long BIO_set_conn_int_port(BIO *b, char *port); 22*2175Sjp161948 char *BIO_get_conn_hostname(BIO *b); 23*2175Sjp161948 char *BIO_get_conn_port(BIO *b); 24*2175Sjp161948 char *BIO_get_conn_ip(BIO *b, dummy); 25*2175Sjp161948 long BIO_get_conn_int_port(BIO *b, int port); 26*2175Sjp161948 27*2175Sjp161948 long BIO_set_nbio(BIO *b, long n); 28*2175Sjp161948 29*2175Sjp161948 int BIO_do_connect(BIO *b); 30*2175Sjp161948 31*2175Sjp161948=head1 DESCRIPTION 32*2175Sjp161948 33*2175Sjp161948BIO_s_connect() returns the connect BIO method. This is a wrapper 34*2175Sjp161948round the platform's TCP/IP socket connection routines. 35*2175Sjp161948 36*2175Sjp161948Using connect BIOs, TCP/IP connections can be made and data 37*2175Sjp161948transferred using only BIO routines. In this way any platform 38*2175Sjp161948specific operations are hidden by the BIO abstraction. 39*2175Sjp161948 40*2175Sjp161948Read and write operations on a connect BIO will perform I/O 41*2175Sjp161948on the underlying connection. If no connection is established 42*2175Sjp161948and the port and hostname (see below) is set up properly then 43*2175Sjp161948a connection is established first. 44*2175Sjp161948 45*2175Sjp161948Connect BIOs support BIO_puts() but not BIO_gets(). 46*2175Sjp161948 47*2175Sjp161948If the close flag is set on a connect BIO then any active 48*2175Sjp161948connection is shutdown and the socket closed when the BIO 49*2175Sjp161948is freed. 50*2175Sjp161948 51*2175Sjp161948Calling BIO_reset() on a connect BIO will close any active 52*2175Sjp161948connection and reset the BIO into a state where it can connect 53*2175Sjp161948to the same host again. 54*2175Sjp161948 55*2175Sjp161948BIO_get_fd() places the underlying socket in B<c> if it is not NULL, 56*2175Sjp161948it also returns the socket . If B<c> is not NULL it should be of 57*2175Sjp161948type (int *). 58*2175Sjp161948 59*2175Sjp161948BIO_set_conn_hostname() uses the string B<name> to set the hostname. 60*2175Sjp161948The hostname can be an IP address. The hostname can also include the 61*2175Sjp161948port in the form hostname:port . It is also acceptable to use the 62*2175Sjp161948form "hostname/any/other/path" or "hostname:port/any/other/path". 63*2175Sjp161948 64*2175Sjp161948BIO_set_conn_port() sets the port to B<port>. B<port> can be the 65*2175Sjp161948numerical form or a string such as "http". A string will be looked 66*2175Sjp161948up first using getservbyname() on the host platform but if that 67*2175Sjp161948fails a standard table of port names will be used. Currently the 68*2175Sjp161948list is http, telnet, socks, https, ssl, ftp, gopher and wais. 69*2175Sjp161948 70*2175Sjp161948BIO_set_conn_ip() sets the IP address to B<ip> using binary form, 71*2175Sjp161948that is four bytes specifying the IP address in big-endian form. 72*2175Sjp161948 73*2175Sjp161948BIO_set_conn_int_port() sets the port using B<port>. B<port> should 74*2175Sjp161948be of type (int *). 75*2175Sjp161948 76*2175Sjp161948BIO_get_conn_hostname() returns the hostname of the connect BIO or 77*2175Sjp161948NULL if the BIO is initialized but no hostname is set. 78*2175Sjp161948This return value is an internal pointer which should not be modified. 79*2175Sjp161948 80*2175Sjp161948BIO_get_conn_port() returns the port as a string. 81*2175Sjp161948 82*2175Sjp161948BIO_get_conn_ip() returns the IP address in binary form. 83*2175Sjp161948 84*2175Sjp161948BIO_get_conn_int_port() returns the port as an int. 85*2175Sjp161948 86*2175Sjp161948BIO_set_nbio() sets the non blocking I/O flag to B<n>. If B<n> is 87*2175Sjp161948zero then blocking I/O is set. If B<n> is 1 then non blocking I/O 88*2175Sjp161948is set. Blocking I/O is the default. The call to BIO_set_nbio() 89*2175Sjp161948should be made before the connection is established because 90*2175Sjp161948non blocking I/O is set during the connect process. 91*2175Sjp161948 92*2175Sjp161948BIO_new_connect() combines BIO_new() and BIO_set_conn_hostname() into 93*2175Sjp161948a single call: that is it creates a new connect BIO with B<name>. 94*2175Sjp161948 95*2175Sjp161948BIO_do_connect() attempts to connect the supplied BIO. It returns 1 96*2175Sjp161948if the connection was established successfully. A zero or negative 97*2175Sjp161948value is returned if the connection could not be established, the 98*2175Sjp161948call BIO_should_retry() should be used for non blocking connect BIOs 99*2175Sjp161948to determine if the call should be retried. 100*2175Sjp161948 101*2175Sjp161948=head1 NOTES 102*2175Sjp161948 103*2175Sjp161948If blocking I/O is set then a non positive return value from any 104*2175Sjp161948I/O call is caused by an error condition, although a zero return 105*2175Sjp161948will normally mean that the connection was closed. 106*2175Sjp161948 107*2175Sjp161948If the port name is supplied as part of the host name then this will 108*2175Sjp161948override any value set with BIO_set_conn_port(). This may be undesirable 109*2175Sjp161948if the application does not wish to allow connection to arbitrary 110*2175Sjp161948ports. This can be avoided by checking for the presence of the ':' 111*2175Sjp161948character in the passed hostname and either indicating an error or 112*2175Sjp161948truncating the string at that point. 113*2175Sjp161948 114*2175Sjp161948The values returned by BIO_get_conn_hostname(), BIO_get_conn_port(), 115*2175Sjp161948BIO_get_conn_ip() and BIO_get_conn_int_port() are updated when a 116*2175Sjp161948connection attempt is made. Before any connection attempt the values 117*2175Sjp161948returned are those set by the application itself. 118*2175Sjp161948 119*2175Sjp161948Applications do not have to call BIO_do_connect() but may wish to do 120*2175Sjp161948so to separate the connection process from other I/O processing. 121*2175Sjp161948 122*2175Sjp161948If non blocking I/O is set then retries will be requested as appropriate. 123*2175Sjp161948 124*2175Sjp161948It addition to BIO_should_read() and BIO_should_write() it is also 125*2175Sjp161948possible for BIO_should_io_special() to be true during the initial 126*2175Sjp161948connection process with the reason BIO_RR_CONNECT. If this is returned 127*2175Sjp161948then this is an indication that a connection attempt would block, 128*2175Sjp161948the application should then take appropriate action to wait until 129*2175Sjp161948the underlying socket has connected and retry the call. 130*2175Sjp161948 131*2175Sjp161948BIO_set_conn_hostname(), BIO_set_conn_port(), BIO_set_conn_ip(), 132*2175Sjp161948BIO_set_conn_int_port(), BIO_get_conn_hostname(), BIO_get_conn_port(), 133*2175Sjp161948BIO_get_conn_ip(), BIO_get_conn_int_port(), BIO_set_nbio() and 134*2175Sjp161948BIO_do_connect() are macros. 135*2175Sjp161948 136*2175Sjp161948=head1 RETURN VALUES 137*2175Sjp161948 138*2175Sjp161948BIO_s_connect() returns the connect BIO method. 139*2175Sjp161948 140*2175Sjp161948BIO_get_fd() returns the socket or -1 if the BIO has not 141*2175Sjp161948been initialized. 142*2175Sjp161948 143*2175Sjp161948BIO_set_conn_hostname(), BIO_set_conn_port(), BIO_set_conn_ip() and 144*2175Sjp161948BIO_set_conn_int_port() always return 1. 145*2175Sjp161948 146*2175Sjp161948BIO_get_conn_hostname() returns the connected hostname or NULL is 147*2175Sjp161948none was set. 148*2175Sjp161948 149*2175Sjp161948BIO_get_conn_port() returns a string representing the connected 150*2175Sjp161948port or NULL if not set. 151*2175Sjp161948 152*2175Sjp161948BIO_get_conn_ip() returns a pointer to the connected IP address in 153*2175Sjp161948binary form or all zeros if not set. 154*2175Sjp161948 155*2175Sjp161948BIO_get_conn_int_port() returns the connected port or 0 if none was 156*2175Sjp161948set. 157*2175Sjp161948 158*2175Sjp161948BIO_set_nbio() always returns 1. 159*2175Sjp161948 160*2175Sjp161948BIO_do_connect() returns 1 if the connection was successfully 161*2175Sjp161948established and 0 or -1 if the connection failed. 162*2175Sjp161948 163*2175Sjp161948=head1 EXAMPLE 164*2175Sjp161948 165*2175Sjp161948This is example connects to a webserver on the local host and attempts 166*2175Sjp161948to retrieve a page and copy the result to standard output. 167*2175Sjp161948 168*2175Sjp161948 169*2175Sjp161948 BIO *cbio, *out; 170*2175Sjp161948 int len; 171*2175Sjp161948 char tmpbuf[1024]; 172*2175Sjp161948 ERR_load_crypto_strings(); 173*2175Sjp161948 cbio = BIO_new_connect("localhost:http"); 174*2175Sjp161948 out = BIO_new_fp(stdout, BIO_NOCLOSE); 175*2175Sjp161948 if(BIO_do_connect(cbio) <= 0) { 176*2175Sjp161948 fprintf(stderr, "Error connecting to server\n"); 177*2175Sjp161948 ERR_print_errors_fp(stderr); 178*2175Sjp161948 /* whatever ... */ 179*2175Sjp161948 } 180*2175Sjp161948 BIO_puts(cbio, "GET / HTTP/1.0\n\n"); 181*2175Sjp161948 for(;;) { 182*2175Sjp161948 len = BIO_read(cbio, tmpbuf, 1024); 183*2175Sjp161948 if(len <= 0) break; 184*2175Sjp161948 BIO_write(out, tmpbuf, len); 185*2175Sjp161948 } 186*2175Sjp161948 BIO_free(cbio); 187*2175Sjp161948 BIO_free(out); 188*2175Sjp161948 189*2175Sjp161948 190*2175Sjp161948=head1 SEE ALSO 191*2175Sjp161948 192*2175Sjp161948TBA 193