summaryrefslogtreecommitdiffstatshomepage
path: root/3rdparty/asio/src/doc/overview/posix.qbk
diff options
context:
space:
mode:
Diffstat (limited to '3rdparty/asio/src/doc/overview/posix.qbk')
-rw-r--r--3rdparty/asio/src/doc/overview/posix.qbk152
1 files changed, 152 insertions, 0 deletions
diff --git a/3rdparty/asio/src/doc/overview/posix.qbk b/3rdparty/asio/src/doc/overview/posix.qbk
new file mode 100644
index 00000000000..19c91783e64
--- /dev/null
+++ b/3rdparty/asio/src/doc/overview/posix.qbk
@@ -0,0 +1,152 @@
+[/
+ / 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]