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