BIO_s_connect(3) OpenSSL BIO_s_connect(3)
NAME
BIO_s_connect, BIO_set_conn_hostname, BIO_set_conn_port, BIO_set_conn_ip, BIO_set_conn_int_port, BIO_get_conn_host- name, BIO_get_conn_port, BIO_get_conn_ip, BIO_get_conn_int_port, BIO_set_nbio, BIO_do_connect - con- nect BIO
LIBRARY
libcrypto, -lcrypto
SYNOPSIS
#include <openssl/bio.h> 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) #define BIO_set_nbio(b,n) BIO_ctrl(b,BIO_C_SET_NBIO,(n),NULL) #define BIO_do_connect(b) BIO_do_handshake(b)
DESCRIPTION
BIO_s_connect() returns the connect BIO method. This is a wrapper round the platform's TCP/IP socket connection rou- tines. Using connect BIOs TCP/IP connections can be made and data transferred using only BIO routines. In this way any plat- form specific operations are hidden by the BIO abstrac- tion. Read and write operations on a connect BIO will perform I/O on the underlying connection. If no connection is established and the port and hostname (see below) is set up properly then a connection is established first. Connect BIOs support BIO_puts() but not BIO_gets(). If the close flag is set on a connect BIO then any active connection is shutdown and the socket closed when the BIO is freed. 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. 2001-04-12 0.9.6g 1 BIO_s_connect(3) OpenSSL BIO_s_connect(3) BIO_get_fd() places the underlying socket in c if it is not NULL, it also returns the socket . If c is not NULL it should be of type (int *). BIO_set_conn_hostname() uses the string name 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 "host- name/any/other/path" or "hostname:port/any/other/path". BIO_set_conn_port() sets the port to port. port can be the numerical form or a string such as "http". A string will be looked up first using getservbyname() on the host plat- form but if that 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 ip using binary form, that is four bytes specifying the IP address in big- endian form. BIO_set_conn_int_port() sets the port using port. port should be of type (int *). BIO_get_conn_hostname() returns the hostname of the con- nect BIO or 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 port as an int. BIO_set_nbio() sets the non blocking I/O flag to n. If n is zero then blocking I/O is set. If n is 1 then non blocking I/O 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_do_connect() attempts to connect the supplied BIO. It returns 1 if the connection was established successfully. A zero or negative 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.
NOTES
If blocking I/O is set then a non positive return value from any I/O call is caused by an error condition, although a zero return will normally mean that the connec- tion was closed. 2001-04-12 0.9.6g 2 BIO_s_connect(3) OpenSSL BIO_s_connect(3) If the port name is supplied as part of the host name then this will 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 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. 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 indi- cation that a connection attempt would block, the applica- tion should then take appropriate action to wait until the underlying socket has connected and retry the call.
RETURN VALUES
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_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 con- nected 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 2001-04-12 0.9.6g 3 BIO_s_connect(3) OpenSSL BIO_s_connect(3) successfully established and 0 or -1 if the connection failed.
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);
SEE ALSO
TBA 2001-04-12 0.9.6g 4
Powered by man-cgi (2024-08-26). Maintained for NetBSD by Kimmo Suominen. Based on man-cgi by Panagiotis Christias.