version 2, including all changes.
.
Rev |
Author |
# |
Line |
1 |
perry |
1 |
UNIX |
|
|
2 |
!!!UNIX |
|
|
3 |
NAME |
|
|
4 |
SYNOPSIS |
|
|
5 |
DESCRIPTION |
|
|
6 |
ADDRESS FORMAT |
|
|
7 |
SOCKET OPTIONS |
|
|
8 |
ANCILLARY MESSAGES |
|
|
9 |
VERSIONS |
|
|
10 |
NOTES |
|
|
11 |
ERRORS |
|
|
12 |
SEE ALSO |
|
|
13 |
CREDITS |
|
|
14 |
---- |
|
|
15 |
!!NAME |
|
|
16 |
|
|
|
17 |
|
|
|
18 |
unix, PF_UNIX, AF_UNIX, PF_LOCAL, AF_LOCAL - Sockets for local interprocess communication. |
|
|
19 |
!!SYNOPSIS |
|
|
20 |
|
|
|
21 |
|
|
|
22 |
__#include __ |
|
|
23 |
#include __ |
|
|
24 |
|
|
|
25 |
|
|
|
26 |
''unix_socket'' __= socket(PF_UNIX, type, 0);__'' |
|
|
27 |
error'' __= socketpair(PF_UNIX, type, 0, int |
|
|
28 |
*__''sv''__);__ |
|
|
29 |
!!DESCRIPTION |
|
|
30 |
|
|
|
31 |
|
|
|
32 |
The __PF_UNIX__ (also known as __PF_LOCAL__) socket |
|
|
33 |
family is used to communicate between processes on the same |
|
|
34 |
machine efficiently. Unix sockets can be either anonymous |
|
|
35 |
(created by socketpair(2)) or associated with a file |
|
|
36 |
of socket type. Linux also supports an abstract namespace |
|
|
37 |
which is independent of the file system. |
|
|
38 |
|
|
|
39 |
|
|
|
40 |
Valid types are __SOCK_STREAM__ for a stream oriented |
|
|
41 |
socket and __SOCK_DGRAM__ for a datagram oriented socket |
|
|
42 |
that preserves message boundaries. Unix sockets are always |
|
|
43 |
reliable and don't reorder datagrams. |
|
|
44 |
|
|
|
45 |
|
|
|
46 |
Unix sockets support passing file descriptors or process |
|
|
47 |
credentials to other processes as ancillary data to |
|
|
48 |
datagrams. |
|
|
49 |
!!ADDRESS FORMAT |
|
|
50 |
|
|
|
51 |
|
|
|
52 |
A unix address is defined as a filename in the filesystem or |
|
|
53 |
as a unique string in the abstract namespace. Sockets |
|
|
54 |
created by socketpair(2) are anonymous. For |
|
|
55 |
non-anonymous sockets the target address can be set using |
|
|
56 |
connect(2). The local address can be set using |
|
|
57 |
bind(2). When a socket is connected and it doesn't |
|
|
58 |
already have a local address a unique address in the |
|
|
59 |
abstract namespace will be generated |
|
|
60 |
automatically. |
|
|
61 |
|
|
|
62 |
|
|
|
63 |
#define UNIX_PATH_MAX 108 |
|
|
64 |
struct sockaddr_un { |
|
|
65 |
sa_family_t sun_family; /* AF_UNIX */ |
|
|
66 |
char sun_path[[UNIX_PATH_MAX]; /* pathname */ |
|
|
67 |
}; |
|
|
68 |
|
|
|
69 |
|
|
|
70 |
__sun_family__ always contains __AF_UNIX__. |
|
|
71 |
__sun_path__ contains the zero-terminated pathname of the |
|
|
72 |
socket in the file system. If __sun_path__ starts with a |
|
|
73 |
zero byte it refers to the abstract namespace maintained by |
|
|
74 |
the Unix protocol module. The socket's address in this |
|
|
75 |
namespace is given by the rest of the bytes in |
|
|
76 |
__sun_path__. Note that names in the abstract namespace |
|
|
77 |
are not zero-terminated. |
|
|
78 |
!!SOCKET OPTIONS |
|
|
79 |
|
|
|
80 |
|
|
|
81 |
For historical reasons these socket options are specified |
|
|
82 |
with a SOL_SOCKET type even though they are PF_UNIX |
|
|
83 |
specific. They can be set with setsockopt(2) and read |
|
|
84 |
with getsockopt(2) by specifying SOL_SOCKET as the |
|
|
85 |
socket family. |
|
|
86 |
|
|
|
87 |
|
|
|
88 |
__SO_PASSCRED__ enables the receiving of the credentials |
|
|
89 |
of the sending process ancillary message. When this option |
|
|
90 |
is set and the socket is not connected yet an unique name in |
|
|
91 |
the abstract namespace will be generated automatically. |
|
|
92 |
Expects an integer boolean flag. |
|
|
93 |
!!ANCILLARY MESSAGES |
|
|
94 |
|
|
|
95 |
|
|
|
96 |
For historical reasons these ancillary message type are |
|
|
97 |
specified with a SOL_SOCKET type even though they are |
|
|
98 |
PF_UNIX specific. To send them set the __cmsg_level__ |
|
|
99 |
field of the struct __cmsghdr__ to SOL_SOCKET and the |
|
|
100 |
__cmsg_type__ field to the type. For more information see |
|
|
101 |
cmsg(3). |
|
|
102 |
|
|
|
103 |
|
|
|
104 |
__SCM_RIGHTS__ |
|
|
105 |
|
|
|
106 |
|
|
|
107 |
Send or receive a set of open file descriptors from another |
|
|
108 |
process. The data portion contains a integer array of the |
|
|
109 |
file descriptors. The passed file descriptors behave as like |
|
|
110 |
they have been created with dup(2). |
|
|
111 |
|
|
|
112 |
|
|
|
113 |
__SCM_CREDENTIALS__ |
|
|
114 |
|
|
|
115 |
|
|
|
116 |
Send or receive unix credentials. This can be used for |
|
|
117 |
authentication. The credentials are passed as a __struct |
|
|
118 |
ucred__ ancillary message. |
|
|
119 |
|
|
|
120 |
|
|
|
121 |
struct ucred { |
|
|
122 |
pid_t pid; /* process id of the sending process */ |
|
|
123 |
uid_t uid; /* user id of the sending process */ |
|
|
124 |
gid_t gid; /* group id of the sending process */ |
|
|
125 |
}; |
|
|
126 |
|
|
|
127 |
|
|
|
128 |
The credentials which the sender specifies are checked by |
|
|
129 |
the kernel. A process with effective user id 0 is allowed to |
|
|
130 |
specify values that do not match his own. The sender must |
|
|
131 |
specify its own process id (unless it has |
|
|
132 |
__CAP_SYS_ADMIN__), its user id, effective user id or set |
|
|
133 |
user id (unless it has __CAP_SETUID__), and its group id, |
|
|
134 |
effective group id or set group id (unless it has |
|
|
135 |
__CAP_SETGID__). To receive a __struct ucred__ message |
|
|
136 |
the __SO_PASSCRED__ option must be enabled on the |
|
|
137 |
socket. |
|
|
138 |
!!VERSIONS |
|
|
139 |
|
|
|
140 |
|
|
|
141 |
__SCM_CREDENTIALS__ and the abstract namespace were |
|
|
142 |
introduced with Linux 2.2 and should not be used in portable |
|
|
143 |
programs. |
|
|
144 |
!!NOTES |
|
|
145 |
|
|
|
146 |
|
|
|
147 |
In the Linux implementation, sockets which are visible in |
|
|
148 |
the filesystem honour the permissions of the directory they |
|
|
149 |
are in. Their owner, group and their permissions can be |
|
|
150 |
changed. Creation of a new socket will fail if the process |
|
|
151 |
does not have write and search (execute) permission on the |
|
|
152 |
directory the socket is created in. Connecting to the socket |
|
|
153 |
object requires read/write permission. This behavior differs |
|
|
154 |
from many BSD derived systems which ignore permissions for |
|
|
155 |
Unix sockets. Portable programs should not rely on this |
|
|
156 |
feature for security. |
|
|
157 |
|
|
|
158 |
|
|
|
159 |
Binding to a socket with a filename creates a socket in the |
|
|
160 |
file system that must be deleted by the caller when it is no |
|
|
161 |
longer needed (using unlink(2)). The usual Unix |
|
|
162 |
close-behind semantics apply; the socket can be unlinked at |
|
|
163 |
any time and will be finally removed from the file system |
|
|
164 |
when the last reference to it is closed. |
|
|
165 |
|
|
|
166 |
|
|
|
167 |
To pass file descriptors or credentials you need to |
|
|
168 |
send/read at least one byte. |
|
|
169 |
!!ERRORS |
|
|
170 |
|
|
|
171 |
|
|
|
172 |
__ENOMEM__ |
|
|
173 |
|
|
|
174 |
|
|
|
175 |
Out of memory. |
|
|
176 |
|
|
|
177 |
|
|
|
178 |
__ECONNREFUSED__ |
|
|
179 |
|
|
|
180 |
|
|
|
181 |
connect(2) called with a socket object that isn't |
|
|
182 |
listening. This can happen when the remote socket does not |
|
|
183 |
exist or the filename is not a socket. |
|
|
184 |
|
|
|
185 |
|
|
|
186 |
__EINVAL__ |
|
|
187 |
|
|
|
188 |
|
|
|
189 |
Invalid argument passed. A common cause is the missing |
|
|
190 |
setting of AF_UNIX in the sun_type field of passed addresses |
|
|
191 |
or the socket being in an invalid state for the applied |
|
|
192 |
operation. |
|
|
193 |
|
|
|
194 |
|
|
|
195 |
__EOPNOTSUPP__ |
|
|
196 |
|
|
|
197 |
|
|
|
198 |
Stream operation called on non-stream oriented socket or |
|
|
199 |
tried to use the out-of-band data option. |
|
|
200 |
|
|
|
201 |
|
|
|
202 |
__EPROTONOSUPPORT__ |
|
|
203 |
|
|
|
204 |
|
|
|
205 |
Passed protocol is not PF_UNIX. |
|
|
206 |
|
|
|
207 |
|
|
|
208 |
__ESOCKTNOSUPPORT__ |
|
|
209 |
|
|
|
210 |
|
|
|
211 |
Unknown socket type. |
|
|
212 |
|
|
|
213 |
|
|
|
214 |
__EPROTOTYPE__ |
|
|
215 |
|
|
|
216 |
|
|
|
217 |
Remote socket does not match the local socket type |
|
|
218 |
(SOCK_DGRAM vs. SOCK_STREAM) |
|
|
219 |
|
|
|
220 |
|
|
|
221 |
__EADDRINUSE__ |
|
|
222 |
|
|
|
223 |
|
|
|
224 |
Selected local address is already taken or filesystem socket |
|
|
225 |
object already exists. |
|
|
226 |
|
|
|
227 |
|
|
|
228 |
__EISCONN__ |
|
|
229 |
|
|
|
230 |
|
|
|
231 |
connect(2) called on an already connected socket or a |
|
|
232 |
target address was specified on a connected |
|
|
233 |
socket. |
|
|
234 |
|
|
|
235 |
|
|
|
236 |
__ENOTCONN__ |
|
|
237 |
|
|
|
238 |
|
|
|
239 |
Socket operation needs a target address, but the socket is |
|
|
240 |
not connected. |
|
|
241 |
|
|
|
242 |
|
|
|
243 |
__ECONNRESET__ |
|
|
244 |
|
|
|
245 |
|
|
|
246 |
Remote socket was unexpectedly closed. |
|
|
247 |
|
|
|
248 |
|
|
|
249 |
__EPIPE__ |
|
|
250 |
|
|
|
251 |
|
|
|
252 |
Remote socket was closed on a stream socket. If enabled, a |
|
|
253 |
__SIGPIPE__ is sent as well. This can be avoided by |
|
|
254 |
passing the __MSG_NOSIGNAL__ flag to sendmsg(2) or |
|
|
255 |
recvmsg(2). |
|
|
256 |
|
|
|
257 |
|
|
|
258 |
__EFAULT__ |
|
|
259 |
|
|
|
260 |
|
|
|
261 |
User memory address was not valid. |
|
|
262 |
|
|
|
263 |
|
|
|
264 |
__EPERM__ |
|
|
265 |
|
|
|
266 |
|
|
|
267 |
The sender passed invalid credentials in the __struct |
|
|
268 |
ucred__. |
|
|
269 |
|
|
|
270 |
|
|
|
271 |
Other errors can be generated by the generic socket layer or |
|
|
272 |
by the filesystem while generating a filesystem socket |
|
|
273 |
object. See the appropriate manual pages for more |
|
|
274 |
information. |
|
|
275 |
!!SEE ALSO |
|
|
276 |
|
|
|
277 |
|
|
|
278 |
recvmsg(2), sendmsg(2), socket(2), |
|
|
279 |
socketpair(2), cmsg(3), |
2 |
StuartYeates |
280 |
socket(7), WhyUnix |
1 |
perry |
281 |
!!CREDITS |
|
|
282 |
|
|
|
283 |
|
|
|
284 |
This man page was written by Andi Kleen. |
|
|
285 |
---- |