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