1BIO_S_ACCEPT(3ossl) OpenSSL BIO_S_ACCEPT(3ossl)
2
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
13 #include <openssl/bio.h>
14 const BIO_METHOD *BIO_s_accept(void);
16 long BIO_set_accept_name(BIO *b, char *name);
18 char *BIO_get_accept_name(BIO *b);
19 long BIO_set_accept_port(BIO *b, char *port);
21 char *BIO_get_accept_port(BIO *b);
22 BIO *BIO_new_accept(char *host_port);
24 long BIO_set_nbio_accept(BIO *b, int n);
26 long BIO_set_accept_bios(BIO *b, char *bio);
27 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 long BIO_set_bind_mode(BIO *b, long mode);
34 long BIO_get_bind_mode(BIO *b);
35 int BIO_do_accept(BIO *b);
37
39 BIO_s_accept() returns the accept BIO method. This is a wrapper round
40 the platform's TCP/IP socket accept routines.
41 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 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 Accept BIOs support BIO_puts() but not BIO_gets().
52 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 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 BIO_get_fd() and BIO_set_fd() can be called to retrieve or set the
61 accept socket. See BIO_s_fd(3)
62 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 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 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 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 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 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 BIO_set_accept_ip_family() sets the IP family family accepted by BIO b.
97 The default is BIO_FAMILY_IPANY.
98 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 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
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 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 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 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 connection = BIO_pop(accept);
134 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 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 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 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
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 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 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 BIO_get_bind_mode() returns the set of BIO_BIND flags, or <=0 on
174 failure.
175 BIO_new_accept() returns a BIO or NULL on error.
177
179 This example accepts two connections on port 4444, sends messages down
180 each and finally closes both down.
181 BIO *abio, *cbio, *cbio2;
183 /* 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 /* 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 /* 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 /* 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 /* 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 BIO_puts(cbio, "Connection 1: Second connection established\n");
220 /* 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 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>.
2323.1.1 2023-08-31 BIO_S_ACCEPT(3ossl)