diff options
Diffstat (limited to '3rdparty/asio/src/doc/overview/posix.qbk')
-rw-r--r-- | 3rdparty/asio/src/doc/overview/posix.qbk | 152 |
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] |