From 3562e78743202e43aec8727005182a2558117eca Mon Sep 17 00:00:00 2001 From: marha Date: Sun, 28 Jun 2009 22:07:26 +0000 Subject: 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 --- openssl/doc/crypto/BIO_s_accept.pod | 195 ++++++++++++++++++++++++++++++++++++ 1 file changed, 195 insertions(+) create mode 100644 openssl/doc/crypto/BIO_s_accept.pod (limited to 'openssl/doc/crypto/BIO_s_accept.pod') diff --git a/openssl/doc/crypto/BIO_s_accept.pod b/openssl/doc/crypto/BIO_s_accept.pod new file mode 100644 index 000000000..7b63e4621 --- /dev/null +++ b/openssl/doc/crypto/BIO_s_accept.pod @@ -0,0 +1,195 @@ +=pod + +=head1 NAME + +BIO_s_accept, BIO_set_accept_port, BIO_get_accept_port, +BIO_set_nbio_accept, BIO_set_accept_bios, BIO_set_bind_mode, +BIO_get_bind_mode, BIO_do_accept - accept BIO + +=head1 SYNOPSIS + + #include + + BIO_METHOD *BIO_s_accept(void); + + long BIO_set_accept_port(BIO *b, char *name); + char *BIO_get_accept_port(BIO *b); + + BIO *BIO_new_accept(char *host_port); + + long BIO_set_nbio_accept(BIO *b, int n); + long BIO_set_accept_bios(BIO *b, char *bio); + + long BIO_set_bind_mode(BIO *b, long mode); + long BIO_get_bind_mode(BIO *b, long dummy); + + #define BIO_BIND_NORMAL 0 + #define BIO_BIND_REUSEADDR_IF_UNUSED 1 + #define BIO_BIND_REUSEADDR 2 + + int BIO_do_accept(BIO *b); + +=head1 DESCRIPTION + +BIO_s_accept() returns the accept BIO method. This is a wrapper +round the platform's TCP/IP socket accept routines. + +Using accept BIOs, TCP/IP connections can be accepted 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 an accept BIO will perform I/O +on the underlying connection. If no connection is established +and the port (see below) is set up properly then the BIO +waits for an incoming connection. + +Accept BIOs support BIO_puts() but not BIO_gets(). + +If the close flag is set on an accept BIO then any active +connection on that chain is shutdown and the socket closed when +the BIO is freed. + +Calling BIO_reset() on a accept BIO will close any active +connection and reset the BIO into a state where it awaits another +incoming connection. + +BIO_get_fd() and BIO_set_fd() can be called to retrieve or set +the accept socket. See L + +BIO_set_accept_port() uses the string B to set the accept +port. The port is represented as a string of the form "host:port", +where "host" is the interface to use and "port" is the port. +Either or both values can be "*" which is interpreted as meaning +any interface or port respectively. "port" has the same syntax +as the port specified in BIO_set_conn_port() for connect BIOs, +that is it can be a numerical port string or a string to lookup +using getservbyname() and a string table. + +BIO_new_accept() combines BIO_new() and BIO_set_accept_port() into +a single call: that is it creates a new accept BIO with port +B. + +BIO_set_nbio_accept() sets the accept socket to blocking mode +(the default) if B is 0 or non blocking mode if B is 1. + +BIO_set_accept_bios() can be used to set a chain of BIOs which +will be duplicated and prepended to the chain when an incoming +connection is received. This is useful if, for example, a +buffering or SSL BIO is required for each connection. The +chain of BIOs must not be freed after this call, they will +be automatically freed when the accept BIO is freed. + +BIO_set_bind_mode() and BIO_get_bind_mode() set and retrieve +the current bind mode. If BIO_BIND_NORMAL (the default) is set +then another socket cannot be bound to the same port. If +BIO_BIND_REUSEADDR is set then other sockets can bind to the +same port. If BIO_BIND_REUSEADDR_IF_UNUSED is set then and +attempt is first made to use BIO_BIN_NORMAL, if this fails +and the port is not in use then a second attempt is made +using BIO_BIND_REUSEADDR. + +BIO_do_accept() serves two functions. When it is first +called, after the accept BIO has been setup, it will attempt +to create the accept socket and bind an address to it. Second +and subsequent calls to BIO_do_accept() will await an incoming +connection, or request a retry in non blocking mode. + +=head1 NOTES + +When an accept BIO is at the end of a chain it will await an +incoming connection before processing I/O calls. When an accept +BIO is not at then end of a chain it passes I/O calls to the next +BIO in the chain. + +When a connection is established a new socket BIO is created for +the connection and appended to the chain. That is the chain is now +accept->socket. This effectively means that attempting I/O on +an initial accept socket will await an incoming connection then +perform I/O on it. + +If any additional BIOs have been set using BIO_set_accept_bios() +then they are placed between the socket and the accept BIO, +that is the chain will be accept->otherbios->socket. + +If a server wishes to process multiple connections (as is normally +the case) then the accept BIO must be made available for further +incoming connections. This can be done by waiting for a connection and +then calling: + + connection = BIO_pop(accept); + +After this call B will contain a BIO for the recently +established connection and B will now be a single BIO +again which can be used to await further incoming connections. +If no further connections will be accepted the B can +be freed using BIO_free(). + +If only a single connection will be processed it is possible to +perform I/O using the accept BIO itself. This is often undesirable +however because the accept BIO will still accept additional incoming +connections. This can be resolved by using BIO_pop() (see above) +and freeing up the accept BIO after the initial connection. + +If the underlying accept socket is non-blocking and BIO_do_accept() is +called to await an incoming connection it is possible for +BIO_should_io_special() with the reason BIO_RR_ACCEPT. If this happens +then it is an indication that an accept attempt would block: the application +should take appropriate action to wait until the underlying socket has +accepted a connection and retry the call. + +BIO_set_accept_port(), BIO_get_accept_port(), BIO_set_nbio_accept(), +BIO_set_accept_bios(), BIO_set_bind_mode(), BIO_get_bind_mode() and +BIO_do_accept() are macros. + +=head1 RETURN VALUES + +TBA + +=head1 EXAMPLE + +This example accepts two connections on port 4444, sends messages +down each and finally closes both down. + + BIO *abio, *cbio, *cbio2; + ERR_load_crypto_strings(); + abio = BIO_new_accept("4444"); + + /* First call to BIO_accept() sets up accept BIO */ + if(BIO_do_accept(abio) <= 0) { + fprintf(stderr, "Error setting up accept\n"); + ERR_print_errors_fp(stderr); + exit(0); + } + + /* Wait for incoming connection */ + if(BIO_do_accept(abio) <= 0) { + fprintf(stderr, "Error accepting connection\n"); + ERR_print_errors_fp(stderr); + exit(0); + } + fprintf(stderr, "Connection 1 established\n"); + /* Retrieve BIO for connection */ + cbio = BIO_pop(abio); + BIO_puts(cbio, "Connection 1: Sending out Data on initial connection\n"); + fprintf(stderr, "Sent out data on connection 1\n"); + /* Wait for another connection */ + if(BIO_do_accept(abio) <= 0) { + fprintf(stderr, "Error accepting connection\n"); + ERR_print_errors_fp(stderr); + exit(0); + } + fprintf(stderr, "Connection 2 established\n"); + /* Close accept BIO to refuse further connections */ + cbio2 = BIO_pop(abio); + BIO_free(abio); + BIO_puts(cbio2, "Connection 2: Sending out Data on second\n"); + fprintf(stderr, "Sent out data on connection 2\n"); + + BIO_puts(cbio, "Connection 1: Second connection established\n"); + /* Close the two established connections */ + BIO_free(cbio); + BIO_free(cbio2); + +=head1 SEE ALSO + +TBA -- cgit v1.2.3