Switch from OpenSSL 0.9.7d to 0.9.7e.
[dragonfly.git] / secure / lib / libcrypto / man / BIO_s_accept.3
CommitLineData
74dab6c2
JR
1.rn '' }`
2''' $RCSfile$$Revision$$Date$
3'''
4''' $Log$
5'''
6.de Sh
984263bc
MD
7.br
8.if t .Sp
9.ne 5
10.PP
11\fB\\$1\fR
12.PP
13..
74dab6c2 14.de Sp
984263bc
MD
15.if t .sp .5v
16.if n .sp
17..
74dab6c2 18.de Ip
984263bc
MD
19.br
20.ie \\n(.$>=3 .ne \\$3
21.el .ne 3
22.IP "\\$1" \\$2
23..
74dab6c2 24.de Vb
984263bc
MD
25.ft CW
26.nf
27.ne \\$1
28..
74dab6c2 29.de Ve
984263bc
MD
30.ft R
31
32.fi
33..
74dab6c2
JR
34'''
35'''
36''' Set up \*(-- to give an unbreakable dash;
37''' string Tr holds user defined translation string.
38''' Bell System Logo is used as a dummy character.
39'''
984263bc 40.tr \(*W-|\(bv\*(Tr
984263bc 41.ie n \{\
74dab6c2
JR
42.ds -- \(*W-
43.ds PI pi
44.if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
45.if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
46.ds L" ""
47.ds R" ""
48''' \*(M", \*(S", \*(N" and \*(T" are the equivalent of
49''' \*(L" and \*(R", except that they are used on ".xx" lines,
50''' such as .IP and .SH, which do another additional levels of
51''' double-quote interpretation
52.ds M" """
53.ds S" """
54.ds N" """""
55.ds T" """""
56.ds L' '
57.ds R' '
58.ds M' '
59.ds S' '
60.ds N' '
61.ds T' '
984263bc
MD
62'br\}
63.el\{\
74dab6c2
JR
64.ds -- \(em\|
65.tr \*(Tr
66.ds L" ``
67.ds R" ''
68.ds M" ``
69.ds S" ''
70.ds N" ``
71.ds T" ''
72.ds L' `
73.ds R' '
74.ds M' `
75.ds S' '
76.ds N' `
77.ds T' '
78.ds PI \(*p
984263bc 79'br\}
74dab6c2
JR
80.\" If the F register is turned on, we'll generate
81.\" index entries out stderr for the following things:
82.\" TH Title
83.\" SH Header
84.\" Sh Subsection
85.\" Ip Item
86.\" X<> Xref (embedded
87.\" Of course, you have to process the output yourself
88.\" in some meaninful fashion.
89.if \nF \{
90.de IX
91.tm Index:\\$1\t\\n%\t"\\$2"
984263bc 92..
74dab6c2
JR
93.nr % 0
94.rr F
984263bc 95.\}
74dab6c2
JR
96.TH BIO_s_accept 3 "0.9.7d" "2/Sep/2004" "OpenSSL"
97.UC
98.if n .hy 0
984263bc 99.if n .na
74dab6c2
JR
100.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
101.de CQ \" put $1 in typewriter font
102.ft CW
103'if n "\c
104'if t \\&\\$1\c
105'if n \\&\\$1\c
106'if n \&"
107\\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
108'.ft R
109..
110.\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
111. \" AM - accent mark definitions
984263bc 112.bd B 3
74dab6c2 113. \" fudge factors for nroff and troff
984263bc 114.if n \{\
74dab6c2
JR
115. ds #H 0
116. ds #V .8m
117. ds #F .3m
118. ds #[ \f1
119. ds #] \fP
984263bc
MD
120.\}
121.if t \{\
74dab6c2
JR
122. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
123. ds #V .6m
124. ds #F 0
125. ds #[ \&
126. ds #] \&
984263bc 127.\}
74dab6c2 128. \" simple accents for nroff and troff
984263bc 129.if n \{\
74dab6c2
JR
130. ds ' \&
131. ds ` \&
132. ds ^ \&
133. ds , \&
134. ds ~ ~
135. ds ? ?
136. ds ! !
137. ds /
138. ds q
984263bc
MD
139.\}
140.if t \{\
74dab6c2
JR
141. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
142. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
143. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
144. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
145. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
146. ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
147. ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
148. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
149. ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
984263bc 150.\}
74dab6c2 151. \" troff and (daisy-wheel) nroff accents
984263bc
MD
152.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
153.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
74dab6c2
JR
154.ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
155.ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
156.ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
157.ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
984263bc
MD
158.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
159.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
160.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
161.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
162.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
163.ds ae a\h'-(\w'a'u*4/10)'e
164.ds Ae A\h'-(\w'A'u*4/10)'E
74dab6c2
JR
165.ds oe o\h'-(\w'o'u*4/10)'e
166.ds Oe O\h'-(\w'O'u*4/10)'E
167. \" corrections for vroff
984263bc
MD
168.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
169.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
74dab6c2 170. \" for low resolution devices (crt and lpr)
984263bc
MD
171.if \n(.H>23 .if \n(.V>19 \
172\{\
74dab6c2
JR
173. ds : e
174. ds 8 ss
175. ds v \h'-1'\o'\(aa\(ga'
176. ds _ \h'-1'^
177. ds . \h'-1'.
178. ds 3 3
179. ds o a
180. ds d- d\h'-1'\(ga
181. ds D- D\h'-1'\(hy
182. ds th \o'bp'
183. ds Th \o'LP'
184. ds ae ae
185. ds Ae AE
186. ds oe oe
187. ds Oe OE
984263bc
MD
188.\}
189.rm #[ #] #H #V #F C
984263bc
MD
190.SH "NAME"
191BIO_s_accept, BIO_set_accept_port, BIO_get_accept_port,
192BIO_set_nbio_accept, BIO_set_accept_bios, BIO_set_bind_mode,
74dab6c2 193BIO_get_bind_mode, BIO_do_accept \- accept BIO
984263bc 194.SH "SYNOPSIS"
74dab6c2 195.PP
984263bc
MD
196.Vb 1
197\& #include <openssl/bio.h>
198.Ve
199.Vb 1
200\& BIO_METHOD *BIO_s_accept(void);
201.Ve
202.Vb 2
203\& long BIO_set_accept_port(BIO *b, char *name);
204\& char *BIO_get_accept_port(BIO *b);
205.Ve
206.Vb 1
207\& BIO *BIO_new_accept(char *host_port);
208.Ve
209.Vb 2
210\& long BIO_set_nbio_accept(BIO *b, int n);
211\& long BIO_set_accept_bios(BIO *b, char *bio);
212.Ve
213.Vb 2
214\& long BIO_set_bind_mode(BIO *b, long mode);
215\& long BIO_get_bind_mode(BIO *b, long dummy);
216.Ve
217.Vb 3
218\& #define BIO_BIND_NORMAL 0
219\& #define BIO_BIND_REUSEADDR_IF_UNUSED 1
220\& #define BIO_BIND_REUSEADDR 2
221.Ve
222.Vb 1
223\& int BIO_do_accept(BIO *b);
224.Ve
225.SH "DESCRIPTION"
74dab6c2
JR
226\fIBIO_s_accept()\fR returns the accept BIO method. This is a wrapper
227round the platform's TCP/IP socket accept routines.
984263bc 228.PP
74dab6c2
JR
229Using accept BIOs, TCP/IP connections can be accepted and data
230transferred using only BIO routines. In this way any platform
231specific operations are hidden by the BIO abstraction.
984263bc 232.PP
74dab6c2 233Read and write operations on an accept BIO will perform I/O
984263bc 234on the underlying connection. If no connection is established
74dab6c2 235and the port (see below) is set up properly then the BIO
984263bc
MD
236waits for an incoming connection.
237.PP
238Accept BIOs support \fIBIO_puts()\fR but not \fIBIO_gets()\fR.
239.PP
74dab6c2 240If the close flag is set on an accept BIO then any active
984263bc 241connection on that chain is shutdown and the socket closed when
74dab6c2 242the BIO is freed.
984263bc 243.PP
74dab6c2
JR
244Calling \fIBIO_reset()\fR on a accept BIO will close any active
245connection and reset the BIO into a state where it awaits another
984263bc
MD
246incoming connection.
247.PP
74dab6c2 248\fIBIO_get_fd()\fR and \fIBIO_set_fd()\fR can be called to retrieve or set
984263bc
MD
249the accept socket. See BIO_s_fd(3)
250.PP
74dab6c2 251\fIBIO_set_accept_port()\fR uses the string \fBname\fR to set the accept
984263bc
MD
252port. The port is represented as a string of the form \*(L"host:port\*(R",
253where \*(L"host\*(R" is the interface to use and \*(L"port\*(R" is the port.
254Either or both values can be \*(L"*\*(R" which is interpreted as meaning
255any interface or port respectively. \*(L"port\*(R" has the same syntax
256as the port specified in \fIBIO_set_conn_port()\fR for connect BIOs,
257that is it can be a numerical port string or a string to lookup
258using \fIgetservbyname()\fR and a string table.
259.PP
74dab6c2
JR
260\fIBIO_new_accept()\fR combines \fIBIO_new()\fR and \fIBIO_set_accept_port()\fR into
261a single call: that is it creates a new accept BIO with port
262\fBhost_port\fR.
984263bc 263.PP
74dab6c2 264\fIBIO_set_nbio_accept()\fR sets the accept socket to blocking mode
984263bc
MD
265(the default) if \fBn\fR is 0 or non blocking mode if \fBn\fR is 1.
266.PP
74dab6c2 267\fIBIO_set_accept_bios()\fR can be used to set a chain of BIOs which
984263bc
MD
268will be duplicated and prepended to the chain when an incoming
269connection is received. This is useful if, for example, a
74dab6c2 270buffering or SSL BIO is required for each connection. The
984263bc 271chain of BIOs must not be freed after this call, they will
74dab6c2 272be automatically freed when the accept BIO is freed.
984263bc 273.PP
74dab6c2
JR
274\fIBIO_set_bind_mode()\fR and \fIBIO_get_bind_mode()\fR set and retrieve
275the current bind mode. If BIO_BIND_NORMAL (the default) is set
984263bc 276then another socket cannot be bound to the same port. If
74dab6c2
JR
277BIO_BIND_REUSEADDR is set then other sockets can bind to the
278same port. If BIO_BIND_REUSEADDR_IF_UNUSED is set then and
279attempt is first made to use BIO_BIN_NORMAL, if this fails
984263bc 280and the port is not in use then a second attempt is made
74dab6c2 281using BIO_BIND_REUSEADDR.
984263bc 282.PP
74dab6c2
JR
283\fIBIO_do_accept()\fR serves two functions. When it is first
284called, after the accept BIO has been setup, it will attempt
984263bc
MD
285to create the accept socket and bind an address to it. Second
286and subsequent calls to \fIBIO_do_accept()\fR will await an incoming
287connection, or request a retry in non blocking mode.
288.SH "NOTES"
74dab6c2 289When an accept BIO is at the end of a chain it will await an
984263bc 290incoming connection before processing I/O calls. When an accept
74dab6c2
JR
291BIO is not at then end of a chain it passes I/O calls to the next
292BIO in the chain.
984263bc 293.PP
74dab6c2 294When a connection is established a new socket BIO is created for
984263bc
MD
295the connection and appended to the chain. That is the chain is now
296accept->socket. This effectively means that attempting I/O on
297an initial accept socket will await an incoming connection then
298perform I/O on it.
299.PP
300If any additional BIOs have been set using \fIBIO_set_accept_bios()\fR
74dab6c2 301then they are placed between the socket and the accept BIO,
984263bc
MD
302that is the chain will be accept->otherbios->socket.
303.PP
304If a server wishes to process multiple connections (as is normally
74dab6c2 305the case) then the accept BIO must be made available for further
984263bc
MD
306incoming connections. This can be done by waiting for a connection and
307then calling:
308.PP
309.Vb 1
310\& connection = BIO_pop(accept);
311.Ve
74dab6c2
JR
312After this call \fBconnection\fR will contain a BIO for the recently
313established connection and \fBaccept\fR will now be a single BIO
984263bc
MD
314again which can be used to await further incoming connections.
315If no further connections will be accepted the \fBaccept\fR can
316be freed using \fIBIO_free()\fR.
317.PP
318If only a single connection will be processed it is possible to
74dab6c2
JR
319perform I/O using the accept BIO itself. This is often undesirable
320however because the accept BIO will still accept additional incoming
984263bc 321connections. This can be resolved by using \fIBIO_pop()\fR (see above)
74dab6c2 322and freeing up the accept BIO after the initial connection.
984263bc
MD
323.PP
324If the underlying accept socket is non-blocking and \fIBIO_do_accept()\fR is
325called to await an incoming connection it is possible for
74dab6c2 326\fIBIO_should_io_special()\fR with the reason BIO_RR_ACCEPT. If this happens
984263bc
MD
327then it is an indication that an accept attempt would block: the application
328should take appropriate action to wait until the underlying socket has
329accepted a connection and retry the call.
330.PP
74dab6c2
JR
331\fIBIO_set_accept_port()\fR, \fIBIO_get_accept_port()\fR, \fIBIO_set_nbio_accept()\fR,
332\fIBIO_set_accept_bios()\fR, \fIBIO_set_bind_mode()\fR, \fIBIO_get_bind_mode()\fR and
333\fIBIO_do_accept()\fR are macros.
984263bc 334.SH "RETURN VALUES"
74dab6c2 335TBA
984263bc 336.SH "EXAMPLE"
984263bc
MD
337This example accepts two connections on port 4444, sends messages
338down each and finally closes both down.
339.PP
340.Vb 3
341\& BIO *abio, *cbio, *cbio2;
342\& ERR_load_crypto_strings();
343\& abio = BIO_new_accept("4444");
344.Ve
345.Vb 6
346\& /* First call to BIO_accept() sets up accept BIO */
347\& if(BIO_do_accept(abio) <= 0) {
348\& fprintf(stderr, "Error setting up accept\en");
349\& ERR_print_errors_fp(stderr);
350\& exit(0);
351\& }
352.Ve
353.Vb 23
354\& /* Wait for incoming connection */
355\& if(BIO_do_accept(abio) <= 0) {
356\& fprintf(stderr, "Error accepting connection\en");
357\& ERR_print_errors_fp(stderr);
358\& exit(0);
359\& }
360\& fprintf(stderr, "Connection 1 established\en");
361\& /* Retrieve BIO for connection */
362\& cbio = BIO_pop(abio);
363\& BIO_puts(cbio, "Connection 1: Sending out Data on initial connection\en");
364\& fprintf(stderr, "Sent out data on connection 1\en");
365\& /* Wait for another connection */
366\& if(BIO_do_accept(abio) <= 0) {
367\& fprintf(stderr, "Error accepting connection\en");
368\& ERR_print_errors_fp(stderr);
369\& exit(0);
370\& }
371\& fprintf(stderr, "Connection 2 established\en");
372\& /* Close accept BIO to refuse further connections */
373\& cbio2 = BIO_pop(abio);
374\& BIO_free(abio);
375\& BIO_puts(cbio2, "Connection 2: Sending out Data on second\en");
376\& fprintf(stderr, "Sent out data on connection 2\en");
377.Ve
378.Vb 4
379\& BIO_puts(cbio, "Connection 1: Second connection established\en");
380\& /* Close the two established connections */
381\& BIO_free(cbio);
382\& BIO_free(cbio2);
383.Ve
384.SH "SEE ALSO"
74dab6c2
JR
385TBA
386
387.rn }` ''
388.IX Title "BIO_s_accept 3"
389.IX Name "BIO_s_accept, BIO_set_accept_port, BIO_get_accept_port,
390BIO_set_nbio_accept, BIO_set_accept_bios, BIO_set_bind_mode,
391BIO_get_bind_mode, BIO_do_accept - accept BIO"
392
393.IX Header "NAME"
394
395.IX Header "SYNOPSIS"
396
397.IX Header "DESCRIPTION"
398
399.IX Header "NOTES"
400
401.IX Header "RETURN VALUES"
402
403.IX Header "EXAMPLE"
404
984263bc 405.IX Header "SEE ALSO"
74dab6c2 406