1 .\" $OpenBSD: BIO_s_accept.3,v 1.5 2016/12/06 14:45:08 schwarze Exp $
2 .\" OpenSSL c03726ca Thu Aug 27 12:28:08 2015 -0400
4 .\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
5 .\" Copyright (c) 2000, 2014, 2015 The OpenSSL Project. All rights reserved.
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
11 .\" 1. Redistributions of source code must retain the above copyright
12 .\" notice, this list of conditions and the following disclaimer.
14 .\" 2. Redistributions in binary form must reproduce the above copyright
15 .\" notice, this list of conditions and the following disclaimer in
16 .\" the documentation and/or other materials provided with the
19 .\" 3. All advertising materials mentioning features or use of this
20 .\" software must display the following acknowledgment:
21 .\" "This product includes software developed by the OpenSSL Project
22 .\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
24 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
25 .\" endorse or promote products derived from this software without
26 .\" prior written permission. For written permission, please contact
27 .\" openssl-core@openssl.org.
29 .\" 5. Products derived from this software may not be called "OpenSSL"
30 .\" nor may "OpenSSL" appear in their names without prior written
31 .\" permission of the OpenSSL Project.
33 .\" 6. Redistributions of any form whatsoever must retain the following
35 .\" "This product includes software developed by the OpenSSL Project
36 .\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
38 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
39 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
40 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
41 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
42 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
43 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
44 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
45 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
46 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
47 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
48 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
49 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
51 .Dd $Mdocdate: December 6 2016 $
56 .Nm BIO_set_accept_port ,
57 .Nm BIO_get_accept_port ,
59 .Nm BIO_set_nbio_accept ,
60 .Nm BIO_set_accept_bios ,
61 .Nm BIO_set_bind_mode ,
62 .Nm BIO_get_bind_mode ,
72 .Fo BIO_set_accept_port
77 .Fo BIO_get_accept_port
85 .Fo BIO_set_nbio_accept
90 .Fo BIO_set_accept_bios
100 .Fo BIO_get_bind_mode
104 .Fd #define BIO_BIND_NORMAL 0
105 .Fd #define BIO_BIND_REUSEADDR_IF_UNUSED 1
106 .Fd #define BIO_BIND_REUSEADDR 2
113 returns the accept BIO method.
114 This is a wrapper round the platform's TCP/IP socket
118 Using accept BIOs, TCP/IP connections can be accepted
119 and data transferred using only BIO routines.
120 In this way any platform specific operations
121 are hidden by the BIO abstraction.
123 Read and write operations on an accept BIO
124 will perform I/O on the underlying connection.
125 If no connection is established and the port (see below) is set up
126 properly then the BIO waits for an incoming connection.
133 If the close flag is set on an accept BIO, then any active
134 connection on that chain is shut down and the socket closed when
139 on an accept BIO will close any active connection and reset the BIO
140 into a state where it awaits another incoming connection.
145 can be called to retrieve or set the accept socket.
149 .Fn BIO_set_accept_port
152 to set the accept port.
153 The port is represented as a string of the form
154 .Ar host : Ns Ar port ,
157 is the interface to use and
162 which is interpreted as meaning any interface;
164 has the same syntax as the port specified in
165 .Xr BIO_set_conn_port 3
167 It can be a numerical port string or a string to look up using
175 .Fn BIO_set_accept_port
177 It creates a new accept BIO with port
180 .Fn BIO_set_nbio_accept
181 sets the accept socket to blocking mode (the default) if
183 is 0 or non-blocking mode if
187 .Fn BIO_set_accept_bios
188 can be used to set a chain of BIOs which will be duplicated
189 and prepended to the chain when an incoming connection is received.
190 This is useful if, for example, a buffering or SSL BIO
191 is required for each connection.
192 The chain of BIOs must not be freed after this call -
193 they will be automatically freed when the accept BIO is freed.
195 .Fn BIO_set_bind_mode
197 .Fn BIO_get_bind_mode
198 set and retrieve the current bind mode.
200 .Dv BIO_BIND_NORMAL Pq the default
201 is set, then another socket cannot be bound to the same port.
203 .Dv BIO_BIND_REUSEADDR
204 is set, then other sockets can bind to the same port.
206 .Dv BIO_BIND_REUSEADDR_IF_UNUSED
207 is set, then an attempt is first made to use
209 if this fails and the port is not in use,
210 then a second attempt is made using
211 .Dv BIO_BIND_REUSEADDR .
215 When it is first called, after the accept BIO has been set up,
216 it will attempt to create the accept socket and bind an address to it.
217 Second and subsequent calls to
219 will await an incoming connection, or request a retry in non-blocking mode.
221 When an accept BIO is at the end of a chain, it will await an
222 incoming connection before processing I/O calls.
223 When an accept BIO is not at then end of a chain,
224 it passes I/O calls to the next BIO in the chain.
226 When a connection is established a new socket BIO is created
227 for the connection and appended to the chain.
228 That is the chain is now accept->socket.
229 This effectively means that attempting I/O on an initial accept
230 socket will await an incoming connection then perform I/O on it.
232 If any additional BIOs have been set using
233 .Fn BIO_set_accept_bios ,
234 then they are placed between the socket and the accept BIO;
235 that is, the chain will be accept->otherbios->socket.
237 If a server wishes to process multiple connections (as is normally
238 the case), then the accept BIO must be made available for further
239 incoming connections.
240 This can be done by waiting for a connection and then calling:
242 .Dl connection = BIO_pop(accept);
246 will contain a BIO for the recently established connection and
248 will now be a single BIO again which can be used
249 to await further incoming connections.
250 If no further connections will be accepted, the
255 If only a single connection will be processed,
256 it is possible to perform I/O using the accept BIO itself.
257 This is often undesirable however because the accept BIO
258 will still accept additional incoming connections.
259 This can be resolved by using
261 (see above) and freeing up the accept BIO after the initial connection.
263 If the underlying accept socket is non-blocking and
265 is called to await an incoming connection, it is possible for
266 .Xr BIO_should_io_special 3
269 If this happens, then it is an indication that an accept attempt
270 would block: the application should take appropriate action
271 to wait until the underlying socket has accepted a connection
274 .Fn BIO_set_accept_port ,
275 .Fn BIO_get_accept_port ,
276 .Fn BIO_set_nbio_accept ,
277 .Fn BIO_set_accept_bios ,
278 .Fn BIO_set_bind_mode ,
279 .Fn BIO_get_bind_mode ,
285 .Fn BIO_set_accept_port ,
286 .Fn BIO_set_nbio_accept ,
287 .Fn BIO_set_accept_bios ,
289 .Fn BIO_set_bind_mode
290 return 1 for success or 0 or -1 for failure.
292 .Fn BIO_get_accept_port
293 returns the port as a string or
297 .Fn BIO_get_bind_mode
298 returns the set of BIO_BIND flags or -1 on failure.
307 This example accepts two connections on port 4444,
308 sends messages down each and finally closes both down.
309 .Bd -literal -offset 2n
310 BIO *abio, *cbio, *cbio2;
311 ERR_load_crypto_strings();
312 abio = BIO_new_accept("4444");
314 /* First call to BIO_accept() sets up accept BIO */
315 if (BIO_do_accept(abio) <= 0) {
316 fprintf(stderr, "Error setting up accept\en");
317 ERR_print_errors_fp(stderr);
321 /* Wait for incoming connection */
322 if (BIO_do_accept(abio) <= 0) {
323 fprintf(stderr, "Error accepting connection\en");
324 ERR_print_errors_fp(stderr);
327 fprintf(stderr, "Connection 1 established\en");
329 /* Retrieve BIO for connection */
330 cbio = BIO_pop(abio);
332 BIO_puts(cbio, "Connection 1: Sending out Data on initial connection\en");
333 fprintf(stderr, "Sent out data on connection 1\en");
335 /* Wait for another connection */
336 if (BIO_do_accept(abio) <= 0) {
337 fprintf(stderr, "Error accepting connection\en");
338 ERR_print_errors_fp(stderr);
341 fprintf(stderr, "Connection 2 established\en");
343 /* Close accept BIO to refuse further connections */
344 cbio2 = BIO_pop(abio);
347 BIO_puts(cbio2, "Connection 2: Sending out Data on second\en");
348 fprintf(stderr, "Sent out data on connection 2\en");
349 BIO_puts(cbio, "Connection 1: Second connection established\en");
351 /* Close the two established connections */