| [/ |
| / 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 (but /not/ regular files). |
| |
| 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] |