]>
Commit | Line | Data |
---|---|---|
77117f4f | 1 | .\" This man page is Copyright (C) 1999 Andi Kleen <ak@muc.de>. |
2297bf0e | 2 | .\" |
00acdba1 | 3 | .\" %%%LICENSE_START(VERBATIM_ONE_PARA) |
77117f4f MK |
4 | .\" Permission is granted to distribute possibly modified copies |
5 | .\" of this page provided the header is included verbatim, | |
6 | .\" and in case of nontrivial modification author and date | |
7 | .\" of the modification is added to the header. | |
8ff7380d | 8 | .\" %%%LICENSE_END |
77117f4f MK |
9 | .\" |
10 | .\" Modified, 2003-12-02, Michael Kerrisk, <mtk.manpages@gmail.com> | |
11 | .\" Modified, 2003-09-23, Adam Langley | |
12 | .\" Modified, 2004-05-27, Michael Kerrisk, <mtk.manpages@gmail.com> | |
13 | .\" Added SOCK_SEQPACKET | |
14 | .\" 2008-05-27, mtk, Provide a clear description of the three types of | |
15 | .\" address that can appear in the sockaddr_un structure: pathname, | |
16 | .\" unnamed, and abstract. | |
17 | .\" | |
eae2dfce | 18 | .TH UNIX 7 2012-05-10 "Linux" "Linux Programmer's Manual" |
77117f4f | 19 | .SH NAME |
f68512e9 | 20 | unix \- sockets for local interprocess communication |
77117f4f MK |
21 | .SH SYNOPSIS |
22 | .B #include <sys/socket.h> | |
23 | .br | |
24 | .B #include <sys/un.h> | |
25 | ||
d4c8c97c | 26 | .IB unix_socket " = socket(AF_UNIX, type, 0);" |
77117f4f | 27 | .br |
d4c8c97c | 28 | .IB error " = socketpair(AF_UNIX, type, 0, int *" sv ");" |
77117f4f MK |
29 | .SH DESCRIPTION |
30 | The | |
d4c8c97c | 31 | .B AF_UNIX |
77117f4f | 32 | (also known as |
d4c8c97c | 33 | .BR AF_LOCAL ) |
77117f4f MK |
34 | socket family is used to communicate between processes on the same machine |
35 | efficiently. | |
4891f52a | 36 | Traditionally, UNIX domain sockets can be either unnamed, |
9ee4a2b6 | 37 | or bound to a filesystem pathname (marked as being of type socket). |
77117f4f | 38 | Linux also supports an abstract namespace which is independent of the |
9ee4a2b6 | 39 | filesystem. |
77117f4f MK |
40 | |
41 | Valid types are: | |
42 | .BR SOCK_STREAM , | |
43 | for a stream-oriented socket and | |
44 | .BR SOCK_DGRAM , | |
45 | for a datagram-oriented socket that preserves message boundaries | |
008f1ecc | 46 | (as on most UNIX implementations, UNIX domain datagram |
77117f4f MK |
47 | sockets are always reliable and don't reorder datagrams); |
48 | and (since Linux 2.6.4) | |
49 | .BR SOCK_SEQPACKET , | |
50 | for a connection-oriented socket that preserves message boundaries | |
51 | and delivers messages in the order that they were sent. | |
52 | ||
4891f52a | 53 | UNIX domain sockets support passing file descriptors or process credentials |
77117f4f | 54 | to other processes using ancillary data. |
c634028a | 55 | .SS Address format |
008f1ecc | 56 | A UNIX domain socket address is represented in the following structure: |
77117f4f MK |
57 | .in +4n |
58 | .nf | |
59 | ||
60 | #define UNIX_PATH_MAX 108 | |
61 | ||
62 | struct sockaddr_un { | |
63 | sa_family_t sun_family; /* AF_UNIX */ | |
64 | char sun_path[UNIX_PATH_MAX]; /* pathname */ | |
65 | }; | |
66 | .fi | |
67 | .in | |
68 | .PP | |
69 | .I sun_family | |
70 | always contains | |
71 | .BR AF_UNIX . | |
72 | ||
73 | Three types of address are distinguished in this structure: | |
74 | .IP * 3 | |
75 | .IR pathname : | |
1c7b2458 MK |
76 | a UNIX domain socket can be bound to a null-terminated |
77 | filesystem pathname using | |
77117f4f MK |
78 | .BR bind (2). |
79 | When the address of the socket is returned by | |
80 | .BR getsockname (2), | |
81 | .BR getpeername (2), | |
82 | and | |
83 | .BR accept (2), | |
84 | its length is | |
6cd06646 MK |
85 | |
86 | offsetof(struct sockaddr_un, sun_path) + strlen(sun_path) + 1 | |
87 | ||
77117f4f MK |
88 | and |
89 | .I sun_path | |
90 | contains the null-terminated pathname. | |
91 | .IP * | |
92 | .IR unnamed : | |
93 | A stream socket that has not been bound to a pathname using | |
94 | .BR bind (2) | |
95 | has no name. | |
96 | Likewise, the two sockets created by | |
97 | .BR socketpair (2) | |
98 | are unnamed. | |
99 | When the address of an unnamed socket is returned by | |
100 | .BR getsockname (2), | |
101 | .BR getpeername (2), | |
102 | and | |
103 | .BR accept (2), | |
104 | its length is | |
105 | .IR "sizeof(sa_family_t)" , | |
106 | and | |
107 | .I sun_path | |
108 | should not be inspected. | |
109 | .\" There is quite some variation across implementations: FreeBSD | |
110 | .\" says the length is 16 bytes, HP-UX 11 says it's zero bytes. | |
111 | .IP * | |
112 | .IR abstract : | |
113 | an abstract socket address is distinguished by the fact that | |
114 | .IR sun_path[0] | |
836830b4 | 115 | is a null byte (\(aq\\0\(aq). |
156a0e0d MK |
116 | The socket's address in this namespace is given by the additional |
117 | bytes in | |
118 | .IR sun_path | |
119 | that are covered by the specified length of the address structure. | |
77117f4f | 120 | (Null bytes in the name have no special significance.) |
9ee4a2b6 | 121 | The name has no connection with filesystem pathnames. |
77117f4f MK |
122 | When the address of an abstract socket is returned by |
123 | .BR getsockname (2), | |
124 | .BR getpeername (2), | |
125 | and | |
126 | .BR accept (2), | |
156a0e0d MK |
127 | the returned |
128 | .I addrlen | |
129 | is greater than | |
130 | .IR "sizeof(sa_family_t)" | |
131 | (i.e., greater than 2), and the name of the socket is contained in | |
132 | the first | |
133 | .IR "(addrlen \- sizeof(sa_family_t))" | |
134 | bytes of | |
135 | .IR sun_path . | |
d603cc27 | 136 | The abstract socket namespace is a nonportable Linux extension. |
c634028a | 137 | .SS Socket options |
77117f4f MK |
138 | For historical reasons these socket options are specified with a |
139 | .B SOL_SOCKET | |
140 | type even though they are | |
d4c8c97c | 141 | .B AF_UNIX |
77117f4f MK |
142 | specific. |
143 | They can be set with | |
144 | .BR setsockopt (2) | |
145 | and read with | |
146 | .BR getsockopt (2) | |
147 | by specifying | |
148 | .B SOL_SOCKET | |
149 | as the socket family. | |
150 | .TP | |
151 | .B SO_PASSCRED | |
6074c3e6 | 152 | Enables the receiving of the credentials of the sending process in an |
77117f4f MK |
153 | ancillary message. |
154 | When this option is set and the socket is not yet connected | |
155 | a unique name in the abstract namespace will be generated automatically. | |
156 | Expects an integer boolean flag. | |
c634028a | 157 | .SS Autobind feature |
0cf2caa4 | 158 | If a |
0b80cf56 | 159 | .BR bind (2) |
0cf2caa4 MK |
160 | call specifies |
161 | .I addrlen | |
162 | as | |
163 | .IR sizeof(sa_family_t) , | |
449dd4e2 | 164 | .\" i.e., sizeof(short) |
0cf2caa4 MK |
165 | or the |
166 | .BR SO_PASSCRED | |
167 | socket option was specified for a socket that was | |
168 | not explicitly bound to an address, | |
169 | then the socket is autobound to an abstract address. | |
170 | The address consists of a null byte | |
171 | followed by 5 bytes in the character set | |
172 | .IR [0-9a-f] . | |
1e4e3bad MK |
173 | Thus, there is a limit of 2^20 autobind addresses. |
174 | (From Linux 2.1.15, when the autobind feature was added, | |
175 | 8 bytes were used, and the limit was thus 2^32 autobind addresses. | |
176 | The change to 5 bytes came in Linux 2.3.15.) | |
19e19f5f | 177 | .SS Sockets API |
77117f4f | 178 | The following paragraphs describe domain-specific details and |
008f1ecc | 179 | unsupported features of the sockets API for UNIX domain sockets on Linux. |
77117f4f | 180 | |
008f1ecc | 181 | UNIX domain sockets do not support the transmission of |
77117f4f MK |
182 | out-of-band data (the |
183 | .B MSG_OOB | |
184 | flag for | |
185 | .BR send (2) | |
186 | and | |
187 | .BR recv (2)). | |
188 | ||
189 | The | |
190 | .BR send (2) | |
191 | .B MSG_MORE | |
008f1ecc | 192 | flag is not supported by UNIX domain sockets. |
77117f4f | 193 | |
77e75b90 MK |
194 | The use of |
195 | .B MSG_TRUNC | |
196 | in the | |
197 | .I flags | |
198 | argument of | |
199 | .BR recv (2) | |
008f1ecc | 200 | is not supported by UNIX domain sockets. |
77e75b90 | 201 | |
77117f4f MK |
202 | The |
203 | .B SO_SNDBUF | |
008f1ecc | 204 | socket option does have an effect for UNIX domain sockets, but the |
77117f4f MK |
205 | .B SO_RCVBUF |
206 | option does not. | |
207 | For datagram sockets, the | |
208 | .B SO_SNDBUF | |
209 | value imposes an upper limit on the size of outgoing datagrams. | |
210 | This limit is calculated as the doubled (see | |
211 | .BR socket (7)) | |
212 | option value less 32 bytes used for overhead. | |
c634028a | 213 | .SS Ancillary messages |
77117f4f MK |
214 | Ancillary data is sent and received using |
215 | .BR sendmsg (2) | |
216 | and | |
217 | .BR recvmsg (2). | |
218 | For historical reasons the ancillary message types listed below | |
219 | are specified with a | |
220 | .B SOL_SOCKET | |
221 | type even though they are | |
d4c8c97c | 222 | .B AF_UNIX |
77117f4f MK |
223 | specific. |
224 | To send them set the | |
225 | .I cmsg_level | |
226 | field of the struct | |
227 | .I cmsghdr | |
228 | to | |
229 | .B SOL_SOCKET | |
230 | and the | |
231 | .I cmsg_type | |
232 | field to the type. | |
233 | For more information see | |
234 | .BR cmsg (3). | |
235 | .TP | |
236 | .B SCM_RIGHTS | |
237 | Send or receive a set of open file descriptors from another process. | |
238 | The data portion contains an integer array of the file descriptors. | |
239 | The passed file descriptors behave as though they have been created with | |
240 | .BR dup (2). | |
241 | .TP | |
242 | .B SCM_CREDENTIALS | |
008f1ecc | 243 | Send or receive UNIX credentials. |
77117f4f MK |
244 | This can be used for authentication. |
245 | The credentials are passed as a | |
246 | .I struct ucred | |
247 | ancillary message. | |
b1587ca8 MK |
248 | Thus structure is defined in |
249 | .I <sys/socket.h> | |
250 | as follows: | |
77117f4f MK |
251 | |
252 | .in +4n | |
253 | .nf | |
254 | struct ucred { | |
255 | pid_t pid; /* process ID of the sending process */ | |
256 | uid_t uid; /* user ID of the sending process */ | |
257 | gid_t gid; /* group ID of the sending process */ | |
258 | }; | |
259 | .fi | |
260 | .in | |
261 | ||
b1587ca8 | 262 | Since glibc 2.8, the |
1bc510f5 | 263 | .B _GNU_SOURCE |
e417acb0 MK |
264 | feature test macro must be defined (before including |
265 | .I any | |
266 | header files) in order to obtain the definition | |
b1587ca8 MK |
267 | of this structure. |
268 | ||
77117f4f MK |
269 | The credentials which the sender specifies are checked by the kernel. |
270 | A process with effective user ID 0 is allowed to specify values that do | |
271 | not match its own. | |
272 | The sender must specify its own process ID (unless it has the capability | |
273 | .BR CAP_SYS_ADMIN ), | |
274 | its user ID, effective user ID, or saved set-user-ID (unless it has | |
275 | .BR CAP_SETUID ), | |
276 | and its group ID, effective group ID, or saved set-group-ID | |
277 | (unless it has | |
278 | .BR CAP_SETGID ). | |
279 | To receive a | |
280 | .I struct ucred | |
281 | message the | |
282 | .B SO_PASSCRED | |
283 | option must be enabled on the socket. | |
fbea0f81 MK |
284 | .SS Ioctls |
285 | The following | |
286 | .BR ioctl (2) | |
287 | calls return information in | |
288 | .IR value . | |
289 | The correct syntax is: | |
290 | .PP | |
291 | .RS | |
292 | .nf | |
293 | .BI int " value"; | |
f0d77d97 | 294 | .IB error " = ioctl(" unix_socket ", " ioctl_type ", &" value ");" |
fbea0f81 MK |
295 | .fi |
296 | .RE | |
297 | .PP | |
298 | .I ioctl_type | |
299 | can be: | |
300 | .TP | |
301 | .B SIOCINQ | |
302 | Returns the amount of queued unread data in the receive buffer. | |
303 | The socket must not be in LISTEN state, otherwise an error | |
304 | .RB ( EINVAL ) | |
305 | is returned. | |
306 | .B SIOCINQ | |
307 | is defined in | |
308 | .IR <linux/sockios.h> . | |
309 | .\" FIXME http://sources.redhat.com/bugzilla/show_bug.cgi?id=12002, | |
310 | .\" filed 2010-09-10, may cause SIOCINQ to be defined in glibc headers | |
311 | Alternatively, | |
312 | you can use the synonymous | |
313 | .BR FIONREAD , | |
314 | defined in | |
315 | .IR <sys/ioctl.h> . | |
7aed61d9 | 316 | .\" SIOCOUTQ also has an effect for UNIX domain sockets, but not |
fbea0f81 MK |
317 | .\" quite what userland might expect. It seems to return the number |
318 | .\" of bytes allocated for buffers containing pending output. | |
319 | .\" That number is normally larger than the number of bytes of pending | |
320 | .\" output. Since this info is, from userland's point of view, imprecise, | |
321 | .\" and it may well change, probably best not to document this now. | |
77117f4f MK |
322 | .SH ERRORS |
323 | .TP | |
324 | .B EADDRINUSE | |
9ee4a2b6 | 325 | The specified local address is already in use or the filesystem socket |
77117f4f MK |
326 | object already exists. |
327 | .TP | |
328 | .B ECONNREFUSED | |
1fe284ab | 329 | The remote address specified by |
77117f4f | 330 | .BR connect (2) |
1fe284ab | 331 | was not a listening socket. |
d1c9ea80 | 332 | This error can also occur if the target filename is not a socket. |
77117f4f MK |
333 | .TP |
334 | .B ECONNRESET | |
335 | Remote socket was unexpectedly closed. | |
336 | .TP | |
337 | .B EFAULT | |
338 | User memory address was not valid. | |
339 | .TP | |
340 | .B EINVAL | |
341 | Invalid argument passed. | |
1fe284ab | 342 | A common cause is that the value |
40656bc7 | 343 | .B AF_UNIX |
1fe284ab | 344 | was not specified in the |
77117f4f | 345 | .I sun_type |
1fe284ab | 346 | field of passed addresses, or the socket was in an |
77117f4f MK |
347 | invalid state for the applied operation. |
348 | .TP | |
349 | .B EISCONN | |
350 | .BR connect (2) | |
351 | called on an already connected socket or a target address was | |
352 | specified on a connected socket. | |
353 | .TP | |
ec55a2b6 MK |
354 | .B ENOENT |
355 | The pathname in the remote address specified to | |
9470f355 | 356 | .BR connect (2) |
ec55a2b6 MK |
357 | did not exist. |
358 | .TP | |
77117f4f MK |
359 | .B ENOMEM |
360 | Out of memory. | |
361 | .TP | |
362 | .B ENOTCONN | |
363 | Socket operation needs a target address, but the socket is not connected. | |
364 | .TP | |
365 | .B EOPNOTSUPP | |
366 | Stream operation called on non-stream oriented socket or tried to | |
367 | use the out-of-band data option. | |
368 | .TP | |
369 | .B EPERM | |
370 | The sender passed invalid credentials in the | |
371 | .IR "struct ucred" . | |
372 | .TP | |
373 | .B EPIPE | |
374 | Remote socket was closed on a stream socket. | |
375 | If enabled, a | |
376 | .B SIGPIPE | |
377 | is sent as well. | |
378 | This can be avoided by passing the | |
379 | .B MSG_NOSIGNAL | |
380 | flag to | |
381 | .BR sendmsg (2) | |
382 | or | |
383 | .BR recvmsg (2). | |
384 | .TP | |
385 | .B EPROTONOSUPPORT | |
cd0221ea MK |
386 | Passed protocol is not |
387 | .BR AF_UNIX . | |
77117f4f MK |
388 | .TP |
389 | .B EPROTOTYPE | |
390 | Remote socket does not match the local socket type | |
391 | .RB ( SOCK_DGRAM | |
d1c9ea80 | 392 | versus |
77117f4f MK |
393 | .BR SOCK_STREAM ) |
394 | .TP | |
395 | .B ESOCKTNOSUPPORT | |
396 | Unknown socket type. | |
397 | .PP | |
398 | Other errors can be generated by the generic socket layer or | |
9ee4a2b6 | 399 | by the filesystem while generating a filesystem socket object. |
77117f4f MK |
400 | See the appropriate manual pages for more information. |
401 | .SH VERSIONS | |
402 | .B SCM_CREDENTIALS | |
403 | and the abstract namespace were introduced with Linux 2.2 and should not | |
404 | be used in portable programs. | |
405 | (Some BSD-derived systems also support credential passing, | |
406 | but the implementation details differ.) | |
407 | .SH NOTES | |
408 | In the Linux implementation, sockets which are visible in the | |
9ee4a2b6 | 409 | filesystem honor the permissions of the directory they are in. |
77117f4f MK |
410 | Their owner, group and their permissions can be changed. |
411 | Creation of a new socket will fail if the process does not have write and | |
412 | search (execute) permission on the directory the socket is created in. | |
413 | Connecting to the socket object requires read/write permission. | |
414 | This behavior differs from many BSD-derived systems which | |
4891f52a | 415 | ignore permissions for UNIX domain sockets. |
77117f4f MK |
416 | Portable programs should not rely on |
417 | this feature for security. | |
418 | ||
419 | Binding to a socket with a filename creates a socket | |
9ee4a2b6 | 420 | in the filesystem that must be deleted by the caller when it is no |
77117f4f MK |
421 | longer needed (using |
422 | .BR unlink (2)). | |
008f1ecc | 423 | The usual UNIX close-behind semantics apply; the socket can be unlinked |
9ee4a2b6 | 424 | at any time and will be finally removed from the filesystem when the last |
77117f4f MK |
425 | reference to it is closed. |
426 | ||
427 | To pass file descriptors or credentials over a | |
428 | .BR SOCK_STREAM , | |
429 | you need | |
24b74457 | 430 | to send or receive at least one byte of nonancillary data in the same |
77117f4f MK |
431 | .BR sendmsg (2) |
432 | or | |
433 | .BR recvmsg (2) | |
434 | call. | |
435 | ||
008f1ecc | 436 | UNIX domain stream sockets do not support the notion of out-of-band data. |
77117f4f MK |
437 | .SH EXAMPLE |
438 | See | |
439 | .BR bind (2). | |
c751683c MK |
440 | |
441 | For an example of the use of | |
442 | .BR SCM_RIGHTS | |
443 | see | |
444 | .BR cmsg (3). | |
47297adb | 445 | .SH SEE ALSO |
77117f4f MK |
446 | .BR recvmsg (2), |
447 | .BR sendmsg (2), | |
448 | .BR socket (2), | |
449 | .BR socketpair (2), | |
450 | .BR cmsg (3), | |
451 | .BR capabilities (7), | |
452 | .BR credentials (7), | |
453 | .BR socket (7) |