openssl: Adjust manual pages for 1.0.1m.
[dragonfly.git] / secure / lib / libcrypto / man / BIO_s_accept.3
CommitLineData
5a44c043 1.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
8b0cefbb
JR
2.\"
3.\" Standard preamble:
4.\" ========================================================================
8b0cefbb 5.de Sp \" Vertical space (when we can't use .PP)
984263bc
MD
6.if t .sp .5v
7.if n .sp
8..
8b0cefbb 9.de Vb \" Begin verbatim text
984263bc
MD
10.ft CW
11.nf
12.ne \\$1
13..
8b0cefbb 14.de Ve \" End verbatim text
984263bc 15.ft R
984263bc
MD
16.fi
17..
8b0cefbb
JR
18.\" Set up some character translations and predefined strings. \*(-- will
19.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
e257b235
PA
20.\" double quote, and \*(R" will give a right double quote. \*(C+ will
21.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
22.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
23.\" nothing in troff, for use with C<>.
24.tr \(*W-
8b0cefbb 25.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
984263bc 26.ie n \{\
8b0cefbb
JR
27. ds -- \(*W-
28. ds PI pi
29. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
30. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
31. ds L" ""
32. ds R" ""
33. ds C` ""
34. ds C' ""
984263bc
MD
35'br\}
36.el\{\
8b0cefbb
JR
37. ds -- \|\(em\|
38. ds PI \(*p
39. ds L" ``
40. ds R" ''
5a44c043
SW
41. ds C`
42. ds C'
984263bc 43'br\}
8b0cefbb 44.\"
e257b235
PA
45.\" Escape single quotes in literal strings from groff's Unicode transform.
46.ie \n(.g .ds Aq \(aq
47.el .ds Aq '
48.\"
8b0cefbb 49.\" If the F register is turned on, we'll generate index entries on stderr for
01185282 50.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
8b0cefbb
JR
51.\" entries marked with X<> in POD. Of course, you'll have to process the
52.\" output yourself in some meaningful fashion.
5a44c043
SW
53.\"
54.\" Avoid warning from groff about undefined register 'F'.
55.de IX
984263bc 56..
5a44c043
SW
57.nr rF 0
58.if \n(.g .if rF .nr rF 1
59.if (\n(rF:(\n(.g==0)) \{
60. if \nF \{
61. de IX
62. tm Index:\\$1\t\\n%\t"\\$2"
e257b235 63..
5a44c043
SW
64. if !\nF==2 \{
65. nr % 0
66. nr F 2
67. \}
68. \}
e257b235 69.\}
5a44c043 70.rr rF
aac4ff6f 71.\"
8b0cefbb
JR
72.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
73.\" Fear. Run. Save yourself. No user-serviceable parts.
74. \" fudge factors for nroff and troff
984263bc 75.if n \{\
8b0cefbb
JR
76. ds #H 0
77. ds #V .8m
78. ds #F .3m
79. ds #[ \f1
80. ds #] \fP
984263bc
MD
81.\}
82.if t \{\
8b0cefbb
JR
83. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
84. ds #V .6m
85. ds #F 0
86. ds #[ \&
87. ds #] \&
984263bc 88.\}
8b0cefbb 89. \" simple accents for nroff and troff
984263bc 90.if n \{\
8b0cefbb
JR
91. ds ' \&
92. ds ` \&
93. ds ^ \&
94. ds , \&
95. ds ~ ~
96. ds /
984263bc
MD
97.\}
98.if t \{\
8b0cefbb
JR
99. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
100. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
101. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
102. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
103. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
104. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
984263bc 105.\}
8b0cefbb 106. \" troff and (daisy-wheel) nroff accents
984263bc
MD
107.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
108.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
109.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
110.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
111.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
112.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
113.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
114.ds ae a\h'-(\w'a'u*4/10)'e
115.ds Ae A\h'-(\w'A'u*4/10)'E
8b0cefbb 116. \" corrections for vroff
984263bc
MD
117.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
118.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
8b0cefbb 119. \" for low resolution devices (crt and lpr)
984263bc
MD
120.if \n(.H>23 .if \n(.V>19 \
121\{\
8b0cefbb
JR
122. ds : e
123. ds 8 ss
124. ds o a
125. ds d- d\h'-1'\(ga
126. ds D- D\h'-1'\(hy
127. ds th \o'bp'
128. ds Th \o'LP'
129. ds ae ae
130. ds Ae AE
984263bc
MD
131.\}
132.rm #[ #] #H #V #F C
8b0cefbb
JR
133.\" ========================================================================
134.\"
135.IX Title "BIO_s_accept 3"
5a44c043 136.TH BIO_s_accept 3 "2015-03-19" "1.0.1m" "OpenSSL"
e257b235
PA
137.\" For nroff, turn off justification. Always turn off hyphenation; it makes
138.\" way too many mistakes in technical documents.
139.if n .ad l
140.nh
984263bc
MD
141.SH "NAME"
142BIO_s_accept, BIO_set_accept_port, BIO_get_accept_port,
143BIO_set_nbio_accept, BIO_set_accept_bios, BIO_set_bind_mode,
74dab6c2 144BIO_get_bind_mode, BIO_do_accept \- accept BIO
984263bc 145.SH "SYNOPSIS"
8b0cefbb 146.IX Header "SYNOPSIS"
984263bc
MD
147.Vb 1
148\& #include <openssl/bio.h>
e257b235 149\&
984263bc 150\& BIO_METHOD *BIO_s_accept(void);
e257b235 151\&
984263bc
MD
152\& long BIO_set_accept_port(BIO *b, char *name);
153\& char *BIO_get_accept_port(BIO *b);
e257b235 154\&
984263bc 155\& BIO *BIO_new_accept(char *host_port);
e257b235 156\&
984263bc
MD
157\& long BIO_set_nbio_accept(BIO *b, int n);
158\& long BIO_set_accept_bios(BIO *b, char *bio);
e257b235 159\&
984263bc
MD
160\& long BIO_set_bind_mode(BIO *b, long mode);
161\& long BIO_get_bind_mode(BIO *b, long dummy);
e257b235 162\&
984263bc
MD
163\& #define BIO_BIND_NORMAL 0
164\& #define BIO_BIND_REUSEADDR_IF_UNUSED 1
165\& #define BIO_BIND_REUSEADDR 2
e257b235 166\&
984263bc
MD
167\& int BIO_do_accept(BIO *b);
168.Ve
169.SH "DESCRIPTION"
8b0cefbb
JR
170.IX Header "DESCRIPTION"
171\&\fIBIO_s_accept()\fR returns the accept \s-1BIO\s0 method. This is a wrapper
172round the platform's \s-1TCP/IP\s0 socket accept routines.
984263bc 173.PP
8b0cefbb
JR
174Using accept BIOs, \s-1TCP/IP\s0 connections can be accepted and data
175transferred using only \s-1BIO\s0 routines. In this way any platform
176specific operations are hidden by the \s-1BIO\s0 abstraction.
984263bc 177.PP
8b0cefbb 178Read and write operations on an accept \s-1BIO\s0 will perform I/O
984263bc 179on the underlying connection. If no connection is established
8b0cefbb 180and the port (see below) is set up properly then the \s-1BIO\s0
984263bc
MD
181waits for an incoming connection.
182.PP
183Accept BIOs support \fIBIO_puts()\fR but not \fIBIO_gets()\fR.
184.PP
8b0cefbb 185If the close flag is set on an accept \s-1BIO\s0 then any active
984263bc 186connection on that chain is shutdown and the socket closed when
8b0cefbb 187the \s-1BIO\s0 is freed.
984263bc 188.PP
8b0cefbb
JR
189Calling \fIBIO_reset()\fR on a accept \s-1BIO\s0 will close any active
190connection and reset the \s-1BIO\s0 into a state where it awaits another
984263bc
MD
191incoming connection.
192.PP
8b0cefbb
JR
193\&\fIBIO_get_fd()\fR and \fIBIO_set_fd()\fR can be called to retrieve or set
194the accept socket. See \fIBIO_s_fd\fR\|(3)
984263bc 195.PP
8b0cefbb 196\&\fIBIO_set_accept_port()\fR uses the string \fBname\fR to set the accept
984263bc
MD
197port. The port is represented as a string of the form \*(L"host:port\*(R",
198where \*(L"host\*(R" is the interface to use and \*(L"port\*(R" is the port.
d95b477a
SW
199The host can be can be \*(L"*\*(R" which is interpreted as meaning
200any interface; \*(L"port\*(R" has the same syntax
984263bc
MD
201as the port specified in \fIBIO_set_conn_port()\fR for connect BIOs,
202that is it can be a numerical port string or a string to lookup
203using \fIgetservbyname()\fR and a string table.
204.PP
8b0cefbb
JR
205\&\fIBIO_new_accept()\fR combines \fIBIO_new()\fR and \fIBIO_set_accept_port()\fR into
206a single call: that is it creates a new accept \s-1BIO\s0 with port
207\&\fBhost_port\fR.
984263bc 208.PP
8b0cefbb 209\&\fIBIO_set_nbio_accept()\fR sets the accept socket to blocking mode
984263bc
MD
210(the default) if \fBn\fR is 0 or non blocking mode if \fBn\fR is 1.
211.PP
8b0cefbb 212\&\fIBIO_set_accept_bios()\fR can be used to set a chain of BIOs which
984263bc
MD
213will be duplicated and prepended to the chain when an incoming
214connection is received. This is useful if, for example, a
5a44c043 215buffering or \s-1SSL BIO\s0 is required for each connection. The
984263bc 216chain of BIOs must not be freed after this call, they will
8b0cefbb 217be automatically freed when the accept \s-1BIO\s0 is freed.
984263bc 218.PP
8b0cefbb 219\&\fIBIO_set_bind_mode()\fR and \fIBIO_get_bind_mode()\fR set and retrieve
5a44c043 220the current bind mode. If \s-1BIO_BIND_NORMAL \s0(the default) is set
984263bc 221then another socket cannot be bound to the same port. If
8b0cefbb
JR
222\&\s-1BIO_BIND_REUSEADDR\s0 is set then other sockets can bind to the
223same port. If \s-1BIO_BIND_REUSEADDR_IF_UNUSED\s0 is set then and
5a44c043 224attempt is first made to use \s-1BIO_BIN_NORMAL,\s0 if this fails
984263bc 225and the port is not in use then a second attempt is made
5a44c043 226using \s-1BIO_BIND_REUSEADDR.\s0
984263bc 227.PP
8b0cefbb
JR
228\&\fIBIO_do_accept()\fR serves two functions. When it is first
229called, after the accept \s-1BIO\s0 has been setup, it will attempt
984263bc
MD
230to create the accept socket and bind an address to it. Second
231and subsequent calls to \fIBIO_do_accept()\fR will await an incoming
232connection, or request a retry in non blocking mode.
233.SH "NOTES"
8b0cefbb
JR
234.IX Header "NOTES"
235When an accept \s-1BIO\s0 is at the end of a chain it will await an
984263bc 236incoming connection before processing I/O calls. When an accept
8b0cefbb
JR
237\&\s-1BIO\s0 is not at then end of a chain it passes I/O calls to the next
238\&\s-1BIO\s0 in the chain.
984263bc 239.PP
8b0cefbb 240When a connection is established a new socket \s-1BIO\s0 is created for
984263bc 241the connection and appended to the chain. That is the chain is now
8b0cefbb 242accept\->socket. This effectively means that attempting I/O on
984263bc
MD
243an initial accept socket will await an incoming connection then
244perform I/O on it.
245.PP
246If any additional BIOs have been set using \fIBIO_set_accept_bios()\fR
5a44c043 247then they are placed between the socket and the accept \s-1BIO,\s0
8b0cefbb 248that is the chain will be accept\->otherbios\->socket.
984263bc
MD
249.PP
250If a server wishes to process multiple connections (as is normally
8b0cefbb 251the case) then the accept \s-1BIO\s0 must be made available for further
984263bc
MD
252incoming connections. This can be done by waiting for a connection and
253then calling:
254.PP
255.Vb 1
256\& connection = BIO_pop(accept);
257.Ve
8b0cefbb
JR
258.PP
259After this call \fBconnection\fR will contain a \s-1BIO\s0 for the recently
260established connection and \fBaccept\fR will now be a single \s-1BIO\s0
984263bc
MD
261again which can be used to await further incoming connections.
262If no further connections will be accepted the \fBaccept\fR can
263be freed using \fIBIO_free()\fR.
264.PP
265If only a single connection will be processed it is possible to
8b0cefbb
JR
266perform I/O using the accept \s-1BIO\s0 itself. This is often undesirable
267however because the accept \s-1BIO\s0 will still accept additional incoming
984263bc 268connections. This can be resolved by using \fIBIO_pop()\fR (see above)
8b0cefbb 269and freeing up the accept \s-1BIO\s0 after the initial connection.
984263bc
MD
270.PP
271If the underlying accept socket is non-blocking and \fIBIO_do_accept()\fR is
272called to await an incoming connection it is possible for
5a44c043 273\&\fIBIO_should_io_special()\fR with the reason \s-1BIO_RR_ACCEPT.\s0 If this happens
984263bc
MD
274then it is an indication that an accept attempt would block: the application
275should take appropriate action to wait until the underlying socket has
276accepted a connection and retry the call.
277.PP
8b0cefbb
JR
278\&\fIBIO_set_accept_port()\fR, \fIBIO_get_accept_port()\fR, \fIBIO_set_nbio_accept()\fR,
279\&\fIBIO_set_accept_bios()\fR, \fIBIO_set_bind_mode()\fR, \fIBIO_get_bind_mode()\fR and
280\&\fIBIO_do_accept()\fR are macros.
984263bc 281.SH "RETURN VALUES"
8b0cefbb
JR
282.IX Header "RETURN VALUES"
283\&\s-1TBA\s0
984263bc 284.SH "EXAMPLE"
8b0cefbb 285.IX Header "EXAMPLE"
984263bc
MD
286This example accepts two connections on port 4444, sends messages
287down each and finally closes both down.
288.PP
289.Vb 3
290\& BIO *abio, *cbio, *cbio2;
291\& ERR_load_crypto_strings();
292\& abio = BIO_new_accept("4444");
e257b235 293\&
984263bc
MD
294\& /* First call to BIO_accept() sets up accept BIO */
295\& if(BIO_do_accept(abio) <= 0) {
296\& fprintf(stderr, "Error setting up accept\en");
297\& ERR_print_errors_fp(stderr);
298\& exit(0);
299\& }
e257b235 300\&
984263bc
MD
301\& /* Wait for incoming connection */
302\& if(BIO_do_accept(abio) <= 0) {
303\& fprintf(stderr, "Error accepting connection\en");
304\& ERR_print_errors_fp(stderr);
305\& exit(0);
306\& }
307\& fprintf(stderr, "Connection 1 established\en");
308\& /* Retrieve BIO for connection */
309\& cbio = BIO_pop(abio);
310\& BIO_puts(cbio, "Connection 1: Sending out Data on initial connection\en");
311\& fprintf(stderr, "Sent out data on connection 1\en");
312\& /* Wait for another connection */
313\& if(BIO_do_accept(abio) <= 0) {
314\& fprintf(stderr, "Error accepting connection\en");
315\& ERR_print_errors_fp(stderr);
316\& exit(0);
317\& }
318\& fprintf(stderr, "Connection 2 established\en");
319\& /* Close accept BIO to refuse further connections */
320\& cbio2 = BIO_pop(abio);
321\& BIO_free(abio);
322\& BIO_puts(cbio2, "Connection 2: Sending out Data on second\en");
323\& fprintf(stderr, "Sent out data on connection 2\en");
e257b235 324\&
984263bc
MD
325\& BIO_puts(cbio, "Connection 1: Second connection established\en");
326\& /* Close the two established connections */
327\& BIO_free(cbio);
328\& BIO_free(cbio2);
329.Ve
330.SH "SEE ALSO"
331.IX Header "SEE ALSO"
8b0cefbb 332\&\s-1TBA\s0