[/ / 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:posix POSIX-Specific Functionality] [link asio.overview.posix.local UNIX Domain Sockets] [link asio.overview.posix.stream_descriptor Stream-Oriented File Descriptors] [link asio.overview.posix.fork Fork] [section:local UNIX Domain Sockets] Asio provides basic support UNIX domain sockets (also known as local sockets). The simplest use involves creating a pair of connected sockets. The following code: local::stream_protocol::socket socket1(my_io_context); local::stream_protocol::socket socket2(my_io_context); local::connect_pair(socket1, socket2); will create a pair of stream-oriented sockets. To do the same for datagram-oriented sockets, use: local::datagram_protocol::socket socket1(my_io_context); local::datagram_protocol::socket socket2(my_io_context); local::connect_pair(socket1, socket2); A UNIX domain socket server may be created by binding an acceptor to an endpoint, in much the same way as one does for a TCP server: ::unlink("/tmp/foobar"); // Remove previous binding. local::stream_protocol::endpoint ep("/tmp/foobar"); local::stream_protocol::acceptor acceptor(my_io_context, ep); local::stream_protocol::socket socket(my_io_context); acceptor.accept(socket); A client that connects to this server might look like: local::stream_protocol::endpoint ep("/tmp/foobar"); local::stream_protocol::socket socket(my_io_context); socket.connect(ep); Transmission of file descriptors or credentials across UNIX domain sockets is not directly supported within Asio, but may be achieved by accessing the socket's underlying descriptor using the [link asio.reference.basic_socket.native_handle native_handle()] member function. [heading See Also] [link asio.reference.local__connect_pair local::connect_pair], [link asio.reference.local__datagram_protocol local::datagram_protocol], [link asio.reference.local__datagram_protocol.endpoint local::datagram_protocol::endpoint], [link asio.reference.local__datagram_protocol.socket local::datagram_protocol::socket], [link asio.reference.local__stream_protocol local::stream_protocol], [link asio.reference.local__stream_protocol.acceptor local::stream_protocol::acceptor], [link asio.reference.local__stream_protocol.endpoint local::stream_protocol::endpoint], [link asio.reference.local__stream_protocol.iostream local::stream_protocol::iostream], [link asio.reference.local__stream_protocol.socket local::stream_protocol::socket], [link asio.examples.cpp03_examples.unix_domain_sockets UNIX domain sockets examples]. [heading Notes] UNIX domain sockets are only available at compile time if supported by the target operating system. A program may test for the macro `ASIO_HAS_LOCAL_SOCKETS` to determine whether they are supported. [endsect] [section:stream_descriptor Stream-Oriented File Descriptors] Asio includes classes added to permit synchronous and asynchronous read and write operations to be performed on POSIX file descriptors, such as pipes, standard input and output, and various devices. These classes also provide limited support for regular files. This support assumes that the underlying read and write operations provided by the operating system never fail with `EAGAIN` or `EWOULDBLOCK`. (This assumption normally holds for buffered file I/O.) Synchronous and asynchronous read and write operations on file descriptors will succeed but the I/O will always be performed immediately. Wait operations, and operations involving `asio::null_buffers`, are not portably supported. For example, to perform read and write operations on standard input and output, the following objects may be created: posix::stream_descriptor in(my_io_context, ::dup(STDIN_FILENO)); posix::stream_descriptor out(my_io_context, ::dup(STDOUT_FILENO)); These are then used as synchronous or asynchronous read and write streams. This means the objects can be used with any of the [link asio.reference.read read()], [link asio.reference.async_read async_read()], [link asio.reference.write write()], [link asio.reference.async_write async_write()], [link asio.reference.read_until read_until()] or [link asio.reference.async_read_until async_read_until()] free functions. [heading See Also] [link asio.reference.posix__stream_descriptor posix::stream_descriptor], [link asio.examples.cpp03_examples.chat Chat example (C++03)], [link asio.examples.cpp11_examples.chat Chat example (C++11)]. [heading Notes] POSIX stream descriptors are only available at compile time if supported by the target operating system. A program may test for the macro `ASIO_HAS_POSIX_STREAM_DESCRIPTOR` to determine whether they are supported. [endsect] [section:fork Fork] Asio supports programs that utilise the `fork()` system call. Provided the program calls `io_context.notify_fork()` at the appropriate times, Asio will recreate any internal file descriptors (such as the "self-pipe trick" descriptor used for waking up a reactor). The notification is usually performed as follows: io_context_.notify_fork(asio::io_context::fork_prepare); if (fork() == 0) { io_context_.notify_fork(asio::io_context::fork_child); ... } else { io_context_.notify_fork(asio::io_context::fork_parent); ... } User-defined services can also be made fork-aware by overriding the `io_context::service::notify_fork()` virtual function. Note that any file descriptors accessible via Asio's public API (e.g. the descriptors underlying `basic_socket<>`, `posix::stream_descriptor`, etc.) are not altered during a fork. It is the program's responsibility to manage these as required. [heading See Also] [link asio.reference.io_context.notify_fork io_context::notify_fork()], [link asio.reference.io_context.fork_event io_context::fork_event], [link asio.reference.execution_context__service.notify_fork io_context::service::notify_fork()], [link asio.examples.cpp03_examples.fork Fork examples]. [endsect] [endsect]