ceph/src/boost/libs/asio/doc/overview/bsd_sockets.qbk

   1 [/
   2  / Copyright (c) 2003-2016 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
  10 The Boost.Asio library includes a low-level socket interface based on the BSD socket
  11 API, which is widely implemented and supported by extensive literature. It is
  12 also used as the basis for networking APIs in other languages, like Java. This
  13 low-level interface is designed to support the development of efficient and
  14 scalable applications. For example, it permits programmers to exert finer
  15 control over the number of system calls, avoid redundant data copying, minimise
  16 the use of resources like threads, and so on.
  17
  18 Unsafe and error prone aspects of the BSD socket API not included. For example,
  19 the use of `int` to represent all sockets lacks type safety. The socket
  20 representation in Boost.Asio uses a distinct type for each protocol, e.g. for TCP one
  21 would use `ip::tcp::socket`, and for UDP one uses `ip::udp::socket`.
  22
  23 The 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_service.run io_service::run()],
 170                [link boost_asio.reference.io_service.run_one io_service::run_one()],
 171                [link boost_asio.reference.io_service.poll io_service::poll()],
 172                [link boost_asio.reference.io_service.poll_one io_service::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]