| 1 |
.\" -*- mode: troff; coding: utf-8 -*- |
| 2 |
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) |
| 3 |
.\" |
| 4 |
.\" Standard preamble: |
| 5 |
.\" ======================================================================== |
| 6 |
.de Sp \" Vertical space (when we can't use .PP) |
| 7 |
.if t .sp .5v |
| 8 |
.if n .sp |
| 9 |
.. |
| 10 |
.de Vb \" Begin verbatim text |
| 11 |
.ft CW |
| 12 |
.nf |
| 13 |
.ne \\$1 |
| 14 |
.. |
| 15 |
.de Ve \" End verbatim text |
| 16 |
.ft R |
| 17 |
.fi |
| 18 |
.. |
| 19 |
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. |
| 20 |
.ie n \{\ |
| 21 |
. ds C` "" |
| 22 |
. ds C' "" |
| 23 |
'br\} |
| 24 |
.el\{\ |
| 25 |
. ds C` |
| 26 |
. ds C' |
| 27 |
'br\} |
| 28 |
.\" |
| 29 |
.\" Escape single quotes in literal strings from groff's Unicode transform. |
| 30 |
.ie \n(.g .ds Aq \(aq |
| 31 |
.el .ds Aq ' |
| 32 |
.\" |
| 33 |
.\" If the F register is >0, we'll generate index entries on stderr for |
| 34 |
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index |
| 35 |
.\" entries marked with X<> in POD. Of course, you'll have to process the |
| 36 |
.\" output yourself in some meaningful fashion. |
| 37 |
.\" |
| 38 |
.\" Avoid warning from groff about undefined register 'F'. |
| 39 |
.de IX |
| 40 |
.. |
| 41 |
.nr rF 0 |
| 42 |
.if \n(.g .if rF .nr rF 1 |
| 43 |
.if (\n(rF:(\n(.g==0)) \{\ |
| 44 |
. if \nF \{\ |
| 45 |
. de IX |
| 46 |
. tm Index:\\$1\t\\n%\t"\\$2" |
| 47 |
.. |
| 48 |
. if !\nF==2 \{\ |
| 49 |
. nr % 0 |
| 50 |
. nr F 2 |
| 51 |
. \} |
| 52 |
. \} |
| 53 |
.\} |
| 54 |
.rr rF |
| 55 |
.\" ======================================================================== |
| 56 |
.\" |
| 57 |
.IX Title "BIO_S_ACCEPT 3SSL" |
| 58 |
.TH BIO_S_ACCEPT 3SSL 2026-04-07 3.6.2 OpenSSL |
| 59 |
.\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 60 |
.\" way too many mistakes in technical documents. |
| 61 |
.if n .ad l |
| 62 |
.nh |
| 63 |
.SH NAME |
| 64 |
BIO_s_accept, BIO_set_accept_name, BIO_set_accept_port, BIO_get_accept_name, |
| 65 |
BIO_get_accept_port, BIO_new_accept, BIO_set_nbio_accept, BIO_set_tfo_accept, BIO_set_accept_bios, |
| 66 |
BIO_get_peer_name, BIO_get_peer_port, |
| 67 |
BIO_get_accept_ip_family, BIO_set_accept_ip_family, |
| 68 |
BIO_set_bind_mode, BIO_get_bind_mode, BIO_do_accept \- accept BIO |
| 69 |
.SH SYNOPSIS |
| 70 |
.IX Header "SYNOPSIS" |
| 71 |
.Vb 1 |
| 72 |
\& #include <openssl/bio.h> |
| 73 |
\& |
| 74 |
\& const BIO_METHOD *BIO_s_accept(void); |
| 75 |
\& |
| 76 |
\& long BIO_set_accept_name(BIO *b, char *name); |
| 77 |
\& char *BIO_get_accept_name(BIO *b); |
| 78 |
\& |
| 79 |
\& long BIO_set_accept_port(BIO *b, char *port); |
| 80 |
\& char *BIO_get_accept_port(BIO *b); |
| 81 |
\& |
| 82 |
\& BIO *BIO_new_accept(char *host_port); |
| 83 |
\& |
| 84 |
\& long BIO_set_nbio_accept(BIO *b, int n); |
| 85 |
\& long BIO_set_tfo_accept(BIO *b, int n); |
| 86 |
\& long BIO_set_accept_bios(BIO *b, char *bio); |
| 87 |
\& |
| 88 |
\& char *BIO_get_peer_name(BIO *b); |
| 89 |
\& char *BIO_get_peer_port(BIO *b); |
| 90 |
\& long BIO_get_accept_ip_family(BIO *b); |
| 91 |
\& long BIO_set_accept_ip_family(BIO *b, long family); |
| 92 |
\& |
| 93 |
\& long BIO_set_bind_mode(BIO *b, long mode); |
| 94 |
\& long BIO_get_bind_mode(BIO *b); |
| 95 |
\& |
| 96 |
\& int BIO_do_accept(BIO *b); |
| 97 |
.Ve |
| 98 |
.SH DESCRIPTION |
| 99 |
.IX Header "DESCRIPTION" |
| 100 |
\&\fBBIO_s_accept()\fR returns the accept BIO method. This is a wrapper |
| 101 |
round the platform's TCP/IP socket accept routines. |
| 102 |
.PP |
| 103 |
Using accept BIOs, TCP/IP connections can be accepted and data |
| 104 |
transferred using only BIO routines. In this way any platform |
| 105 |
specific operations are hidden by the BIO abstraction. |
| 106 |
.PP |
| 107 |
Read and write operations on an accept BIO will perform I/O |
| 108 |
on the underlying connection. If no connection is established |
| 109 |
and the port (see below) is set up properly then the BIO |
| 110 |
waits for an incoming connection. |
| 111 |
.PP |
| 112 |
Accept BIOs support \fBBIO_puts()\fR but not \fBBIO_gets()\fR. |
| 113 |
.PP |
| 114 |
If the close flag is set on an accept BIO then any active |
| 115 |
connection on that chain is shutdown and the socket closed when |
| 116 |
the BIO is freed. |
| 117 |
.PP |
| 118 |
Calling \fBBIO_reset()\fR on an accept BIO will close any active |
| 119 |
connection and reset the BIO into a state where it awaits another |
| 120 |
incoming connection. |
| 121 |
.PP |
| 122 |
\&\fBBIO_get_fd()\fR and \fBBIO_set_fd()\fR can be called to retrieve or set |
| 123 |
the accept socket. See \fBBIO_s_fd\fR\|(3) |
| 124 |
.PP |
| 125 |
\&\fBBIO_set_accept_name()\fR uses the string \fBname\fR to set the accept |
| 126 |
name. The name is represented as a string of the form "host:port", |
| 127 |
where "host" is the interface to use and "port" is the port. |
| 128 |
The host can be "*" or empty which is interpreted as meaning |
| 129 |
any interface. If the host is an IPv6 address, it has to be |
| 130 |
enclosed in brackets, for example "[::1]:https". "port" has the |
| 131 |
same syntax as the port specified in \fBBIO_set_conn_port()\fR for |
| 132 |
connect BIOs, that is it can be a numerical port string or a |
| 133 |
string to lookup using \fBgetservbyname()\fR and a string table. |
| 134 |
.PP |
| 135 |
\&\fBBIO_set_accept_port()\fR uses the string \fBport\fR to set the accept |
| 136 |
port of BIO \fIb\fR. "port" has the same syntax as the port specified in |
| 137 |
\&\fBBIO_set_conn_port()\fR for connect BIOs, that is it can be a numerical |
| 138 |
port string or a string to lookup using \fBgetservbyname()\fR and a string |
| 139 |
table. |
| 140 |
If the given port is \f(CW0\fR then a random available port is chosen. |
| 141 |
It may be queried using \fBBIO_sock_info()\fR and \fBBIO_ADDR_service_string\fR\|(3). |
| 142 |
.PP |
| 143 |
\&\fBBIO_new_accept()\fR combines \fBBIO_new()\fR and \fBBIO_set_accept_name()\fR into |
| 144 |
a single call: that is it creates a new accept BIO with port |
| 145 |
\&\fBhost_port\fR. |
| 146 |
.PP |
| 147 |
\&\fBBIO_set_nbio_accept()\fR sets the accept socket to blocking mode |
| 148 |
(the default) if \fBn\fR is 0 or non blocking mode if \fBn\fR is 1. |
| 149 |
.PP |
| 150 |
\&\fBBIO_set_tfo_accept()\fR enables TCP Fast Open on the accept socket |
| 151 |
if \fBn\fR is 1 or disables TCP Fast Open if \fBn\fR is 0 (the default). |
| 152 |
Setting the value to 1 is equivalent to setting \fBBIO_SOCK_TFO\fR |
| 153 |
in \fBBIO_set_bind_mode()\fR. |
| 154 |
.PP |
| 155 |
\&\fBBIO_set_accept_bios()\fR can be used to set a chain of BIOs which |
| 156 |
will be duplicated and prepended to the chain when an incoming |
| 157 |
connection is received. This is useful if, for example, a |
| 158 |
buffering or SSL BIO is required for each connection. The |
| 159 |
chain of BIOs must not be freed after this call, they will |
| 160 |
be automatically freed when the accept BIO is freed. |
| 161 |
.PP |
| 162 |
\&\fBBIO_get_accept_ip_family()\fR returns the IP family accepted by the BIO \fIb\fR, |
| 163 |
which may be \fBBIO_FAMILY_IPV4\fR, \fBBIO_FAMILY_IPV6\fR, or \fBBIO_FAMILY_IPANY\fR. |
| 164 |
.PP |
| 165 |
\&\fBBIO_set_accept_ip_family()\fR sets the IP family \fIfamily\fR accepted by BIO \fIb\fR. |
| 166 |
The default is \fBBIO_FAMILY_IPANY\fR. |
| 167 |
.PP |
| 168 |
\&\fBBIO_set_bind_mode()\fR and \fBBIO_get_bind_mode()\fR set and retrieve |
| 169 |
the current bind mode. If \fBBIO_BIND_NORMAL\fR (the default) is set |
| 170 |
then another socket cannot be bound to the same port. If |
| 171 |
\&\fBBIO_BIND_REUSEADDR\fR is set then other sockets can bind to the |
| 172 |
same port. If \fBBIO_BIND_REUSEADDR_IF_UNUSED\fR is set then and |
| 173 |
attempt is first made to use BIO_BIN_NORMAL, if this fails |
| 174 |
and the port is not in use then a second attempt is made |
| 175 |
using \fBBIO_BIND_REUSEADDR\fR. If \fBBIO_SOCK_TFO\fR is set, then |
| 176 |
the socket will be configured to accept TCP Fast Open |
| 177 |
connections. |
| 178 |
.PP |
| 179 |
\&\fBBIO_do_accept()\fR serves two functions. When it is first |
| 180 |
called, after the accept BIO has been setup, it will attempt |
| 181 |
to create the accept socket and bind an address to it. Second |
| 182 |
and subsequent calls to \fBBIO_do_accept()\fR will await an incoming |
| 183 |
connection, or request a retry in non blocking mode. |
| 184 |
.SH NOTES |
| 185 |
.IX Header "NOTES" |
| 186 |
When an accept BIO is at the end of a chain it will await an |
| 187 |
incoming connection before processing I/O calls. When an accept |
| 188 |
BIO is not at then end of a chain it passes I/O calls to the next |
| 189 |
BIO in the chain. |
| 190 |
.PP |
| 191 |
When a connection is established a new socket BIO is created for |
| 192 |
the connection and appended to the chain. That is the chain is now |
| 193 |
accept\->socket. This effectively means that attempting I/O on |
| 194 |
an initial accept socket will await an incoming connection then |
| 195 |
perform I/O on it. |
| 196 |
.PP |
| 197 |
If any additional BIOs have been set using \fBBIO_set_accept_bios()\fR |
| 198 |
then they are placed between the socket and the accept BIO, |
| 199 |
that is the chain will be accept\->otherbios\->socket. |
| 200 |
.PP |
| 201 |
If a server wishes to process multiple connections (as is normally |
| 202 |
the case) then the accept BIO must be made available for further |
| 203 |
incoming connections. This can be done by waiting for a connection and |
| 204 |
then calling: |
| 205 |
.PP |
| 206 |
.Vb 1 |
| 207 |
\& connection = BIO_pop(accept); |
| 208 |
.Ve |
| 209 |
.PP |
| 210 |
After this call \fBconnection\fR will contain a BIO for the recently |
| 211 |
established connection and \fBaccept\fR will now be a single BIO |
| 212 |
again which can be used to await further incoming connections. |
| 213 |
If no further connections will be accepted the \fBaccept\fR can |
| 214 |
be freed using \fBBIO_free()\fR. |
| 215 |
.PP |
| 216 |
If only a single connection will be processed it is possible to |
| 217 |
perform I/O using the accept BIO itself. This is often undesirable |
| 218 |
however because the accept BIO will still accept additional incoming |
| 219 |
connections. This can be resolved by using \fBBIO_pop()\fR (see above) |
| 220 |
and freeing up the accept BIO after the initial connection. |
| 221 |
.PP |
| 222 |
If the underlying accept socket is nonblocking and \fBBIO_do_accept()\fR is |
| 223 |
called to await an incoming connection it is possible for |
| 224 |
\&\fBBIO_should_io_special()\fR with the reason BIO_RR_ACCEPT. If this happens |
| 225 |
then it is an indication that an accept attempt would block: the application |
| 226 |
should take appropriate action to wait until the underlying socket has |
| 227 |
accepted a connection and retry the call. |
| 228 |
.PP |
| 229 |
\&\fBBIO_set_accept_name()\fR, \fBBIO_get_accept_name()\fR, \fBBIO_set_accept_port()\fR, |
| 230 |
\&\fBBIO_get_accept_port()\fR, \fBBIO_set_nbio_accept()\fR, \fBBIO_set_accept_bios()\fR, |
| 231 |
\&\fBBIO_get_peer_name()\fR, \fBBIO_get_peer_port()\fR, |
| 232 |
\&\fBBIO_get_accept_ip_family()\fR, \fBBIO_set_accept_ip_family()\fR, |
| 233 |
\&\fBBIO_set_bind_mode()\fR, \fBBIO_get_bind_mode()\fR and \fBBIO_do_accept()\fR are macros. |
| 234 |
.SH "RETURN VALUES" |
| 235 |
.IX Header "RETURN VALUES" |
| 236 |
\&\fBBIO_do_accept()\fR, |
| 237 |
\&\fBBIO_set_accept_name()\fR, \fBBIO_set_accept_port()\fR, \fBBIO_set_nbio_accept()\fR, |
| 238 |
\&\fBBIO_set_accept_bios()\fR, \fBBIO_set_accept_ip_family()\fR, and \fBBIO_set_bind_mode()\fR |
| 239 |
return 1 for success and <= 0 for failure. |
| 240 |
.PP |
| 241 |
\&\fBBIO_get_accept_name()\fR returns the accept name or NULL on error. |
| 242 |
\&\fBBIO_get_peer_name()\fR returns the peer name or NULL on error. |
| 243 |
.PP |
| 244 |
\&\fBBIO_get_accept_port()\fR returns the accept port as a string or NULL on error. |
| 245 |
\&\fBBIO_get_peer_port()\fR returns the peer port as a string or NULL on error. |
| 246 |
\&\fBBIO_get_accept_ip_family()\fR returns the IP family or <= 0 on error. |
| 247 |
.PP |
| 248 |
\&\fBBIO_get_bind_mode()\fR returns the set of \fBBIO_BIND\fR flags, or <= 0 on failure. |
| 249 |
.PP |
| 250 |
\&\fBBIO_new_accept()\fR returns a BIO or NULL on error. |
| 251 |
.SH EXAMPLES |
| 252 |
.IX Header "EXAMPLES" |
| 253 |
This example accepts two connections on port 4444, sends messages |
| 254 |
down each and finally closes both down. |
| 255 |
.PP |
| 256 |
.Vb 1 |
| 257 |
\& BIO *abio, *cbio, *cbio2; |
| 258 |
\& |
| 259 |
\& /* First call to BIO_do_accept() sets up accept BIO */ |
| 260 |
\& abio = BIO_new_accept("4444"); |
| 261 |
\& if (BIO_do_accept(abio) <= 0) { |
| 262 |
\& fprintf(stderr, "Error setting up accept\en"); |
| 263 |
\& ERR_print_errors_fp(stderr); |
| 264 |
\& exit(1); |
| 265 |
\& } |
| 266 |
\& |
| 267 |
\& /* Wait for incoming connection */ |
| 268 |
\& if (BIO_do_accept(abio) <= 0) { |
| 269 |
\& fprintf(stderr, "Error accepting connection\en"); |
| 270 |
\& ERR_print_errors_fp(stderr); |
| 271 |
\& exit(1); |
| 272 |
\& } |
| 273 |
\& fprintf(stderr, "Connection 1 established\en"); |
| 274 |
\& |
| 275 |
\& /* Retrieve BIO for connection */ |
| 276 |
\& cbio = BIO_pop(abio); |
| 277 |
\& BIO_puts(cbio, "Connection 1: Sending out Data on initial connection\en"); |
| 278 |
\& fprintf(stderr, "Sent out data on connection 1\en"); |
| 279 |
\& |
| 280 |
\& /* Wait for another connection */ |
| 281 |
\& if (BIO_do_accept(abio) <= 0) { |
| 282 |
\& fprintf(stderr, "Error accepting connection\en"); |
| 283 |
\& ERR_print_errors_fp(stderr); |
| 284 |
\& exit(1); |
| 285 |
\& } |
| 286 |
\& fprintf(stderr, "Connection 2 established\en"); |
| 287 |
\& |
| 288 |
\& /* Close accept BIO to refuse further connections */ |
| 289 |
\& cbio2 = BIO_pop(abio); |
| 290 |
\& BIO_free(abio); |
| 291 |
\& BIO_puts(cbio2, "Connection 2: Sending out Data on second\en"); |
| 292 |
\& fprintf(stderr, "Sent out data on connection 2\en"); |
| 293 |
\& |
| 294 |
\& BIO_puts(cbio, "Connection 1: Second connection established\en"); |
| 295 |
\& |
| 296 |
\& /* Close the two established connections */ |
| 297 |
\& BIO_free(cbio); |
| 298 |
\& BIO_free(cbio2); |
| 299 |
.Ve |
| 300 |
.SH HISTORY |
| 301 |
.IX Header "HISTORY" |
| 302 |
\&\fBBIO_set_tfo_accept()\fR was added in OpenSSL 3.2. |
| 303 |
.SH COPYRIGHT |
| 304 |
.IX Header "COPYRIGHT" |
| 305 |
Copyright 2000\-2022 The OpenSSL Project Authors. All Rights Reserved. |
| 306 |
.PP |
| 307 |
Licensed under the Apache License 2.0 (the "License"). You may not use |
| 308 |
this file except in compliance with the License. You can obtain a copy |
| 309 |
in the file LICENSE in the source distribution or at |
| 310 |
<https://www.openssl.org/source/license.html>. |