From 68a1c6b0d9957d95a44453ceda50c30c71494bbc Mon Sep 17 00:00:00 2001 From: "Dr. Stephen Henson" Date: Fri, 15 Sep 2000 17:31:47 +0000 Subject: [PATCH] Accept BIO docs. --- doc/crypto/BIO_s_accept.pod | 182 ++++++++++++++++++++++++++++++++++++ 1 file changed, 182 insertions(+) create mode 100644 doc/crypto/BIO_s_accept.pod diff --git a/doc/crypto/BIO_s_accept.pod b/doc/crypto/BIO_s_accept.pod new file mode 100644 index 0000000000..17fd54a9c6 --- /dev/null +++ b/doc/crypto/BIO_s_accept.pod @@ -0,0 +1,182 @@ +=pod + +=head1 NAME + +BIO_s_accept, BIO_set_nbio, 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); + + #define BIO_set_accept_port(b,name) BIO_ctrl(b,BIO_C_SET_ACCEPT,0,(char *)name) + #define BIO_get_accept_port(b) BIO_ptr_ctrl(b,BIO_C_GET_ACCEPT,0) + + BIO *BIO_new_accept(char *host_port); + + #define BIO_set_nbio_accept(b,n) BIO_ctrl(b,BIO_C_SET_ACCEPT,1,(n)?"a":NULL) + #define BIO_set_accept_bios(b,bio) BIO_ctrl(b,BIO_C_SET_ACCEPT,2,(char *)bio) + + #define BIO_set_bind_mode(b,mode) BIO_ctrl(b,BIO_C_SET_BIND_MODE,mode,NULL) + #define BIO_get_bind_mode(b,mode) BIO_ctrl(b,BIO_C_GET_BIND_MODE,0,NULL) + + #define BIO_BIND_NORMAL 0 + #define BIO_BIND_REUSEADDR_IF_UNUSED 1 + #define BIO_BIND_REUSEADDR 2 + + #define BIO_do_accept(b) BIO_do_handshake(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 BIO is required for each connection. + +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. + +=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 conection 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. + +=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 -- 2.25.1