aboutsummaryrefslogtreecommitdiff
path: root/openssl/doc/crypto/BIO_s_connect.pod
diff options
context:
space:
mode:
authormarha <marha@users.sourceforge.net>2009-06-28 22:07:26 +0000
committermarha <marha@users.sourceforge.net>2009-06-28 22:07:26 +0000
commit3562e78743202e43aec8727005182a2558117eca (patch)
tree8f9113a77d12470c5c851a2a8e4cb02e89df7d43 /openssl/doc/crypto/BIO_s_connect.pod
downloadvcxsrv-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.pod192
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