]>
Commit | Line | Data |
---|---|---|
d33b215b RL |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
ebc01683 | 5 | BIO_socket, BIO_bind, BIO_connect, BIO_listen, BIO_accept_ex, BIO_closesocket - BIO |
d33b215b RL |
6 | socket communication setup routines |
7 | ||
8 | =head1 SYNOPSIS | |
9 | ||
10 | #include <openssl/bio.h> | |
11 | ||
12 | int BIO_socket(int domain, int socktype, int protocol, int options); | |
ebc01683 | 13 | int BIO_bind(int sock, const BIO_ADDR *addr, int options); |
d33b215b RL |
14 | int BIO_connect(int sock, const BIO_ADDR *addr, int options); |
15 | int BIO_listen(int sock, const BIO_ADDR *addr, int options); | |
16 | int BIO_accept_ex(int accept_sock, BIO_ADDR *peer, int options); | |
17 | int BIO_closesocket(int sock); | |
18 | ||
19 | =head1 DESCRIPTION | |
20 | ||
21 | BIO_socket() creates a socket in the domain B<domain>, of type | |
22 | B<socktype> and B<protocol>. Socket B<options> are currently unused, | |
23 | but is present for future use. | |
24 | ||
ebc01683 JH |
25 | BIO_bind() binds the source address and service to a socket and |
26 | may be useful before calling BIO_connect(). The options may include | |
ea8d07b1 | 27 | B<BIO_SOCK_REUSEADDR>, which is described in L</FLAGS> below. |
ebc01683 | 28 | |
d33b215b RL |
29 | BIO_connect() connects B<sock> to the address and service given by |
30 | B<addr>. Connection B<options> may be zero or any combination of | |
31 | B<BIO_SOCK_KEEPALIVE>, B<BIO_SOCK_NONBLOCK> and B<BIO_SOCK_NODELAY>. | |
32 | The flags are described in L</FLAGS> below. | |
33 | ||
34 | BIO_listen() has B<sock> start listening on the address and service | |
35 | given by B<addr>. Connection B<options> may be zero or any | |
36 | combination of B<BIO_SOCK_KEEPALIVE>, B<BIO_SOCK_NONBLOCK>, | |
37 | B<BIO_SOCK_NODELAY>, B<BIO_SOCK_REUSEADDR> and B<BIO_SOCK_V6_ONLY>. | |
38 | The flags are described in L</FLAGS> below. | |
39 | ||
40 | BIO_accept_ex() waits for an incoming connections on the given | |
41 | socket B<accept_sock>. When it gets a connection, the address and | |
42 | port of the peer gets stored in B<peer> if that one is non-NULL. | |
43 | Accept B<options> may be zero or B<BIO_SOCK_NONBLOCK>, and is applied | |
44 | on the accepted socket. The flags are described in L</FLAGS> below. | |
45 | ||
46 | BIO_closesocket() closes B<sock>. | |
47 | ||
48 | =head1 FLAGS | |
49 | ||
50 | =over 4 | |
51 | ||
52 | =item BIO_SOCK_KEEPALIVE | |
53 | ||
54 | Enables regular sending of keep-alive messages. | |
55 | ||
56 | =item BIO_SOCK_NONBLOCK | |
57 | ||
490c8711 | 58 | Sets the socket to nonblocking mode. |
d33b215b RL |
59 | |
60 | =item BIO_SOCK_NODELAY | |
61 | ||
62 | Corresponds to B<TCP_NODELAY>, and disables the Nagle algorithm. With | |
63 | this set, any data will be sent as soon as possible instead of being | |
64 | buffered until there's enough for the socket to send out in one go. | |
65 | ||
66 | =item BIO_SOCK_REUSEADDR | |
67 | ||
68 | Try to reuse the address and port combination for a recently closed | |
69 | port. | |
70 | ||
71 | =item BIO_SOCK_V6_ONLY | |
72 | ||
73 | When creating an IPv6 socket, make it only listen for IPv6 addresses | |
74 | and not IPv4 addresses mapped to IPv6. | |
75 | ||
a3e53d56 TS |
76 | =item BIO_SOCK_TFO |
77 | ||
78 | Enables TCP Fast Open on the socket. Uses appropriate APIs on | |
79 | supported operating systems, including Linux, macOS and FreeBSD. Can | |
80 | be used with BIO_connect(), BIO_set_conn_mode(), BIO_set_bind_mode(), | |
81 | and BIO_listen(). | |
82 | On Linux kernels before 4.14, use BIO_set_conn_address() to specify | |
83 | the peer address before starting the TLS handshake. | |
84 | ||
d33b215b RL |
85 | =back |
86 | ||
87 | These flags are bit flags, so they are to be combined with the | |
88 | C<|> operator, for example: | |
89 | ||
2947af32 | 90 | BIO_connect(sock, addr, BIO_SOCK_KEEPALIVE | BIO_SOCK_NONBLOCK); |
d33b215b RL |
91 | |
92 | =head1 RETURN VALUES | |
93 | ||
94 | BIO_socket() returns the socket number on success or B<INVALID_SOCKET> | |
b9b6a7e5 | 95 | (-1) on error. When an error has occurred, the OpenSSL error stack |
d33b215b RL |
96 | will hold the error data and errno has the system error. |
97 | ||
ebc01683 | 98 | BIO_bind(), BIO_connect() and BIO_listen() return 1 on success or 0 on error. |
b9b6a7e5 | 99 | When an error has occurred, the OpenSSL error stack will hold the error |
d33b215b RL |
100 | data and errno has the system error. |
101 | ||
102 | BIO_accept_ex() returns the accepted socket on success or | |
b9b6a7e5 | 103 | B<INVALID_SOCKET> (-1) on error. When an error has occurred, the |
d33b215b RL |
104 | OpenSSL error stack will hold the error data and errno has the system |
105 | error. | |
106 | ||
b5c4bbbe JL |
107 | =head1 SEE ALSO |
108 | ||
109 | L<BIO_ADDR(3)> | |
110 | ||
d33b215b RL |
111 | =head1 HISTORY |
112 | ||
113 | BIO_gethostname(), BIO_get_port(), BIO_get_host_ip(), | |
938e82f6 JL |
114 | BIO_get_accept_socket() and BIO_accept() were deprecated in OpenSSL 1.1.0. |
115 | Use the functions described above instead. | |
d33b215b | 116 | |
e2f92610 RS |
117 | =head1 COPYRIGHT |
118 | ||
0f84cbc3 | 119 | Copyright 2016-2020 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 120 | |
4746f25a | 121 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
122 | this file except in compliance with the License. You can obtain a copy |
123 | in the file LICENSE in the source distribution or at | |
124 | L<https://www.openssl.org/source/license.html>. | |
125 | ||
126 | =cut |