libs/asio/doc/overview/posix.qbk

   1 [/
   2  / Copyright (c) 2003-2017 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:posix POSIX-Specific Functionality]
   9
  10 [link boost_asio.overview.posix.local UNIX Domain Sockets]
  11
  12 [link boost_asio.overview.posix.stream_descriptor Stream-Oriented File Descriptors]
  13
  14 [link boost_asio.overview.posix.fork Fork]
  15
  16 [section:local UNIX Domain Sockets]
  17
  18 Boost.Asio provides basic support UNIX domain sockets (also known as local sockets).
  19 The simplest use involves creating a pair of connected sockets. The following
  20 code:
  21
  22   local::stream_protocol::socket socket1(my_io_service);
  23   local::stream_protocol::socket socket2(my_io_service);
  24   local::connect_pair(socket1, socket2);
  25
  26 will create a pair of stream-oriented sockets. To do the same for
  27 datagram-oriented sockets, use:
  28
  29   local::datagram_protocol::socket socket1(my_io_service);
  30   local::datagram_protocol::socket socket2(my_io_service);
  31   local::connect_pair(socket1, socket2);
  32
  33 A UNIX domain socket server may be created by binding an acceptor to an
  34 endpoint, in much the same way as one does for a TCP server:
  35
  36   ::unlink("/tmp/foobar"); // Remove previous binding.
  37   local::stream_protocol::endpoint ep("/tmp/foobar");
  38   local::stream_protocol::acceptor acceptor(my_io_service, ep);
  39   local::stream_protocol::socket socket(my_io_service);
  40   acceptor.accept(socket);
  41
  42 A client that connects to this server might look like:
  43
  44   local::stream_protocol::endpoint ep("/tmp/foobar");
  45   local::stream_protocol::socket socket(my_io_service);
  46   socket.connect(ep);
  47
  48 Transmission of file descriptors or credentials across UNIX domain sockets is
  49 not directly supported within Boost.Asio, but may be achieved by accessing the
  50 socket's underlying descriptor using the [link
  51 boost_asio.reference.basic_socket.native_handle native_handle()] member function.
  52
  53 [heading See Also]
  54
  55 [link boost_asio.reference.local__connect_pair local::connect_pair],
  56 [link boost_asio.reference.local__datagram_protocol local::datagram_protocol],
  57 [link boost_asio.reference.local__datagram_protocol.endpoint local::datagram_protocol::endpoint],
  58 [link boost_asio.reference.local__datagram_protocol.socket local::datagram_protocol::socket],
  59 [link boost_asio.reference.local__stream_protocol local::stream_protocol],
  60 [link boost_asio.reference.local__stream_protocol.acceptor local::stream_protocol::acceptor],
  61 [link boost_asio.reference.local__stream_protocol.endpoint local::stream_protocol::endpoint],
  62 [link boost_asio.reference.local__stream_protocol.iostream local::stream_protocol::iostream],
  63 [link boost_asio.reference.local__stream_protocol.socket local::stream_protocol::socket],
  64 [link boost_asio.examples.cpp03_examples.unix_domain_sockets UNIX domain sockets examples].
  65
  66 [heading Notes]
  67
  68 UNIX domain sockets are only available at compile time if supported by the
  69 target operating system. A program may test for the macro
  70 `BOOST_ASIO_HAS_LOCAL_SOCKETS` to determine whether they are supported.
  71
  72 [endsect]
  73
  74 [section:stream_descriptor Stream-Oriented File Descriptors]
  75
  76 Boost.Asio includes classes added to permit synchronous and asynchronous read and
  77 write operations to be performed on POSIX file descriptors, such as pipes,
  78 standard input and output, and various devices.
  79
  80 These classes also provide limited support for regular files. This support
  81 assumes that the underlying read and write operations provided by the operating
  82 system never fail with `EAGAIN` or `EWOULDBLOCK`. (This assumption normally
  83 holds for buffered file I/O.)  Synchronous and asynchronous read and write
  84 operations on file descriptors will succeed but the I/O will always be
  85 performed immediately. Wait operations, and operations involving
  86 `boost::asio::null_buffers`, are not portably supported.
  87
  88 For example, to perform read and write operations on standard input
  89 and output, the following objects may be created:
  90
  91   posix::stream_descriptor in(my_io_service, ::dup(STDIN_FILENO));
  92   posix::stream_descriptor out(my_io_service, ::dup(STDOUT_FILENO));
  93
  94 These are then used as synchronous or asynchronous read and write streams. This
  95 means the objects can be used with any of the [link boost_asio.reference.read
  96 read()], [link boost_asio.reference.async_read async_read()], [link
  97 boost_asio.reference.write write()], [link boost_asio.reference.async_write async_write()],
  98 [link boost_asio.reference.read_until read_until()] or [link
  99 boost_asio.reference.async_read_until async_read_until()] free functions.
 100
 101 [heading See Also]
 102
 103 [link boost_asio.reference.posix__stream_descriptor posix::stream_descriptor],
 104 [link boost_asio.reference.posix__basic_stream_descriptor posix::basic_stream_descriptor],
 105 [link boost_asio.reference.posix__stream_descriptor_service posix::stream_descriptor_service],
 106 [link boost_asio.examples.cpp03_examples.chat Chat example (C++03)],
 107 [link boost_asio.examples.cpp11_examples.chat Chat example (C++11)].
 108
 109 [heading Notes]
 110
 111 POSIX stream descriptors are only available at compile time if supported by the
 112 target operating system. A program may test for the macro
 113 `BOOST_ASIO_HAS_POSIX_STREAM_DESCRIPTOR` to determine whether they are supported.
 114
 115 [endsect]
 116
 117 [section:fork Fork]
 118
 119 Boost.Asio supports programs that utilise the `fork()` system call. Provided the
 120 program calls `io_service.notify_fork()` at the appropriate times, Boost.Asio will
 121 recreate any internal file descriptors (such as the "self-pipe trick"
 122 descriptor used for waking up a reactor). The notification is usually performed
 123 as follows:
 124
 125   io_service_.notify_fork(boost::asio::io_service::fork_prepare);
 126   if (fork() == 0)
 127   {
 128     io_service_.notify_fork(boost::asio::io_service::fork_child);
 129     ...
 130   }
 131   else
 132   {
 133     io_service_.notify_fork(boost::asio::io_service::fork_parent);
 134     ...
 135   }
 136
 137 User-defined services can also be made fork-aware by overriding the
 138 `io_service::service::fork_service()` virtual function.
 139
 140 Note that any file descriptors accessible via Boost.Asio's public API (e.g. the
 141 descriptors underlying `basic_socket<>`, `posix::stream_descriptor`, etc.) are
 142 not altered during a fork. It is the program's responsibility to manage these
 143 as required.
 144
 145 [heading See Also]
 146
 147 [link boost_asio.reference.io_service.notify_fork io_service::notify_fork()],
 148 [link boost_asio.reference.io_service.fork_event io_service::fork_event],
 149 [link boost_asio.reference.io_service__service.fork_service io_service::service::fork_service()],
 150 [link boost_asio.examples.cpp03_examples.fork Fork examples].
 151
 152 [endsect]
 153
 154 [endsect]