1[/
2 / Copyright (c) 2003-2021 Christopher M. Kohlhoff (chris at kohlhoff dot com)
3 /
4 / Distributed under the Boost Software License, Version 1.0. (See accompanying
5 / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
6 /]
7
8[section:bsd_sockets The BSD Socket API and Boost.Asio]
9
10The Boost.Asio library includes a low-level socket interface based on the BSD socket
11API, which is widely implemented and supported by extensive literature. It is
12also used as the basis for networking APIs in other languages, like Java. This
13low-level interface is designed to support the development of efficient and
14scalable applications. For example, it permits programmers to exert finer
15control over the number of system calls, avoid redundant data copying, minimise
16the use of resources like threads, and so on.
17
18Unsafe and error prone aspects of the BSD socket API are not included. For
19example, the use of `int` to represent all sockets lacks type safety. The
20socket representation in Boost.Asio uses a distinct type for each protocol, e.g. for
21TCP one would use `ip::tcp::socket`, and for UDP one uses `ip::udp::socket`.
22
23The following table shows the mapping between the BSD socket API and Boost.Asio:
24
25[table
26  [
27    [BSD Socket API Elements]
28    [Equivalents in Boost.Asio]
29  ]
30  [
31    [socket descriptor - `int` (POSIX) or `SOCKET` (Windows)]
32    [ For TCP: [link boost_asio.reference.ip__tcp.socket ip::tcp::socket],
33               [link boost_asio.reference.ip__tcp.acceptor ip::tcp::acceptor]
34
35      For UDP: [link boost_asio.reference.ip__udp.socket ip::udp::socket]
36
37               [link boost_asio.reference.basic_socket basic_socket],
38               [link boost_asio.reference.basic_stream_socket basic_stream_socket],
39               [link boost_asio.reference.basic_datagram_socket basic_datagram_socket],
40               [link boost_asio.reference.basic_raw_socket basic_raw_socket] ]
41  ]
42  [
43    [`in_addr`,
44     `in6_addr`]
45    [          [link boost_asio.reference.ip__address ip::address],
46               [link boost_asio.reference.ip__address ip::address_v4],
47               [link boost_asio.reference.ip__address ip::address_v6] ]
48  ]
49  [
50    [`sockaddr_in`,
51     `sockaddr_in6`]
52    [ For TCP: [link boost_asio.reference.ip__tcp.endpoint ip::tcp::endpoint]
53
54      For UDP: [link boost_asio.reference.ip__udp.endpoint ip::udp::endpoint]
55
56               [link boost_asio.reference.ip__basic_endpoint ip::basic_endpoint] ]
57  ]
58  [
59    [`accept()`]
60    [ For TCP: [link boost_asio.reference.basic_socket_acceptor.accept ip::tcp::acceptor::accept()]
61
62               [link boost_asio.reference.basic_socket_acceptor.accept basic_socket_acceptor::accept()] ]
63  ]
64  [
65    [`bind()`]
66    [ For TCP: [link boost_asio.reference.basic_socket.bind ip::tcp::acceptor::bind()],
67               [link boost_asio.reference.basic_socket.bind ip::tcp::socket::bind()]
68
69      For UDP: [link boost_asio.reference.basic_socket.bind ip::udp::socket::bind()]
70
71               [link boost_asio.reference.basic_socket.bind basic_socket::bind()] ]
72  ]
73  [
74    [`close()`]
75    [ For TCP: [link boost_asio.reference.basic_socket.close ip::tcp::acceptor::close()],
76               [link boost_asio.reference.basic_socket.close ip::tcp::socket::close()]
77
78      For UDP: [link boost_asio.reference.basic_socket.close ip::udp::socket::close()]
79
80               [link boost_asio.reference.basic_socket.close basic_socket::close()] ]
81  ]
82  [
83    [`connect()`]
84    [ For TCP: [link boost_asio.reference.basic_socket.connect ip::tcp::socket::connect()]
85
86      For UDP: [link boost_asio.reference.basic_socket.connect ip::udp::socket::connect()]
87
88               [link boost_asio.reference.basic_socket.connect basic_socket::connect()] ]
89  ]
90  [
91    [`getaddrinfo()`,
92     `gethostbyaddr()`,
93     `gethostbyname()`,
94     `getnameinfo()`,
95     `getservbyname()`,
96     `getservbyport()`]
97    [ For TCP: [link boost_asio.reference.ip__basic_resolver.resolve ip::tcp::resolver::resolve()],
98               [link boost_asio.reference.ip__basic_resolver.async_resolve ip::tcp::resolver::async_resolve()]
99
100      For UDP: [link boost_asio.reference.ip__basic_resolver.resolve ip::udp::resolver::resolve()],
101               [link boost_asio.reference.ip__basic_resolver.async_resolve ip::udp::resolver::async_resolve()]
102
103               [link boost_asio.reference.ip__basic_resolver.resolve ip::basic_resolver::resolve()],
104               [link boost_asio.reference.ip__basic_resolver.async_resolve ip::basic_resolver::async_resolve()] ]
105  ]
106  [
107    [`gethostname()`]
108    [          [link boost_asio.reference.ip__host_name ip::host_name()] ]
109  ]
110  [
111    [`getpeername()`]
112    [ For TCP: [link boost_asio.reference.basic_socket.remote_endpoint ip::tcp::socket::remote_endpoint()]
113
114      For UDP: [link boost_asio.reference.basic_socket.remote_endpoint ip::udp::socket::remote_endpoint()]
115
116               [link boost_asio.reference.basic_socket.remote_endpoint basic_socket::remote_endpoint()] ]
117  ]
118  [
119    [`getsockname()`]
120    [ For TCP: [link boost_asio.reference.basic_socket.local_endpoint ip::tcp::acceptor::local_endpoint()],
121               [link boost_asio.reference.basic_socket.local_endpoint ip::tcp::socket::local_endpoint()]
122
123      For UDP: [link boost_asio.reference.basic_socket.local_endpoint ip::udp::socket::local_endpoint()]
124
125               [link boost_asio.reference.basic_socket.local_endpoint basic_socket::local_endpoint()] ]
126  ]
127  [
128    [`getsockopt()`]
129    [ For TCP: [link boost_asio.reference.basic_socket.get_option ip::tcp::acceptor::get_option()],
130               [link boost_asio.reference.basic_socket.get_option ip::tcp::socket::get_option()]
131
132      For UDP: [link boost_asio.reference.basic_socket.get_option ip::udp::socket::get_option()]
133
134               [link boost_asio.reference.basic_socket.get_option basic_socket::get_option()] ]
135  ]
136  [
137    [`inet_addr()`,
138     `inet_aton()`,
139     `inet_pton()`]
140    [          [link boost_asio.reference.ip__address.from_string ip::address::from_string()],
141               [link boost_asio.reference.ip__address.from_string ip::address_v4::from_string()],
142               [link boost_asio.reference.ip__address.from_string ip_address_v6::from_string()] ]
143  ]
144  [
145    [`inet_ntoa()`,
146     `inet_ntop()`]
147    [          [link boost_asio.reference.ip__address.to_string ip::address::to_string()],
148               [link boost_asio.reference.ip__address.to_string ip::address_v4::to_string()],
149               [link boost_asio.reference.ip__address.to_string ip_address_v6::to_string()] ]
150  ]
151  [
152    [`ioctl()`]
153    [ For TCP: [link boost_asio.reference.basic_socket.io_control ip::tcp::socket::io_control()]
154
155      For UDP: [link boost_asio.reference.basic_socket.io_control ip::udp::socket::io_control()]
156
157               [link boost_asio.reference.basic_socket.io_control basic_socket::io_control()] ]
158  ]
159  [
160    [`listen()`]
161    [ For TCP: [link boost_asio.reference.basic_socket_acceptor.listen ip::tcp::acceptor::listen()]
162
163               [link boost_asio.reference.basic_socket_acceptor.listen basic_socket_acceptor::listen()] ]
164  ]
165  [
166    [`poll()`,
167     `select()`,
168     `pselect()`]
169    [          [link boost_asio.reference.io_context.run io_context::run()],
170               [link boost_asio.reference.io_context.run_one io_context::run_one()],
171               [link boost_asio.reference.io_context.poll io_context::poll()],
172               [link boost_asio.reference.io_context.poll_one io_context::poll_one()]
173
174      Note: in conjunction with asynchronous operations. ]
175  ]
176  [
177    [`readv()`,
178     `recv()`,
179     `read()`]
180    [ For TCP: [link boost_asio.reference.basic_stream_socket.read_some ip::tcp::socket::read_some()],
181               [link boost_asio.reference.basic_stream_socket.async_read_some ip::tcp::socket::async_read_some()],
182               [link boost_asio.reference.basic_stream_socket.receive ip::tcp::socket::receive()],
183               [link boost_asio.reference.basic_stream_socket.async_receive ip::tcp::socket::async_receive()]
184
185      For UDP: [link boost_asio.reference.basic_datagram_socket.receive ip::udp::socket::receive()],
186               [link boost_asio.reference.basic_datagram_socket.async_receive ip::udp::socket::async_receive()]
187
188               [link boost_asio.reference.basic_stream_socket.read_some basic_stream_socket::read_some()],
189               [link boost_asio.reference.basic_stream_socket.async_read_some basic_stream_socket::async_read_some()],
190               [link boost_asio.reference.basic_stream_socket.receive basic_stream_socket::receive()],
191               [link boost_asio.reference.basic_stream_socket.async_receive basic_stream_socket::async_receive()],
192               [link boost_asio.reference.basic_datagram_socket.receive basic_datagram_socket::receive()],
193               [link boost_asio.reference.basic_datagram_socket.async_receive basic_datagram_socket::async_receive()] ]
194  ]
195  [
196    [`recvfrom()`]
197    [ For UDP: [link boost_asio.reference.basic_datagram_socket.receive_from ip::udp::socket::receive_from()],
198               [link boost_asio.reference.basic_datagram_socket.async_receive_from ip::udp::socket::async_receive_from()]
199
200               [link boost_asio.reference.basic_datagram_socket.receive_from basic_datagram_socket::receive_from()],
201               [link boost_asio.reference.basic_datagram_socket.async_receive_from basic_datagram_socket::async_receive_from()] ]
202  ]
203  [
204    [`send()`,
205     `write()`,
206     `writev()`]
207    [ For TCP: [link boost_asio.reference.basic_stream_socket.write_some ip::tcp::socket::write_some()],
208               [link boost_asio.reference.basic_stream_socket.async_write_some ip::tcp::socket::async_write_some()],
209               [link boost_asio.reference.basic_stream_socket.send ip::tcp::socket::send()],
210               [link boost_asio.reference.basic_stream_socket.async_send ip::tcp::socket::async_send()]
211
212      For UDP: [link boost_asio.reference.basic_datagram_socket.send ip::udp::socket::send()],
213               [link boost_asio.reference.basic_datagram_socket.async_send ip::udp::socket::async_send()]
214
215               [link boost_asio.reference.basic_stream_socket.write_some basic_stream_socket::write_some()],
216               [link boost_asio.reference.basic_stream_socket.async_write_some basic_stream_socket::async_write_some()],
217               [link boost_asio.reference.basic_stream_socket.send basic_stream_socket::send()],
218               [link boost_asio.reference.basic_stream_socket.async_send basic_stream_socket::async_send()],
219               [link boost_asio.reference.basic_datagram_socket.send basic_datagram_socket::send()],
220               [link boost_asio.reference.basic_datagram_socket.async_send basic_datagram_socket::async_send()] ]
221  ]
222  [
223    [`sendto()`]
224    [ For UDP: [link boost_asio.reference.basic_datagram_socket.send_to ip::udp::socket::send_to()],
225               [link boost_asio.reference.basic_datagram_socket.async_send_to ip::udp::socket::async_send_to()]
226
227               [link boost_asio.reference.basic_datagram_socket.send_to basic_datagram_socket::send_to()],
228               [link boost_asio.reference.basic_datagram_socket.async_send_to basic_datagram_socket::async_send_to()] ]
229  ]
230  [
231    [`setsockopt()`]
232    [ For TCP: [link boost_asio.reference.basic_socket.set_option ip::tcp::acceptor::set_option()],
233               [link boost_asio.reference.basic_socket.set_option ip::tcp::socket::set_option()]
234
235      For UDP: [link boost_asio.reference.basic_socket.set_option ip::udp::socket::set_option()]
236
237               [link boost_asio.reference.basic_socket.set_option basic_socket::set_option()] ]
238  ]
239  [
240    [`shutdown()`]
241    [ For TCP: [link boost_asio.reference.basic_socket.shutdown ip::tcp::socket::shutdown()]
242
243      For UDP: [link boost_asio.reference.basic_socket.shutdown ip::udp::socket::shutdown()]
244
245               [link boost_asio.reference.basic_socket.shutdown basic_socket::shutdown()] ]
246  ]
247  [
248    [`sockatmark()`]
249    [ For TCP: [link boost_asio.reference.basic_socket.at_mark ip::tcp::socket::at_mark()]
250
251               [link boost_asio.reference.basic_socket.at_mark basic_socket::at_mark()] ]
252  ]
253  [
254    [`socket()`]
255    [ For TCP: [link boost_asio.reference.basic_socket.open ip::tcp::acceptor::open()],
256               [link boost_asio.reference.basic_socket.open ip::tcp::socket::open()]
257
258      For UDP: [link boost_asio.reference.basic_socket.open ip::udp::socket::open()]
259
260               [link boost_asio.reference.basic_socket.open basic_socket::open()] ]
261  ]
262  [
263    [`socketpair()`]
264    [          [link boost_asio.reference.local__connect_pair local::connect_pair()]
265
266      Note: POSIX operating systems only. ]
267  ]
268]
269
270[endsect]
271