1BIO_S_ACCEPT(3ossl)                 OpenSSL                BIO_S_ACCEPT(3ossl)
2
3
4

NAME

6       BIO_s_accept, BIO_set_accept_name, BIO_set_accept_port,
7       BIO_get_accept_name, BIO_get_accept_port, BIO_new_accept,
8       BIO_set_nbio_accept, BIO_set_accept_bios, BIO_get_peer_name,
9       BIO_get_peer_port, BIO_get_accept_ip_family, BIO_set_accept_ip_family,
10       BIO_set_bind_mode, BIO_get_bind_mode, BIO_do_accept - accept BIO
11

SYNOPSIS

13        #include <openssl/bio.h>
14
15        const BIO_METHOD *BIO_s_accept(void);
16
17        long BIO_set_accept_name(BIO *b, char *name);
18        char *BIO_get_accept_name(BIO *b);
19
20        long BIO_set_accept_port(BIO *b, char *port);
21        char *BIO_get_accept_port(BIO *b);
22
23        BIO *BIO_new_accept(char *host_port);
24
25        long BIO_set_nbio_accept(BIO *b, int n);
26        long BIO_set_accept_bios(BIO *b, char *bio);
27
28        char *BIO_get_peer_name(BIO *b);
29        char *BIO_get_peer_port(BIO *b);
30        long BIO_get_accept_ip_family(BIO *b);
31        long BIO_set_accept_ip_family(BIO *b, long family);
32
33        long BIO_set_bind_mode(BIO *b, long mode);
34        long BIO_get_bind_mode(BIO *b);
35
36        int BIO_do_accept(BIO *b);
37

DESCRIPTION

39       BIO_s_accept() returns the accept BIO method. This is a wrapper round
40       the platform's TCP/IP socket accept routines.
41
42       Using accept BIOs, TCP/IP connections can be accepted and data
43       transferred using only BIO routines. In this way any platform specific
44       operations are hidden by the BIO abstraction.
45
46       Read and write operations on an accept BIO will perform I/O on the
47       underlying connection. If no connection is established and the port
48       (see below) is set up properly then the BIO waits for an incoming
49       connection.
50
51       Accept BIOs support BIO_puts() but not BIO_gets().
52
53       If the close flag is set on an accept BIO then any active connection on
54       that chain is shutdown and the socket closed when the BIO is freed.
55
56       Calling BIO_reset() on an accept BIO will close any active connection
57       and reset the BIO into a state where it awaits another incoming
58       connection.
59
60       BIO_get_fd() and BIO_set_fd() can be called to retrieve or set the
61       accept socket. See BIO_s_fd(3)
62
63       BIO_set_accept_name() uses the string name to set the accept name. The
64       name is represented as a string of the form "host:port", where "host"
65       is the interface to use and "port" is the port.  The host can be "*" or
66       empty which is interpreted as meaning any interface.  If the host is an
67       IPv6 address, it has to be enclosed in brackets, for example
68       "[::1]:https".  "port" has the same syntax as the port specified in
69       BIO_set_conn_port() for connect BIOs, that is it can be a numerical
70       port string or a string to lookup using getservbyname() and a string
71       table.
72
73       BIO_set_accept_port() uses the string port to set the accept port of
74       BIO b.  "port" has the same syntax as the port specified in
75       BIO_set_conn_port() for connect BIOs, that is it can be a numerical
76       port string or a string to lookup using getservbyname() and a string
77       table.  If the given port is 0 then a random available port is chosen.
78       It may be queried using BIO_sock_info() and BIO_ADDR_service_string(3).
79
80       BIO_new_accept() combines BIO_new() and BIO_set_accept_name() into a
81       single call: that is it creates a new accept BIO with port host_port.
82
83       BIO_set_nbio_accept() sets the accept socket to blocking mode (the
84       default) if n is 0 or non blocking mode if n is 1.
85
86       BIO_set_accept_bios() can be used to set a chain of BIOs which will be
87       duplicated and prepended to the chain when an incoming connection is
88       received. This is useful if, for example, a buffering or SSL BIO is
89       required for each connection. The chain of BIOs must not be freed after
90       this call, they will be automatically freed when the accept BIO is
91       freed.
92
93       BIO_get_accept_ip_family() returns the IP family accepted by the BIO b,
94       which may be BIO_FAMILY_IPV4, BIO_FAMILY_IPV6, or BIO_FAMILY_IPANY.
95
96       BIO_set_accept_ip_family() sets the IP family family accepted by BIO b.
97       The default is BIO_FAMILY_IPANY.
98
99       BIO_set_bind_mode() and BIO_get_bind_mode() set and retrieve the
100       current bind mode. If BIO_BIND_NORMAL (the default) is set then another
101       socket cannot be bound to the same port. If BIO_BIND_REUSEADDR is set
102       then other sockets can bind to the same port. If
103       BIO_BIND_REUSEADDR_IF_UNUSED is set then and attempt is first made to
104       use BIO_BIN_NORMAL, if this fails and the port is not in use then a
105       second attempt is made using BIO_BIND_REUSEADDR.
106
107       BIO_do_accept() serves two functions. When it is first called, after
108       the accept BIO has been setup, it will attempt to create the accept
109       socket and bind an address to it. Second and subsequent calls to
110       BIO_do_accept() will await an incoming connection, or request a retry
111       in non blocking mode.
112

NOTES

114       When an accept BIO is at the end of a chain it will await an incoming
115       connection before processing I/O calls. When an accept BIO is not at
116       then end of a chain it passes I/O calls to the next BIO in the chain.
117
118       When a connection is established a new socket BIO is created for the
119       connection and appended to the chain. That is the chain is now
120       accept->socket. This effectively means that attempting I/O on an
121       initial accept socket will await an incoming connection then perform
122       I/O on it.
123
124       If any additional BIOs have been set using BIO_set_accept_bios() then
125       they are placed between the socket and the accept BIO, that is the
126       chain will be accept->otherbios->socket.
127
128       If a server wishes to process multiple connections (as is normally the
129       case) then the accept BIO must be made available for further incoming
130       connections. This can be done by waiting for a connection and then
131       calling:
132
133        connection = BIO_pop(accept);
134
135       After this call connection will contain a BIO for the recently
136       established connection and accept will now be a single BIO again which
137       can be used to await further incoming connections.  If no further
138       connections will be accepted the accept can be freed using BIO_free().
139
140       If only a single connection will be processed it is possible to perform
141       I/O using the accept BIO itself. This is often undesirable however
142       because the accept BIO will still accept additional incoming
143       connections. This can be resolved by using BIO_pop() (see above) and
144       freeing up the accept BIO after the initial connection.
145
146       If the underlying accept socket is nonblocking and BIO_do_accept() is
147       called to await an incoming connection it is possible for
148       BIO_should_io_special() with the reason BIO_RR_ACCEPT. If this happens
149       then it is an indication that an accept attempt would block: the
150       application should take appropriate action to wait until the underlying
151       socket has accepted a connection and retry the call.
152
153       BIO_set_accept_name(), BIO_get_accept_name(), BIO_set_accept_port(),
154       BIO_get_accept_port(), BIO_set_nbio_accept(), BIO_set_accept_bios(),
155       BIO_get_peer_name(), BIO_get_peer_port(), BIO_get_accept_ip_family(),
156       BIO_set_accept_ip_family(), BIO_set_bind_mode(), BIO_get_bind_mode()
157       and BIO_do_accept() are macros.
158

RETURN VALUES

160       BIO_do_accept(), BIO_set_accept_name(), BIO_set_accept_port(),
161       BIO_set_nbio_accept(), BIO_set_accept_bios(),
162       BIO_set_accept_ip_family(), and BIO_set_bind_mode() return 1 for
163       success and <=0 for failure.
164
165       BIO_get_accept_name() returns the accept name or NULL on error.
166       BIO_get_peer_name() returns the peer name or NULL on error.
167
168       BIO_get_accept_port() returns the accept port as a string or NULL on
169       error.  BIO_get_peer_port() returns the peer port as a string or NULL
170       on error.  BIO_get_accept_ip_family() returns the IP family or <=0 on
171       error.
172
173       BIO_get_bind_mode() returns the set of BIO_BIND flags, or <=0 on
174       failure.
175
176       BIO_new_accept() returns a BIO or NULL on error.
177

EXAMPLES

179       This example accepts two connections on port 4444, sends messages down
180       each and finally closes both down.
181
182        BIO *abio, *cbio, *cbio2;
183
184        /* First call to BIO_do_accept() sets up accept BIO */
185        abio = BIO_new_accept("4444");
186        if (BIO_do_accept(abio) <= 0) {
187            fprintf(stderr, "Error setting up accept\n");
188            ERR_print_errors_fp(stderr);
189            exit(1);
190        }
191
192        /* Wait for incoming connection */
193        if (BIO_do_accept(abio) <= 0) {
194            fprintf(stderr, "Error accepting connection\n");
195            ERR_print_errors_fp(stderr);
196            exit(1);
197        }
198        fprintf(stderr, "Connection 1 established\n");
199
200        /* Retrieve BIO for connection */
201        cbio = BIO_pop(abio);
202        BIO_puts(cbio, "Connection 1: Sending out Data on initial connection\n");
203        fprintf(stderr, "Sent out data on connection 1\n");
204
205        /* Wait for another connection */
206        if (BIO_do_accept(abio) <= 0) {
207            fprintf(stderr, "Error accepting connection\n");
208            ERR_print_errors_fp(stderr);
209            exit(1);
210        }
211        fprintf(stderr, "Connection 2 established\n");
212
213        /* Close accept BIO to refuse further connections */
214        cbio2 = BIO_pop(abio);
215        BIO_free(abio);
216        BIO_puts(cbio2, "Connection 2: Sending out Data on second\n");
217        fprintf(stderr, "Sent out data on connection 2\n");
218
219        BIO_puts(cbio, "Connection 1: Second connection established\n");
220
221        /* Close the two established connections */
222        BIO_free(cbio);
223        BIO_free(cbio2);
224
226       Copyright 2000-2022 The OpenSSL Project Authors. All Rights Reserved.
227
228       Licensed under the Apache License 2.0 (the "License").  You may not use
229       this file except in compliance with the License.  You can obtain a copy
230       in the file LICENSE in the source distribution or at
231       <https://www.openssl.org/source/license.html>.
232
233
234
2353.1.1                             2023-08-31               BIO_S_ACCEPT(3ossl)
Impressum