]>
Commit | Line | Data |
---|---|---|
68a1c6b0 DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
9d8c2dfe | 5 | BIO_s_accept, BIO_set_accept_name, BIO_set_accept_port, BIO_get_accept_name, |
b4c1d72e | 6 | BIO_get_accept_port, BIO_new_accept, BIO_set_nbio_accept, BIO_set_accept_bios, |
88b8d83e VC |
7 | BIO_get_peer_name, BIO_get_peer_port, |
8 | BIO_get_accept_ip_family, BIO_set_accept_ip_family, | |
b4c1d72e | 9 | BIO_set_bind_mode, BIO_get_bind_mode, BIO_do_accept - accept BIO |
68a1c6b0 DSH |
10 | |
11 | =head1 SYNOPSIS | |
12 | ||
13 | #include <openssl/bio.h> | |
14 | ||
04f6b0fd | 15 | const BIO_METHOD *BIO_s_accept(void); |
68a1c6b0 | 16 | |
b4c1d72e | 17 | long BIO_set_accept_name(BIO *b, char *name); |
18 | char *BIO_get_accept_name(BIO *b); | |
19 | ||
3b7a5758 | 20 | long BIO_set_accept_port(BIO *b, char *port); |
bbdc9c98 | 21 | char *BIO_get_accept_port(BIO *b); |
68a1c6b0 DSH |
22 | |
23 | BIO *BIO_new_accept(char *host_port); | |
24 | ||
bbdc9c98 UM |
25 | long BIO_set_nbio_accept(BIO *b, int n); |
26 | long BIO_set_accept_bios(BIO *b, char *bio); | |
68a1c6b0 | 27 | |
88b8d83e VC |
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 | ||
bbdc9c98 | 33 | long BIO_set_bind_mode(BIO *b, long mode); |
8976eb24 | 34 | long BIO_get_bind_mode(BIO *b); |
68a1c6b0 | 35 | |
bbdc9c98 | 36 | int BIO_do_accept(BIO *b); |
68a1c6b0 DSH |
37 | |
38 | =head1 DESCRIPTION | |
39 | ||
40 | BIO_s_accept() returns the accept BIO method. This is a wrapper | |
41 | round the platform's TCP/IP socket accept routines. | |
42 | ||
bbdc9c98 | 43 | Using accept BIOs, TCP/IP connections can be accepted and data |
68a1c6b0 DSH |
44 | transferred using only BIO routines. In this way any platform |
45 | specific operations are hidden by the BIO abstraction. | |
46 | ||
47 | Read and write operations on an accept BIO will perform I/O | |
48 | on the underlying connection. If no connection is established | |
49 | and the port (see below) is set up properly then the BIO | |
50 | waits for an incoming connection. | |
51 | ||
52 | Accept BIOs support BIO_puts() but not BIO_gets(). | |
53 | ||
54 | If the close flag is set on an accept BIO then any active | |
55 | connection on that chain is shutdown and the socket closed when | |
56 | the BIO is freed. | |
57 | ||
b9b6a7e5 | 58 | Calling BIO_reset() on an accept BIO will close any active |
68a1c6b0 DSH |
59 | connection and reset the BIO into a state where it awaits another |
60 | incoming connection. | |
61 | ||
62 | BIO_get_fd() and BIO_set_fd() can be called to retrieve or set | |
9b86974e | 63 | the accept socket. See L<BIO_s_fd(3)> |
68a1c6b0 | 64 | |
b4c1d72e | 65 | BIO_set_accept_name() uses the string B<name> to set the accept |
66 | name. The name is represented as a string of the form "host:port", | |
68a1c6b0 | 67 | where "host" is the interface to use and "port" is the port. |
417be660 | 68 | The host can be "*" or empty which is interpreted as meaning |
b9b6a7e5 | 69 | any interface. If the host is an IPv6 address, it has to be |
417be660 | 70 | enclosed in brackets, for example "[::1]:https". "port" has the |
3b7a5758 | 71 | same syntax as the port specified in BIO_set_conn_port() for |
417be660 RL |
72 | connect BIOs, that is it can be a numerical port string or a |
73 | string to lookup using getservbyname() and a string table. | |
68a1c6b0 | 74 | |
3b7a5758 J |
75 | BIO_set_accept_port() uses the string B<port> to set the accept |
76 | port. "port" has the same syntax as the port specified in | |
77 | BIO_set_conn_port() for connect BIOs, that is it can be a numerical | |
78 | port string or a string to lookup using getservbyname() and a string | |
79 | table. | |
80 | ||
b4c1d72e | 81 | BIO_new_accept() combines BIO_new() and BIO_set_accept_name() into |
68a1c6b0 DSH |
82 | a single call: that is it creates a new accept BIO with port |
83 | B<host_port>. | |
84 | ||
85 | BIO_set_nbio_accept() sets the accept socket to blocking mode | |
86 | (the default) if B<n> is 0 or non blocking mode if B<n> is 1. | |
87 | ||
88 | BIO_set_accept_bios() can be used to set a chain of BIOs which | |
89 | will be duplicated and prepended to the chain when an incoming | |
1bc74519 | 90 | connection is received. This is useful if, for example, a |
2c281ebb DSH |
91 | buffering or SSL BIO is required for each connection. The |
92 | chain of BIOs must not be freed after this call, they will | |
93 | be automatically freed when the accept BIO is freed. | |
68a1c6b0 DSH |
94 | |
95 | BIO_set_bind_mode() and BIO_get_bind_mode() set and retrieve | |
91da5e77 | 96 | the current bind mode. If B<BIO_BIND_NORMAL> (the default) is set |
68a1c6b0 | 97 | then another socket cannot be bound to the same port. If |
91da5e77 RS |
98 | B<BIO_BIND_REUSEADDR> is set then other sockets can bind to the |
99 | same port. If B<BIO_BIND_REUSEADDR_IF_UNUSED> is set then and | |
68a1c6b0 DSH |
100 | attempt is first made to use BIO_BIN_NORMAL, if this fails |
101 | and the port is not in use then a second attempt is made | |
91da5e77 | 102 | using B<BIO_BIND_REUSEADDR>. |
68a1c6b0 DSH |
103 | |
104 | BIO_do_accept() serves two functions. When it is first | |
105 | called, after the accept BIO has been setup, it will attempt | |
106 | to create the accept socket and bind an address to it. Second | |
107 | and subsequent calls to BIO_do_accept() will await an incoming | |
924046ce | 108 | connection, or request a retry in non blocking mode. |
68a1c6b0 DSH |
109 | |
110 | =head1 NOTES | |
111 | ||
112 | When an accept BIO is at the end of a chain it will await an | |
113 | incoming connection before processing I/O calls. When an accept | |
114 | BIO is not at then end of a chain it passes I/O calls to the next | |
115 | BIO in the chain. | |
116 | ||
117 | When a connection is established a new socket BIO is created for | |
1e4e5492 | 118 | the connection and appended to the chain. That is the chain is now |
68a1c6b0 DSH |
119 | accept->socket. This effectively means that attempting I/O on |
120 | an initial accept socket will await an incoming connection then | |
121 | perform I/O on it. | |
122 | ||
123 | If any additional BIOs have been set using BIO_set_accept_bios() | |
124 | then they are placed between the socket and the accept BIO, | |
125 | that is the chain will be accept->otherbios->socket. | |
126 | ||
127 | If a server wishes to process multiple connections (as is normally | |
128 | the case) then the accept BIO must be made available for further | |
129 | incoming connections. This can be done by waiting for a connection and | |
130 | then calling: | |
131 | ||
132 | connection = BIO_pop(accept); | |
133 | ||
134 | After this call B<connection> will contain a BIO for the recently | |
135 | established connection and B<accept> will now be a single BIO | |
136 | again which can be used to await further incoming connections. | |
137 | If no further connections will be accepted the B<accept> can | |
138 | be freed using BIO_free(). | |
139 | ||
140 | If only a single connection will be processed it is possible to | |
141 | perform I/O using the accept BIO itself. This is often undesirable | |
142 | however because the accept BIO will still accept additional incoming | |
143 | connections. This can be resolved by using BIO_pop() (see above) | |
144 | and freeing up the accept BIO after the initial connection. | |
145 | ||
bbdc9c98 | 146 | If the underlying accept socket is non-blocking and BIO_do_accept() is |
924046ce DSH |
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 application | |
150 | should take appropriate action to wait until the underlying socket has | |
151 | accepted a connection and retry the call. | |
152 | ||
b4c1d72e | 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(), | |
88b8d83e VC |
155 | BIO_get_peer_name(), BIO_get_peer_port(), |
156 | BIO_get_accept_ip_family(), BIO_set_accept_ip_family(), | |
b4c1d72e | 157 | BIO_set_bind_mode(), BIO_get_bind_mode() and BIO_do_accept() are macros. |
bbdc9c98 | 158 | |
68a1c6b0 DSH |
159 | =head1 RETURN VALUES |
160 | ||
c03726ca | 161 | BIO_do_accept(), |
b4c1d72e | 162 | BIO_set_accept_name(), BIO_set_accept_port(), BIO_set_nbio_accept(), |
88b8d83e VC |
163 | BIO_set_accept_bios(), BIO_set_accept_ip_family(), and BIO_set_bind_mode() |
164 | return 1 for success and 0 or -1 for failure. | |
c03726ca | 165 | |
e86e76a6 | 166 | BIO_get_accept_name() returns the accept name or NULL on error. |
88b8d83e | 167 | BIO_get_peer_name() returns the peer name or NULL on error. |
3b7a5758 | 168 | |
88b8d83e VC |
169 | BIO_get_accept_port() returns the accept port as a string or NULL on error. |
170 | BIO_get_peer_port() returns the peer port as a string or NULL on error. | |
171 | BIO_get_accept_ip_family() returns the IP family or -1 on error. | |
c03726ca RS |
172 | |
173 | BIO_get_bind_mode() returns the set of B<BIO_BIND> flags, or -1 on failure. | |
174 | ||
175 | BIO_new_accept() returns a BIO or NULL on error. | |
68a1c6b0 DSH |
176 | |
177 | =head1 EXAMPLE | |
178 | ||
179 | This example accepts two connections on port 4444, sends messages | |
180 | down each and finally closes both down. | |
181 | ||
182 | BIO *abio, *cbio, *cbio2; | |
f672aee4 | 183 | |
68a1c6b0 | 184 | /* First call to BIO_accept() sets up accept BIO */ |
05ea606a RS |
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); | |
68a1c6b0 DSH |
190 | } |
191 | ||
192 | /* Wait for incoming connection */ | |
05ea606a RS |
193 | if (BIO_do_accept(abio) <= 0) { |
194 | fprintf(stderr, "Error accepting connection\n"); | |
195 | ERR_print_errors_fp(stderr); | |
196 | exit(1); | |
68a1c6b0 DSH |
197 | } |
198 | fprintf(stderr, "Connection 1 established\n"); | |
05ea606a | 199 | |
68a1c6b0 DSH |
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"); | |
05ea606a | 204 | |
68a1c6b0 | 205 | /* Wait for another connection */ |
05ea606a RS |
206 | if (BIO_do_accept(abio) <= 0) { |
207 | fprintf(stderr, "Error accepting connection\n"); | |
208 | ERR_print_errors_fp(stderr); | |
209 | exit(1); | |
68a1c6b0 DSH |
210 | } |
211 | fprintf(stderr, "Connection 2 established\n"); | |
05ea606a | 212 | |
68a1c6b0 DSH |
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"); | |
05ea606a | 220 | |
68a1c6b0 DSH |
221 | /* Close the two established connections */ |
222 | BIO_free(cbio); | |
223 | BIO_free(cbio2); | |
224 | ||
e2f92610 RS |
225 | =head1 COPYRIGHT |
226 | ||
c4d3c19b | 227 | Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 228 | |
4746f25a | 229 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
230 | this file except in compliance with the License. You can obtain a copy |
231 | in the file LICENSE in the source distribution or at | |
232 | L<https://www.openssl.org/source/license.html>. | |
233 | ||
234 | =cut |