]>
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 | .\" | |
b1587ca8 | 15 | .TH UNIX 7 2008-09-01 "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. | |
130 | The abstract socket namespace is a non-portable Linux extension. | |
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. | |
151 | .SS (Un)supported Features | |
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 | ||
168 | The | |
169 | .B SO_SNDBUF | |
170 | socket option does have an effect for Unix domain sockets, but the | |
171 | .B SO_RCVBUF | |
172 | option does not. | |
173 | For datagram sockets, the | |
174 | .B SO_SNDBUF | |
175 | value imposes an upper limit on the size of outgoing datagrams. | |
176 | This limit is calculated as the doubled (see | |
177 | .BR socket (7)) | |
178 | option value less 32 bytes used for overhead. | |
179 | .SS Ancillary Messages | |
180 | Ancillary data is sent and received using | |
181 | .BR sendmsg (2) | |
182 | and | |
183 | .BR recvmsg (2). | |
184 | For historical reasons the ancillary message types listed below | |
185 | are specified with a | |
186 | .B SOL_SOCKET | |
187 | type even though they are | |
d4c8c97c | 188 | .B AF_UNIX |
77117f4f MK |
189 | specific. |
190 | To send them set the | |
191 | .I cmsg_level | |
192 | field of the struct | |
193 | .I cmsghdr | |
194 | to | |
195 | .B SOL_SOCKET | |
196 | and the | |
197 | .I cmsg_type | |
198 | field to the type. | |
199 | For more information see | |
200 | .BR cmsg (3). | |
201 | .TP | |
202 | .B SCM_RIGHTS | |
203 | Send or receive a set of open file descriptors from another process. | |
204 | The data portion contains an integer array of the file descriptors. | |
205 | The passed file descriptors behave as though they have been created with | |
206 | .BR dup (2). | |
207 | .TP | |
208 | .B SCM_CREDENTIALS | |
209 | Send or receive Unix credentials. | |
210 | This can be used for authentication. | |
211 | The credentials are passed as a | |
212 | .I struct ucred | |
213 | ancillary message. | |
b1587ca8 MK |
214 | Thus structure is defined in |
215 | .I <sys/socket.h> | |
216 | as follows: | |
77117f4f MK |
217 | |
218 | .in +4n | |
219 | .nf | |
220 | struct ucred { | |
221 | pid_t pid; /* process ID of the sending process */ | |
222 | uid_t uid; /* user ID of the sending process */ | |
223 | gid_t gid; /* group ID of the sending process */ | |
224 | }; | |
225 | .fi | |
226 | .in | |
227 | ||
b1587ca8 | 228 | Since glibc 2.8, the |
1bc510f5 | 229 | .B _GNU_SOURCE |
b1587ca8 MK |
230 | feature test macro must be defined in order to obtain the definition |
231 | of this structure. | |
232 | ||
77117f4f MK |
233 | The credentials which the sender specifies are checked by the kernel. |
234 | A process with effective user ID 0 is allowed to specify values that do | |
235 | not match its own. | |
236 | The sender must specify its own process ID (unless it has the capability | |
237 | .BR CAP_SYS_ADMIN ), | |
238 | its user ID, effective user ID, or saved set-user-ID (unless it has | |
239 | .BR CAP_SETUID ), | |
240 | and its group ID, effective group ID, or saved set-group-ID | |
241 | (unless it has | |
242 | .BR CAP_SETGID ). | |
243 | To receive a | |
244 | .I struct ucred | |
245 | message the | |
246 | .B SO_PASSCRED | |
247 | option must be enabled on the socket. | |
248 | .SH ERRORS | |
249 | .TP | |
250 | .B EADDRINUSE | |
251 | Selected local address is already taken or file system socket | |
252 | object already exists. | |
253 | .TP | |
254 | .B ECONNREFUSED | |
255 | .BR connect (2) | |
256 | called with a socket object that isn't listening. | |
257 | This can happen when | |
258 | the remote socket does not exist or the filename is not a socket. | |
259 | .TP | |
260 | .B ECONNRESET | |
261 | Remote socket was unexpectedly closed. | |
262 | .TP | |
263 | .B EFAULT | |
264 | User memory address was not valid. | |
265 | .TP | |
266 | .B EINVAL | |
267 | Invalid argument passed. | |
268 | A common cause is the missing setting of AF_UNIX | |
269 | in the | |
270 | .I sun_type | |
271 | field of passed addresses or the socket being in an | |
272 | invalid state for the applied operation. | |
273 | .TP | |
274 | .B EISCONN | |
275 | .BR connect (2) | |
276 | called on an already connected socket or a target address was | |
277 | specified on a connected socket. | |
278 | .TP | |
279 | .B ENOMEM | |
280 | Out of memory. | |
281 | .TP | |
282 | .B ENOTCONN | |
283 | Socket operation needs a target address, but the socket is not connected. | |
284 | .TP | |
285 | .B EOPNOTSUPP | |
286 | Stream operation called on non-stream oriented socket or tried to | |
287 | use the out-of-band data option. | |
288 | .TP | |
289 | .B EPERM | |
290 | The sender passed invalid credentials in the | |
291 | .IR "struct ucred" . | |
292 | .TP | |
293 | .B EPIPE | |
294 | Remote socket was closed on a stream socket. | |
295 | If enabled, a | |
296 | .B SIGPIPE | |
297 | is sent as well. | |
298 | This can be avoided by passing the | |
299 | .B MSG_NOSIGNAL | |
300 | flag to | |
301 | .BR sendmsg (2) | |
302 | or | |
303 | .BR recvmsg (2). | |
304 | .TP | |
305 | .B EPROTONOSUPPORT | |
d4c8c97c | 306 | Passed protocol is not AF_UNIX. |
77117f4f MK |
307 | .TP |
308 | .B EPROTOTYPE | |
309 | Remote socket does not match the local socket type | |
310 | .RB ( SOCK_DGRAM | |
311 | vs. | |
312 | .BR SOCK_STREAM ) | |
313 | .TP | |
314 | .B ESOCKTNOSUPPORT | |
315 | Unknown socket type. | |
316 | .PP | |
317 | Other errors can be generated by the generic socket layer or | |
318 | by the file system while generating a file system socket object. | |
319 | See the appropriate manual pages for more information. | |
320 | .SH VERSIONS | |
321 | .B SCM_CREDENTIALS | |
322 | and the abstract namespace were introduced with Linux 2.2 and should not | |
323 | be used in portable programs. | |
324 | (Some BSD-derived systems also support credential passing, | |
325 | but the implementation details differ.) | |
326 | .SH NOTES | |
327 | In the Linux implementation, sockets which are visible in the | |
328 | file system honor the permissions of the directory they are in. | |
329 | Their owner, group and their permissions can be changed. | |
330 | Creation of a new socket will fail if the process does not have write and | |
331 | search (execute) permission on the directory the socket is created in. | |
332 | Connecting to the socket object requires read/write permission. | |
333 | This behavior differs from many BSD-derived systems which | |
334 | ignore permissions for Unix sockets. | |
335 | Portable programs should not rely on | |
336 | this feature for security. | |
337 | ||
338 | Binding to a socket with a filename creates a socket | |
339 | in the file system that must be deleted by the caller when it is no | |
340 | longer needed (using | |
341 | .BR unlink (2)). | |
342 | The usual Unix close-behind semantics apply; the socket can be unlinked | |
343 | at any time and will be finally removed from the file system when the last | |
344 | reference to it is closed. | |
345 | ||
346 | To pass file descriptors or credentials over a | |
347 | .BR SOCK_STREAM , | |
348 | you need | |
349 | to send or receive at least one byte of non-ancillary data in the same | |
350 | .BR sendmsg (2) | |
351 | or | |
352 | .BR recvmsg (2) | |
353 | call. | |
354 | ||
355 | Unix domain stream sockets do not support the notion of out-of-band data. | |
356 | .SH EXAMPLE | |
357 | See | |
358 | .BR bind (2). | |
359 | .SH "SEE ALSO" | |
360 | .BR recvmsg (2), | |
361 | .BR sendmsg (2), | |
362 | .BR socket (2), | |
363 | .BR socketpair (2), | |
364 | .BR cmsg (3), | |
365 | .BR capabilities (7), | |
366 | .BR credentials (7), | |
367 | .BR socket (7) |