]>
Commit | Line | Data |
---|---|---|
d33b215b RL |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | BIO_socket, BIO_connect, BIO_listen, BIO_accept_ex, BIO_closesocket - BIO | |
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); | |
13 | int BIO_connect(int sock, const BIO_ADDR *addr, int options); | |
14 | int BIO_listen(int sock, const BIO_ADDR *addr, int options); | |
15 | int BIO_accept_ex(int accept_sock, BIO_ADDR *peer, int options); | |
16 | int BIO_closesocket(int sock); | |
17 | ||
18 | =head1 DESCRIPTION | |
19 | ||
20 | BIO_socket() creates a socket in the domain B<domain>, of type | |
21 | B<socktype> and B<protocol>. Socket B<options> are currently unused, | |
22 | but is present for future use. | |
23 | ||
24 | BIO_connect() connects B<sock> to the address and service given by | |
25 | B<addr>. Connection B<options> may be zero or any combination of | |
26 | B<BIO_SOCK_KEEPALIVE>, B<BIO_SOCK_NONBLOCK> and B<BIO_SOCK_NODELAY>. | |
27 | The flags are described in L</FLAGS> below. | |
28 | ||
29 | BIO_listen() has B<sock> start listening on the address and service | |
30 | given by B<addr>. Connection B<options> may be zero or any | |
31 | combination of B<BIO_SOCK_KEEPALIVE>, B<BIO_SOCK_NONBLOCK>, | |
32 | B<BIO_SOCK_NODELAY>, B<BIO_SOCK_REUSEADDR> and B<BIO_SOCK_V6_ONLY>. | |
33 | The flags are described in L</FLAGS> below. | |
34 | ||
35 | BIO_accept_ex() waits for an incoming connections on the given | |
36 | socket B<accept_sock>. When it gets a connection, the address and | |
37 | port of the peer gets stored in B<peer> if that one is non-NULL. | |
38 | Accept B<options> may be zero or B<BIO_SOCK_NONBLOCK>, and is applied | |
39 | on the accepted socket. The flags are described in L</FLAGS> below. | |
40 | ||
41 | BIO_closesocket() closes B<sock>. | |
42 | ||
43 | =head1 FLAGS | |
44 | ||
45 | =over 4 | |
46 | ||
47 | =item BIO_SOCK_KEEPALIVE | |
48 | ||
49 | Enables regular sending of keep-alive messages. | |
50 | ||
51 | =item BIO_SOCK_NONBLOCK | |
52 | ||
53 | Sets the socket to non-blocking mode. | |
54 | ||
55 | =item BIO_SOCK_NODELAY | |
56 | ||
57 | Corresponds to B<TCP_NODELAY>, and disables the Nagle algorithm. With | |
58 | this set, any data will be sent as soon as possible instead of being | |
59 | buffered until there's enough for the socket to send out in one go. | |
60 | ||
61 | =item BIO_SOCK_REUSEADDR | |
62 | ||
63 | Try to reuse the address and port combination for a recently closed | |
64 | port. | |
65 | ||
66 | =item BIO_SOCK_V6_ONLY | |
67 | ||
68 | When creating an IPv6 socket, make it only listen for IPv6 addresses | |
69 | and not IPv4 addresses mapped to IPv6. | |
70 | ||
71 | =back | |
72 | ||
73 | These flags are bit flags, so they are to be combined with the | |
74 | C<|> operator, for example: | |
75 | ||
2947af32 | 76 | BIO_connect(sock, addr, BIO_SOCK_KEEPALIVE | BIO_SOCK_NONBLOCK); |
d33b215b RL |
77 | |
78 | =head1 RETURN VALUES | |
79 | ||
80 | BIO_socket() returns the socket number on success or B<INVALID_SOCKET> | |
b9b6a7e5 | 81 | (-1) on error. When an error has occurred, the OpenSSL error stack |
d33b215b RL |
82 | will hold the error data and errno has the system error. |
83 | ||
84 | BIO_connect() and BIO_listen() return 1 on success or 0 on error. | |
b9b6a7e5 | 85 | When an error has occurred, the OpenSSL error stack will hold the error |
d33b215b RL |
86 | data and errno has the system error. |
87 | ||
88 | BIO_accept_ex() returns the accepted socket on success or | |
b9b6a7e5 | 89 | B<INVALID_SOCKET> (-1) on error. When an error has occurred, the |
d33b215b RL |
90 | OpenSSL error stack will hold the error data and errno has the system |
91 | error. | |
92 | ||
93 | =head1 HISTORY | |
94 | ||
95 | BIO_gethostname(), BIO_get_port(), BIO_get_host_ip(), | |
a95d7574 RS |
96 | BIO_get_accept_socket() and BIO_accept() were deprecated in |
97 | OpenSSL 1.1.0. Use the functions described above instead. | |
d33b215b RL |
98 | |
99 | =head1 SEE ALSO | |
100 | ||
101 | L<BIO_ADDR(3)> | |
99ec4fdb | 102 | |
e2f92610 RS |
103 | =head1 COPYRIGHT |
104 | ||
105 | Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. | |
106 | ||
107 | Licensed under the OpenSSL license (the "License"). You may not use | |
108 | this file except in compliance with the License. You can obtain a copy | |
109 | in the file LICENSE in the source distribution or at | |
110 | L<https://www.openssl.org/source/license.html>. | |
111 | ||
112 | =cut |