diff options
Diffstat (limited to '3rdparty/asio/src/doc/overview/bsd_sockets.qbk')
-rw-r--r-- | 3rdparty/asio/src/doc/overview/bsd_sockets.qbk | 270 |
1 files changed, 270 insertions, 0 deletions
diff --git a/3rdparty/asio/src/doc/overview/bsd_sockets.qbk b/3rdparty/asio/src/doc/overview/bsd_sockets.qbk new file mode 100644 index 00000000000..acc67da29d4 --- /dev/null +++ b/3rdparty/asio/src/doc/overview/bsd_sockets.qbk @@ -0,0 +1,270 @@ +[/ + / Copyright (c) 2003-2016 Christopher M. Kohlhoff (chris at kohlhoff dot com) + / + / Distributed under the Boost Software License, Version 1.0. (See accompanying + / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) + /] + +[section:bsd_sockets The BSD Socket API and Asio] + +The Asio library includes a low-level socket interface based on the BSD socket +API, which is widely implemented and supported by extensive literature. It is +also used as the basis for networking APIs in other languages, like Java. This +low-level interface is designed to support the development of efficient and +scalable applications. For example, it permits programmers to exert finer +control over the number of system calls, avoid redundant data copying, minimise +the use of resources like threads, and so on. + +Unsafe and error prone aspects of the BSD socket API not included. For example, +the use of `int` to represent all sockets lacks type safety. The socket +representation in Asio uses a distinct type for each protocol, e.g. for TCP one +would use `ip::tcp::socket`, and for UDP one uses `ip::udp::socket`. + +The following table shows the mapping between the BSD socket API and Asio: + +[table + [ + [BSD Socket API Elements] + [Equivalents in Asio] + ] + [ + [socket descriptor - `int` (POSIX) or `SOCKET` (Windows)] + [ For TCP: [link asio.reference.ip__tcp.socket ip::tcp::socket], + [link asio.reference.ip__tcp.acceptor ip::tcp::acceptor] + + For UDP: [link asio.reference.ip__udp.socket ip::udp::socket] + + [link asio.reference.basic_socket basic_socket], + [link asio.reference.basic_stream_socket basic_stream_socket], + [link asio.reference.basic_datagram_socket basic_datagram_socket], + [link asio.reference.basic_raw_socket basic_raw_socket] ] + ] + [ + [`in_addr`, + `in6_addr`] + [ [link asio.reference.ip__address ip::address], + [link asio.reference.ip__address ip::address_v4], + [link asio.reference.ip__address ip::address_v6] ] + ] + [ + [`sockaddr_in`, + `sockaddr_in6`] + [ For TCP: [link asio.reference.ip__tcp.endpoint ip::tcp::endpoint] + + For UDP: [link asio.reference.ip__udp.endpoint ip::udp::endpoint] + + [link asio.reference.ip__basic_endpoint ip::basic_endpoint] ] + ] + [ + [`accept()`] + [ For TCP: [link asio.reference.basic_socket_acceptor.accept ip::tcp::acceptor::accept()] + + [link asio.reference.basic_socket_acceptor.accept basic_socket_acceptor::accept()] ] + ] + [ + [`bind()`] + [ For TCP: [link asio.reference.basic_socket.bind ip::tcp::acceptor::bind()], + [link asio.reference.basic_socket.bind ip::tcp::socket::bind()] + + For UDP: [link asio.reference.basic_socket.bind ip::udp::socket::bind()] + + [link asio.reference.basic_socket.bind basic_socket::bind()] ] + ] + [ + [`close()`] + [ For TCP: [link asio.reference.basic_socket.close ip::tcp::acceptor::close()], + [link asio.reference.basic_socket.close ip::tcp::socket::close()] + + For UDP: [link asio.reference.basic_socket.close ip::udp::socket::close()] + + [link asio.reference.basic_socket.close basic_socket::close()] ] + ] + [ + [`connect()`] + [ For TCP: [link asio.reference.basic_socket.connect ip::tcp::socket::connect()] + + For UDP: [link asio.reference.basic_socket.connect ip::udp::socket::connect()] + + [link asio.reference.basic_socket.connect basic_socket::connect()] ] + ] + [ + [`getaddrinfo()`, + `gethostbyaddr()`, + `gethostbyname()`, + `getnameinfo()`, + `getservbyname()`, + `getservbyport()`] + [ For TCP: [link asio.reference.ip__basic_resolver.resolve ip::tcp::resolver::resolve()], + [link asio.reference.ip__basic_resolver.async_resolve ip::tcp::resolver::async_resolve()] + + For UDP: [link asio.reference.ip__basic_resolver.resolve ip::udp::resolver::resolve()], + [link asio.reference.ip__basic_resolver.async_resolve ip::udp::resolver::async_resolve()] + + [link asio.reference.ip__basic_resolver.resolve ip::basic_resolver::resolve()], + [link asio.reference.ip__basic_resolver.async_resolve ip::basic_resolver::async_resolve()] ] + ] + [ + [`gethostname()`] + [ [link asio.reference.ip__host_name ip::host_name()] ] + ] + [ + [`getpeername()`] + [ For TCP: [link asio.reference.basic_socket.remote_endpoint ip::tcp::socket::remote_endpoint()] + + For UDP: [link asio.reference.basic_socket.remote_endpoint ip::udp::socket::remote_endpoint()] + + [link asio.reference.basic_socket.remote_endpoint basic_socket::remote_endpoint()] ] + ] + [ + [`getsockname()`] + [ For TCP: [link asio.reference.basic_socket.local_endpoint ip::tcp::acceptor::local_endpoint()], + [link asio.reference.basic_socket.local_endpoint ip::tcp::socket::local_endpoint()] + + For UDP: [link asio.reference.basic_socket.local_endpoint ip::udp::socket::local_endpoint()] + + [link asio.reference.basic_socket.local_endpoint basic_socket::local_endpoint()] ] + ] + [ + [`getsockopt()`] + [ For TCP: [link asio.reference.basic_socket.get_option ip::tcp::acceptor::get_option()], + [link asio.reference.basic_socket.get_option ip::tcp::socket::get_option()] + + For UDP: [link asio.reference.basic_socket.get_option ip::udp::socket::get_option()] + + [link asio.reference.basic_socket.get_option basic_socket::get_option()] ] + ] + [ + [`inet_addr()`, + `inet_aton()`, + `inet_pton()`] + [ [link asio.reference.ip__address.from_string ip::address::from_string()], + [link asio.reference.ip__address.from_string ip::address_v4::from_string()], + [link asio.reference.ip__address.from_string ip_address_v6::from_string()] ] + ] + [ + [`inet_ntoa()`, + `inet_ntop()`] + [ [link asio.reference.ip__address.to_string ip::address::to_string()], + [link asio.reference.ip__address.to_string ip::address_v4::to_string()], + [link asio.reference.ip__address.to_string ip_address_v6::to_string()] ] + ] + [ + [`ioctl()`] + [ For TCP: [link asio.reference.basic_socket.io_control ip::tcp::socket::io_control()] + + For UDP: [link asio.reference.basic_socket.io_control ip::udp::socket::io_control()] + + [link asio.reference.basic_socket.io_control basic_socket::io_control()] ] + ] + [ + [`listen()`] + [ For TCP: [link asio.reference.basic_socket_acceptor.listen ip::tcp::acceptor::listen()] + + [link asio.reference.basic_socket_acceptor.listen basic_socket_acceptor::listen()] ] + ] + [ + [`poll()`, + `select()`, + `pselect()`] + [ [link asio.reference.io_context.run io_context::run()], + [link asio.reference.io_context.run_one io_context::run_one()], + [link asio.reference.io_context.poll io_context::poll()], + [link asio.reference.io_context.poll_one io_context::poll_one()] + + Note: in conjunction with asynchronous operations. ] + ] + [ + [`readv()`, + `recv()`, + `read()`] + [ For TCP: [link asio.reference.basic_stream_socket.read_some ip::tcp::socket::read_some()], + [link asio.reference.basic_stream_socket.async_read_some ip::tcp::socket::async_read_some()], + [link asio.reference.basic_stream_socket.receive ip::tcp::socket::receive()], + [link asio.reference.basic_stream_socket.async_receive ip::tcp::socket::async_receive()] + + For UDP: [link asio.reference.basic_datagram_socket.receive ip::udp::socket::receive()], + [link asio.reference.basic_datagram_socket.async_receive ip::udp::socket::async_receive()] + + [link asio.reference.basic_stream_socket.read_some basic_stream_socket::read_some()], + [link asio.reference.basic_stream_socket.async_read_some basic_stream_socket::async_read_some()], + [link asio.reference.basic_stream_socket.receive basic_stream_socket::receive()], + [link asio.reference.basic_stream_socket.async_receive basic_stream_socket::async_receive()], + [link asio.reference.basic_datagram_socket.receive basic_datagram_socket::receive()], + [link asio.reference.basic_datagram_socket.async_receive basic_datagram_socket::async_receive()] ] + ] + [ + [`recvfrom()`] + [ For UDP: [link asio.reference.basic_datagram_socket.receive_from ip::udp::socket::receive_from()], + [link asio.reference.basic_datagram_socket.async_receive_from ip::udp::socket::async_receive_from()] + + [link asio.reference.basic_datagram_socket.receive_from basic_datagram_socket::receive_from()], + [link asio.reference.basic_datagram_socket.async_receive_from basic_datagram_socket::async_receive_from()] ] + ] + [ + [`send()`, + `write()`, + `writev()`] + [ For TCP: [link asio.reference.basic_stream_socket.write_some ip::tcp::socket::write_some()], + [link asio.reference.basic_stream_socket.async_write_some ip::tcp::socket::async_write_some()], + [link asio.reference.basic_stream_socket.send ip::tcp::socket::send()], + [link asio.reference.basic_stream_socket.async_send ip::tcp::socket::async_send()] + + For UDP: [link asio.reference.basic_datagram_socket.send ip::udp::socket::send()], + [link asio.reference.basic_datagram_socket.async_send ip::udp::socket::async_send()] + + [link asio.reference.basic_stream_socket.write_some basic_stream_socket::write_some()], + [link asio.reference.basic_stream_socket.async_write_some basic_stream_socket::async_write_some()], + [link asio.reference.basic_stream_socket.send basic_stream_socket::send()], + [link asio.reference.basic_stream_socket.async_send basic_stream_socket::async_send()], + [link asio.reference.basic_datagram_socket.send basic_datagram_socket::send()], + [link asio.reference.basic_datagram_socket.async_send basic_datagram_socket::async_send()] ] + ] + [ + [`sendto()`] + [ For UDP: [link asio.reference.basic_datagram_socket.send_to ip::udp::socket::send_to()], + [link asio.reference.basic_datagram_socket.async_send_to ip::udp::socket::async_send_to()] + + [link asio.reference.basic_datagram_socket.send_to basic_datagram_socket::send_to()], + [link asio.reference.basic_datagram_socket.async_send_to basic_datagram_socket::async_send_to()] ] + ] + [ + [`setsockopt()`] + [ For TCP: [link asio.reference.basic_socket.set_option ip::tcp::acceptor::set_option()], + [link asio.reference.basic_socket.set_option ip::tcp::socket::set_option()] + + For UDP: [link asio.reference.basic_socket.set_option ip::udp::socket::set_option()] + + [link asio.reference.basic_socket.set_option basic_socket::set_option()] ] + ] + [ + [`shutdown()`] + [ For TCP: [link asio.reference.basic_socket.shutdown ip::tcp::socket::shutdown()] + + For UDP: [link asio.reference.basic_socket.shutdown ip::udp::socket::shutdown()] + + [link asio.reference.basic_socket.shutdown basic_socket::shutdown()] ] + ] + [ + [`sockatmark()`] + [ For TCP: [link asio.reference.basic_socket.at_mark ip::tcp::socket::at_mark()] + + [link asio.reference.basic_socket.at_mark basic_socket::at_mark()] ] + ] + [ + [`socket()`] + [ For TCP: [link asio.reference.basic_socket.open ip::tcp::acceptor::open()], + [link asio.reference.basic_socket.open ip::tcp::socket::open()] + + For UDP: [link asio.reference.basic_socket.open ip::udp::socket::open()] + + [link asio.reference.basic_socket.open basic_socket::open()] ] + ] + [ + [`socketpair()`] + [ [link asio.reference.local__connect_pair local::connect_pair()] + + Note: POSIX operating systems only. ] + ] +] + +[endsect] |