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: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 18Boost.Asio provides basic support for UNIX domain sockets (also known as local 19sockets). The simplest use involves creating a pair of connected sockets. 20The following code: 21 22 local::stream_protocol::socket socket1(my_io_context); 23 local::stream_protocol::socket socket2(my_io_context); 24 local::connect_pair(socket1, socket2); 25 26will create a pair of stream-oriented sockets. To do the same for 27datagram-oriented sockets, use: 28 29 local::datagram_protocol::socket socket1(my_io_context); 30 local::datagram_protocol::socket socket2(my_io_context); 31 local::connect_pair(socket1, socket2); 32 33A UNIX domain socket server may be created by binding an acceptor to an 34endpoint, 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_context, ep); 39 local::stream_protocol::socket socket(my_io_context); 40 acceptor.accept(socket); 41 42A 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_context); 46 socket.connect(ep); 47 48Transmission of file descriptors or credentials across UNIX domain sockets is 49not directly supported within Boost.Asio, but may be achieved by accessing the 50socket's underlying descriptor using the [link 51boost_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 68UNIX domain sockets are only available at compile time if supported by the 69target 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 76Boost.Asio includes classes added to permit synchronous and asynchronous read and 77write operations to be performed on POSIX file descriptors, such as pipes, 78standard input and output, and various devices. 79 80These classes also provide limited support for regular files. This support 81assumes that the underlying read and write operations provided by the operating 82system never fail with `EAGAIN` or `EWOULDBLOCK`. (This assumption normally 83holds for buffered file I/O.) Synchronous and asynchronous read and write 84operations on file descriptors will succeed but the I/O will always be 85performed immediately. Wait operations, and operations involving 86`boost::asio::null_buffers`, are not portably supported. 87 88For example, to perform read and write operations on standard input 89and output, the following objects may be created: 90 91 posix::stream_descriptor in(my_io_context, ::dup(STDIN_FILENO)); 92 posix::stream_descriptor out(my_io_context, ::dup(STDOUT_FILENO)); 93 94These are then used as synchronous or asynchronous read and write streams. This 95means the objects can be used with any of the [link boost_asio.reference.read 96read()], [link boost_asio.reference.async_read async_read()], [link 97boost_asio.reference.write write()], [link boost_asio.reference.async_write async_write()], 98[link boost_asio.reference.read_until read_until()] or [link 99boost_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.examples.cpp03_examples.chat Chat example (C++03)], 105[link boost_asio.examples.cpp11_examples.chat Chat example (C++11)]. 106 107[heading Notes] 108 109POSIX stream descriptors are only available at compile time if supported by the 110target operating system. A program may test for the macro 111`BOOST_ASIO_HAS_POSIX_STREAM_DESCRIPTOR` to determine whether they are supported. 112 113[endsect] 114 115[section:fork Fork] 116 117Boost.Asio supports programs that utilise the `fork()` system call. Provided the 118program calls `io_context.notify_fork()` at the appropriate times, Boost.Asio will 119recreate any internal file descriptors (such as the "self-pipe trick" 120descriptor used for waking up a reactor). The notification is usually performed 121as follows: 122 123 io_context_.notify_fork(boost::asio::io_context::fork_prepare); 124 if (fork() == 0) 125 { 126 io_context_.notify_fork(boost::asio::io_context::fork_child); 127 ... 128 } 129 else 130 { 131 io_context_.notify_fork(boost::asio::io_context::fork_parent); 132 ... 133 } 134 135User-defined services can also be made fork-aware by overriding the 136`io_context::service::notify_fork()` virtual function. 137 138Note that any file descriptors accessible via Boost.Asio's public API (e.g. the 139descriptors underlying `basic_socket<>`, `posix::stream_descriptor`, etc.) are 140not altered during a fork. It is the program's responsibility to manage these 141as required. 142 143[heading See Also] 144 145[link boost_asio.reference.io_context.notify_fork io_context::notify_fork()], 146[link boost_asio.reference.io_context.fork_event io_context::fork_event], 147[link boost_asio.reference.execution_context__service.notify_fork io_context::service::notify_fork()], 148[link boost_asio.examples.cpp03_examples.fork Fork examples]. 149 150[endsect] 151 152[endsect] 153