168651Skris=pod 268651Skris 368651Skris=head1 NAME 468651Skris 5109998SmarkmBIO_s_accept, BIO_set_accept_port, BIO_get_accept_port, 668651SkrisBIO_set_nbio_accept, BIO_set_accept_bios, BIO_set_bind_mode, 768651SkrisBIO_get_bind_mode, BIO_do_accept - accept BIO 868651Skris 968651Skris=head1 SYNOPSIS 1068651Skris 1168651Skris #include <openssl/bio.h> 1268651Skris 13109998Smarkm BIO_METHOD *BIO_s_accept(void); 1468651Skris 15109998Smarkm long BIO_set_accept_port(BIO *b, char *name); 16109998Smarkm char *BIO_get_accept_port(BIO *b); 1768651Skris 1868651Skris BIO *BIO_new_accept(char *host_port); 1968651Skris 20109998Smarkm long BIO_set_nbio_accept(BIO *b, int n); 21109998Smarkm long BIO_set_accept_bios(BIO *b, char *bio); 2268651Skris 23109998Smarkm long BIO_set_bind_mode(BIO *b, long mode); 24109998Smarkm long BIO_get_bind_mode(BIO *b, long dummy); 2568651Skris 2668651Skris #define BIO_BIND_NORMAL 0 2768651Skris #define BIO_BIND_REUSEADDR_IF_UNUSED 1 2868651Skris #define BIO_BIND_REUSEADDR 2 2968651Skris 30109998Smarkm int BIO_do_accept(BIO *b); 3168651Skris 3268651Skris=head1 DESCRIPTION 3368651Skris 3468651SkrisBIO_s_accept() returns the accept BIO method. This is a wrapper 3568651Skrisround the platform's TCP/IP socket accept routines. 3668651Skris 37109998SmarkmUsing accept BIOs, TCP/IP connections can be accepted and data 3868651Skristransferred using only BIO routines. In this way any platform 3968651Skrisspecific operations are hidden by the BIO abstraction. 4068651Skris 4168651SkrisRead and write operations on an accept BIO will perform I/O 4268651Skrison the underlying connection. If no connection is established 4368651Skrisand the port (see below) is set up properly then the BIO 4468651Skriswaits for an incoming connection. 4568651Skris 4668651SkrisAccept BIOs support BIO_puts() but not BIO_gets(). 4768651Skris 4868651SkrisIf the close flag is set on an accept BIO then any active 4968651Skrisconnection on that chain is shutdown and the socket closed when 5068651Skristhe BIO is freed. 5168651Skris 5268651SkrisCalling BIO_reset() on a accept BIO will close any active 5368651Skrisconnection and reset the BIO into a state where it awaits another 5468651Skrisincoming connection. 5568651Skris 5668651SkrisBIO_get_fd() and BIO_set_fd() can be called to retrieve or set 5768651Skristhe accept socket. See L<BIO_s_fd(3)|BIO_s_fd(3)> 5868651Skris 5968651SkrisBIO_set_accept_port() uses the string B<name> to set the accept 6068651Skrisport. The port is represented as a string of the form "host:port", 6168651Skriswhere "host" is the interface to use and "port" is the port. 62273399SdelphijThe host can be can be "*" which is interpreted as meaning 63273399Sdelphijany interface; "port" has the same syntax 6468651Skrisas the port specified in BIO_set_conn_port() for connect BIOs, 6568651Skristhat is it can be a numerical port string or a string to lookup 6668651Skrisusing getservbyname() and a string table. 6768651Skris 6868651SkrisBIO_new_accept() combines BIO_new() and BIO_set_accept_port() into 6968651Skrisa single call: that is it creates a new accept BIO with port 7068651SkrisB<host_port>. 7168651Skris 7268651SkrisBIO_set_nbio_accept() sets the accept socket to blocking mode 7368651Skris(the default) if B<n> is 0 or non blocking mode if B<n> is 1. 7468651Skris 7568651SkrisBIO_set_accept_bios() can be used to set a chain of BIOs which 7668651Skriswill be duplicated and prepended to the chain when an incoming 7768651Skrisconnection is received. This is useful if, for example, a 7868651Skrisbuffering or SSL BIO is required for each connection. The 7968651Skrischain of BIOs must not be freed after this call, they will 8068651Skrisbe automatically freed when the accept BIO is freed. 8168651Skris 8268651SkrisBIO_set_bind_mode() and BIO_get_bind_mode() set and retrieve 8368651Skristhe current bind mode. If BIO_BIND_NORMAL (the default) is set 8468651Skristhen another socket cannot be bound to the same port. If 8568651SkrisBIO_BIND_REUSEADDR is set then other sockets can bind to the 8668651Skrissame port. If BIO_BIND_REUSEADDR_IF_UNUSED is set then and 8768651Skrisattempt is first made to use BIO_BIN_NORMAL, if this fails 8868651Skrisand the port is not in use then a second attempt is made 8968651Skrisusing BIO_BIND_REUSEADDR. 9068651Skris 9168651SkrisBIO_do_accept() serves two functions. When it is first 9268651Skriscalled, after the accept BIO has been setup, it will attempt 9368651Skristo create the accept socket and bind an address to it. Second 9468651Skrisand subsequent calls to BIO_do_accept() will await an incoming 95109998Smarkmconnection, or request a retry in non blocking mode. 9668651Skris 9768651Skris=head1 NOTES 9868651Skris 9968651SkrisWhen an accept BIO is at the end of a chain it will await an 10068651Skrisincoming connection before processing I/O calls. When an accept 10168651SkrisBIO is not at then end of a chain it passes I/O calls to the next 10268651SkrisBIO in the chain. 10368651Skris 10468651SkrisWhen a connection is established a new socket BIO is created for 10568651Skristhe connection and appended to the chain. That is the chain is now 10668651Skrisaccept->socket. This effectively means that attempting I/O on 10768651Skrisan initial accept socket will await an incoming connection then 10868651Skrisperform I/O on it. 10968651Skris 11068651SkrisIf any additional BIOs have been set using BIO_set_accept_bios() 11168651Skristhen they are placed between the socket and the accept BIO, 11268651Skristhat is the chain will be accept->otherbios->socket. 11368651Skris 11468651SkrisIf a server wishes to process multiple connections (as is normally 11568651Skristhe case) then the accept BIO must be made available for further 11668651Skrisincoming connections. This can be done by waiting for a connection and 11768651Skristhen calling: 11868651Skris 11968651Skris connection = BIO_pop(accept); 12068651Skris 12168651SkrisAfter this call B<connection> will contain a BIO for the recently 12268651Skrisestablished connection and B<accept> will now be a single BIO 12368651Skrisagain which can be used to await further incoming connections. 12468651SkrisIf no further connections will be accepted the B<accept> can 12568651Skrisbe freed using BIO_free(). 12668651Skris 12768651SkrisIf only a single connection will be processed it is possible to 12868651Skrisperform I/O using the accept BIO itself. This is often undesirable 12968651Skrishowever because the accept BIO will still accept additional incoming 13068651Skrisconnections. This can be resolved by using BIO_pop() (see above) 13168651Skrisand freeing up the accept BIO after the initial connection. 13268651Skris 133109998SmarkmIf the underlying accept socket is non-blocking and BIO_do_accept() is 134109998Smarkmcalled to await an incoming connection it is possible for 135109998SmarkmBIO_should_io_special() with the reason BIO_RR_ACCEPT. If this happens 136109998Smarkmthen it is an indication that an accept attempt would block: the application 137109998Smarkmshould take appropriate action to wait until the underlying socket has 138109998Smarkmaccepted a connection and retry the call. 139109998Smarkm 140109998SmarkmBIO_set_accept_port(), BIO_get_accept_port(), BIO_set_nbio_accept(), 141109998SmarkmBIO_set_accept_bios(), BIO_set_bind_mode(), BIO_get_bind_mode() and 142109998SmarkmBIO_do_accept() are macros. 143109998Smarkm 14468651Skris=head1 RETURN VALUES 14568651Skris 14668651SkrisTBA 14768651Skris 14868651Skris=head1 EXAMPLE 14968651Skris 15068651SkrisThis example accepts two connections on port 4444, sends messages 15168651Skrisdown each and finally closes both down. 15268651Skris 15368651Skris BIO *abio, *cbio, *cbio2; 15468651Skris ERR_load_crypto_strings(); 15568651Skris abio = BIO_new_accept("4444"); 15668651Skris 15768651Skris /* First call to BIO_accept() sets up accept BIO */ 15868651Skris if(BIO_do_accept(abio) <= 0) { 15968651Skris fprintf(stderr, "Error setting up accept\n"); 16068651Skris ERR_print_errors_fp(stderr); 16168651Skris exit(0); 16268651Skris } 16368651Skris 16468651Skris /* Wait for incoming connection */ 16568651Skris if(BIO_do_accept(abio) <= 0) { 16668651Skris fprintf(stderr, "Error accepting connection\n"); 16768651Skris ERR_print_errors_fp(stderr); 16868651Skris exit(0); 16968651Skris } 17068651Skris fprintf(stderr, "Connection 1 established\n"); 17168651Skris /* Retrieve BIO for connection */ 17268651Skris cbio = BIO_pop(abio); 17368651Skris BIO_puts(cbio, "Connection 1: Sending out Data on initial connection\n"); 17468651Skris fprintf(stderr, "Sent out data on connection 1\n"); 17568651Skris /* Wait for another connection */ 17668651Skris if(BIO_do_accept(abio) <= 0) { 17768651Skris fprintf(stderr, "Error accepting connection\n"); 17868651Skris ERR_print_errors_fp(stderr); 17968651Skris exit(0); 18068651Skris } 18168651Skris fprintf(stderr, "Connection 2 established\n"); 18268651Skris /* Close accept BIO to refuse further connections */ 18368651Skris cbio2 = BIO_pop(abio); 18468651Skris BIO_free(abio); 18568651Skris BIO_puts(cbio2, "Connection 2: Sending out Data on second\n"); 18668651Skris fprintf(stderr, "Sent out data on connection 2\n"); 18768651Skris 18868651Skris BIO_puts(cbio, "Connection 1: Second connection established\n"); 18968651Skris /* Close the two established connections */ 19068651Skris BIO_free(cbio); 19168651Skris BIO_free(cbio2); 19268651Skris 19368651Skris=head1 SEE ALSO 19468651Skris 19568651SkrisTBA 196