diff options
author | marha <marha@users.sourceforge.net> | 2009-06-28 22:07:26 +0000 |
---|---|---|
committer | marha <marha@users.sourceforge.net> | 2009-06-28 22:07:26 +0000 |
commit | 3562e78743202e43aec8727005182a2558117eca (patch) | |
tree | 8f9113a77d12470c5c851a2a8e4cb02e89df7d43 /openssl/doc/crypto/BIO_s_connect.pod | |
download | vcxsrv-3562e78743202e43aec8727005182a2558117eca.tar.gz vcxsrv-3562e78743202e43aec8727005182a2558117eca.tar.bz2 vcxsrv-3562e78743202e43aec8727005182a2558117eca.zip |
Checked in the following released items:
xkeyboard-config-1.4.tar.gz
ttf-bitstream-vera-1.10.tar.gz
font-alias-1.0.1.tar.gz
font-sun-misc-1.0.0.tar.gz
font-sun-misc-1.0.0.tar.gz
font-sony-misc-1.0.0.tar.gz
font-schumacher-misc-1.0.0.tar.gz
font-mutt-misc-1.0.0.tar.gz
font-misc-misc-1.0.0.tar.gz
font-misc-meltho-1.0.0.tar.gz
font-micro-misc-1.0.0.tar.gz
font-jis-misc-1.0.0.tar.gz
font-isas-misc-1.0.0.tar.gz
font-dec-misc-1.0.0.tar.gz
font-daewoo-misc-1.0.0.tar.gz
font-cursor-misc-1.0.0.tar.gz
font-arabic-misc-1.0.0.tar.gz
font-winitzki-cyrillic-1.0.0.tar.gz
font-misc-cyrillic-1.0.0.tar.gz
font-cronyx-cyrillic-1.0.0.tar.gz
font-screen-cyrillic-1.0.1.tar.gz
font-xfree86-type1-1.0.1.tar.gz
font-adobe-utopia-type1-1.0.1.tar.gz
font-ibm-type1-1.0.0.tar.gz
font-bitstream-type1-1.0.0.tar.gz
font-bitstream-speedo-1.0.0.tar.gz
font-bh-ttf-1.0.0.tar.gz
font-bh-type1-1.0.0.tar.gz
font-bitstream-100dpi-1.0.0.tar.gz
font-bh-lucidatypewriter-100dpi-1.0.0.tar.gz
font-bh-100dpi-1.0.0.tar.gz
font-adobe-utopia-100dpi-1.0.1.tar.gz
font-adobe-100dpi-1.0.0.tar.gz
font-util-1.0.1.tar.gz
font-bitstream-75dpi-1.0.0.tar.gz
font-bh-lucidatypewriter-75dpi-1.0.0.tar.gz
font-adobe-utopia-75dpi-1.0.1.tar.gz
font-bh-75dpi-1.0.0.tar.gz
bdftopcf-1.0.1.tar.gz
font-adobe-75dpi-1.0.0.tar.gz
mkfontscale-1.0.6.tar.gz
openssl-0.9.8k.tar.gz
bigreqsproto-1.0.2.tar.gz
xtrans-1.2.2.tar.gz
resourceproto-1.0.2.tar.gz
inputproto-1.4.4.tar.gz
compositeproto-0.4.tar.gz
damageproto-1.1.0.tar.gz
zlib-1.2.3.tar.gz
xkbcomp-1.0.5.tar.gz
freetype-2.3.9.tar.gz
pthreads-w32-2-8-0-release.tar.gz
pixman-0.12.0.tar.gz
kbproto-1.0.3.tar.gz
evieext-1.0.2.tar.gz
fixesproto-4.0.tar.gz
recordproto-1.13.2.tar.gz
randrproto-1.2.2.tar.gz
scrnsaverproto-1.1.0.tar.gz
renderproto-0.9.3.tar.gz
xcmiscproto-1.1.2.tar.gz
fontsproto-2.0.2.tar.gz
xextproto-7.0.3.tar.gz
xproto-7.0.14.tar.gz
libXdmcp-1.0.2.tar.gz
libxkbfile-1.0.5.tar.gz
libfontenc-1.0.4.tar.gz
libXfont-1.3.4.tar.gz
libX11-1.1.5.tar.gz
libXau-1.0.4.tar.gz
libxcb-1.1.tar.gz
xorg-server-1.5.3.tar.gz
Diffstat (limited to 'openssl/doc/crypto/BIO_s_connect.pod')
-rw-r--r-- | openssl/doc/crypto/BIO_s_connect.pod | 192 |
1 files changed, 192 insertions, 0 deletions
diff --git a/openssl/doc/crypto/BIO_s_connect.pod b/openssl/doc/crypto/BIO_s_connect.pod new file mode 100644 index 000000000..bcf7d8dca --- /dev/null +++ b/openssl/doc/crypto/BIO_s_connect.pod @@ -0,0 +1,192 @@ +=pod + +=head1 NAME + +BIO_s_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 + +=head1 SYNOPSIS + + #include <openssl/bio.h> + + BIO_METHOD * BIO_s_connect(void); + + BIO *BIO_new_connect(char *name); + + 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); + + 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 +transferred using only BIO routines. In this way any platform +specific operations are hidden by the BIO abstraction. + +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. + +BIO_get_fd() places the underlying socket in B<c> if it is not NULL, +it also returns the socket . If B<c> is not NULL it should be of +type (int *). + +BIO_set_conn_hostname() uses the string B<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 "hostname/any/other/path" or "hostname:port/any/other/path". + +BIO_set_conn_port() sets the port to B<port>. B<port> can be the +numerical form or a string such as "http". A string will be looked +up first using getservbyname() on the host platform 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 B<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 B<port>. B<port> should +be of type (int *). + +BIO_get_conn_hostname() returns the hostname of the connect 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 B<n>. If B<n> is +zero then blocking I/O is set. If B<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_new_connect() combines BIO_new() and BIO_set_conn_hostname() into +a single call: that is it creates a new connect BIO with B<name>. + +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. + +=head1 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 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(). 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 indication that a connection attempt would block, +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 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 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); + + +=head1 SEE ALSO + +TBA |