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