1.Dd $Mdocdate: February 16 2015 $ 2.Dt BIO_S_ACCEPT 3 3.Os 4.Sh NAME 5.Nm BIO_s_accept , 6.Nm BIO_set_accept_port , 7.Nm BIO_get_accept_port , 8.Nm BIO_new_accept , 9.Nm BIO_set_nbio_accept , 10.Nm BIO_set_accept_bios , 11.Nm BIO_set_bind_mode , 12.Nm BIO_get_bind_mode , 13.Nm BIO_do_accept 14.Nd accept BIO 15.Sh SYNOPSIS 16.In openssl/bio.h 17.Ft BIO_METHOD * 18.Fo BIO_s_accept 19.Fa void 20.Fc 21.Ft long 22.Fo BIO_set_accept_port 23.Fa "BIO *b" 24.Fa "char *name" 25.Fc 26.Ft char * 27.Fo BIO_get_accept_port 28.Fa "BIO *b" 29.Fc 30.Ft BIO * 31.Fo BIO_new_accept 32.Fa "char *host_port" 33.Fc 34.Ft long 35.Fo BIO_set_nbio_accept 36.Fa "BIO *b" 37.Fa "int n" 38.Fc 39.Ft long 40.Fo BIO_set_accept_bios 41.Fa "BIO *b" 42.Fa "char *bio" 43.Fc 44.Ft long 45.Fo BIO_set_bind_mode 46.Fa "BIO *b" 47.Fa "long mode" 48.Fc 49.Ft long 50.Fo BIO_get_bind_mode 51.Fa "BIO *b" 52.Fa "long dummy" 53.Fc 54.Fd #define BIO_BIND_NORMAL 0 55.Fd #define BIO_BIND_REUSEADDR_IF_UNUSED 1 56.Fd #define BIO_BIND_REUSEADDR 2 57.Ft int 58.Fo BIO_do_accept 59.Fa "BIO *b" 60.Fc 61.Sh DESCRIPTION 62.Fn BIO_s_accept 63returns the accept BIO method. 64This is a wrapper round the platform's TCP/IP socket accept routines. 65.Pp 66Using accept BIOs, TCP/IP connections can be accepted 67and data transferred using only BIO routines. 68In this way any platform specific operations 69are hidden by the BIO abstraction. 70.Pp 71Read and write operations on an accept BIO 72will perform I/O on the underlying connection. 73If no connection is established and the port (see below) is set up 74properly then the BIO waits for an incoming connection. 75.Pp 76Accept BIOs support 77.Xr BIO_puts 3 78but not 79.Xr BIO_gets 3 . 80.Pp 81If the close flag is set on an accept BIO, then any active 82connection on that chain is shutdown and the socket closed when 83the BIO is freed. 84.Pp 85Calling 86.Xr BIO_reset 3 87on a accept BIO will close any active connection and reset the BIO 88into a state where it awaits another incoming connection. 89.Pp 90.Xr BIO_get_fd 3 91and 92.Xr BIO_set_fd 3 93can be called to retrieve or set the accept socket. 94See 95.Xr BIO_s_fd 3 . 96.Pp 97.Fn BIO_set_accept_port 98uses the string 99.Fa name 100to set the accept port. 101The port is represented as a string of the form 102.Ar host : Ns Ar port , 103where 104.Ar host 105is the interface to use and 106.Ar port 107is the port. 108Either or both values can be 109.Qq * 110which is interpreted as meaning any interface or port respectively. 111.Ar port 112has the same syntax as the port specified in 113.Xr BIO_set_conn_port 3 114for connect BIOs. 115It can be a numerical port string or a string to lookup using 116.Xr getservbyname 3 117and a string table. 118.Pp 119.Fn BIO_new_accept 120combines 121.Xr BIO_new 3 122and 123.Fn BIO_set_accept_port 124into a single call. 125It creates a new accept BIO with port 126.Fa host_port . 127.Pp 128.Fn BIO_set_nbio_accept 129sets the accept socket to blocking mode (the default) if 130.Fa n 131is 0 or non blocking mode if 132.Fa n 133is 1. 134.Pp 135.Fn BIO_set_accept_bios 136can be used to set a chain of BIOs which will be duplicated 137and prepended to the chain when an incoming connection is received. 138This is useful if, for example, a buffering or SSL BIO 139is required for each connection. 140The chain of BIOs must not be freed after this call, 141they will be automatically freed when the accept BIO is freed. 142.Pp 143.Fn BIO_set_bind_mode 144and 145.Fn BIO_get_bind_mode 146set and retrieve the current bind mode. 147If 148.Dv BIO_BIND_NORMAL Pq the default 149is set, then another socket cannot be bound to the same port. 150If 151.Dv BIO_BIND_REUSEADDR 152is set, then other sockets can bind to the same port. 153If 154.Dv BIO_BIND_REUSEADDR_IF_UNUSED 155is set, then an attempt is first made to use 156.Dv BIO_BIN_NORMAL ; 157if this fails and the port is not in use, 158then a second attempt is made using 159.Dv BIO_BIND_REUSEADDR . 160.Pp 161.Fn BIO_do_accept 162serves two purposes. 163When it is first called, after the accept BIO has been setup, 164it will attempt to create the accept socket and bind an address to it. 165Second and subsequent calls to 166.Fn BIO_do_accept 167will await an incoming connection, or request a retry in non blocking mode. 168.Sh NOTES 169When an accept BIO is at the end of a chain, it will await an 170incoming connection before processing I/O calls. 171When an accept BIO is not at then end of a chain, 172it passes I/O calls to the next BIO in the chain. 173.Pp 174When a connection is established a new socket BIO is created 175for the connection and appended to the chain. 176That is the chain is now accept->socket. 177This effectively means that attempting I/O on an initial accept 178socket will await an incoming connection then perform I/O on it. 179.Pp 180If any additional BIOs have been set using 181.Fn BIO_set_accept_bios , 182then they are placed between the socket and the accept BIO, 183that is the chain will be accept->otherbios->socket. 184.Pp 185If a server wishes to process multiple connections (as is normally 186the case), then the accept BIO must be made available for further 187incoming connections. 188This can be done by waiting for a connection and then calling: 189.Pp 190.Dl connection = BIO_pop(accept); 191.Pp 192After this call, 193.Sy connection 194will contain a BIO for the recently established connection and 195.Sy accept 196will now be a single BIO again which can be used 197to await further incoming connections. 198If no further connections will be accepted, the 199.Sy accept 200can be freed using 201.Xr BIO_free 3 . 202.Pp 203If only a single connection will be processed, 204it is possible to perform I/O using the accept BIO itself. 205This is often undesirable however because the accept BIO 206will still accept additional incoming connections. 207This can be resolved by using 208.Xr BIO_pop 3 209(see above) and freeing up the accept BIO after the initial connection. 210.Pp 211If the underlying accept socket is non-blocking and 212.Fn BIO_do_accept 213is called to await an incoming connection, it is possible for 214.Xr BIO_should_io_special 3 215with the reason 216.Dv BIO_RR_ACCEPT . 217If this happens, then it is an indication that an accept attempt 218would block: the application should take appropriate action 219to wait until the underlying socket has accepted a connection 220and retry the call. 221.Pp 222.Fn BIO_set_accept_port , 223.Fn BIO_get_accept_port , 224.Fn BIO_set_nbio_accept , 225.Fn BIO_set_accept_bios , 226.Fn BIO_set_bind_mode , 227.Fn BIO_get_bind_mode , 228and 229.Fn BIO_do_accept 230are macros. 231.Sh EXAMPLES 232This example accepts two connections on port 4444, 233sends messages down each and finally closes both down. 234.Bd -literal -offset 2n 235BIO *abio, *cbio, *cbio2; 236ERR_load_crypto_strings(); 237abio = BIO_new_accept("4444"); 238 239/* First call to BIO_accept() sets up accept BIO */ 240if (BIO_do_accept(abio) <= 0) { 241 fprintf(stderr, "Error setting up accept\en"); 242 ERR_print_errors_fp(stderr); 243 exit(0); 244} 245 246/* Wait for incoming connection */ 247if (BIO_do_accept(abio) <= 0) { 248 fprintf(stderr, "Error accepting connection\en"); 249 ERR_print_errors_fp(stderr); 250 exit(0); 251} 252fprintf(stderr, "Connection 1 established\en"); 253 254/* Retrieve BIO for connection */ 255cbio = BIO_pop(abio); 256 257BIO_puts(cbio, "Connection 1: Sending out Data on initial connection\en"); 258fprintf(stderr, "Sent out data on connection 1\en"); 259 260/* Wait for another connection */ 261if (BIO_do_accept(abio) <= 0) { 262 fprintf(stderr, "Error accepting connection\en"); 263 ERR_print_errors_fp(stderr); 264 exit(0); 265} 266fprintf(stderr, "Connection 2 established\en"); 267 268/* Close accept BIO to refuse further connections */ 269cbio2 = BIO_pop(abio); 270BIO_free(abio); 271 272BIO_puts(cbio2, "Connection 2: Sending out Data on second\en"); 273fprintf(stderr, "Sent out data on connection 2\en"); 274BIO_puts(cbio, "Connection 1: Second connection established\en"); 275 276/* Close the two established connections */ 277BIO_free(cbio); 278BIO_free(cbio2); 279.Ed 280