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