Initial connect BIO docs.

1 files changed, 131 insertions, 0 deletions

diff --git a/doc/crypto/BIO_s_connect.pod b/doc/crypto/BIO_s_connect.pod
new file mode 100644
index 0000000000..08a9e6473e
--- /dev/null
+++ b/doc/crypto/BIO_s_connect.pod
@@ -0,0 +1,131 @@
+=pod
+
+=head1 NAME
+
+	BIO_s_connect - connect BIO
+
+=head1 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)
+
+=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 initialised 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 host name 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.
+
+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().
+
+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 can 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 appropiate action to wait until
+the underlying socket has connected and retry the call.
+
+=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 initialised.
+
+=head1 EXAMPLES
+
+TBA
+
+=head1 SEE ALSO
+
+TBA