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