]>
Commit | Line | Data |
---|---|---|
7c4ddad1 AC |
1 | .\" SPDX-License-Identifier: Linux-man-pages-1-para |
2 | .\" | |
15545eb6 HS |
3 | .\" This man page is Copyright (C) 1999 Andi Kleen <ak@muc.de>, |
4 | .\" Copyright (C) 2008-2014, Michael Kerrisk <mtk.manpages@gmail.com>, | |
5 | .\" and Copyright (C) 2016, Heinrich Schuchardt <xypron.glpk@gmx.de> | |
2297bf0e | 6 | .\" |
77117f4f MK |
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 | .\" | |
ab47278f | 15 | .TH UNIX 7 (date) "Linux man-pages (unreleased)" |
77117f4f | 16 | .SH NAME |
f68512e9 | 17 | unix \- sockets for local interprocess communication |
77117f4f | 18 | .SH SYNOPSIS |
c7db92b9 | 19 | .nf |
77117f4f | 20 | .B #include <sys/socket.h> |
77117f4f | 21 | .B #include <sys/un.h> |
c6d039a3 | 22 | .P |
d4c8c97c | 23 | .IB unix_socket " = socket(AF_UNIX, type, 0);" |
d4c8c97c | 24 | .IB error " = socketpair(AF_UNIX, type, 0, int *" sv ");" |
c7db92b9 | 25 | .fi |
77117f4f MK |
26 | .SH DESCRIPTION |
27 | The | |
d4c8c97c | 28 | .B AF_UNIX |
77117f4f | 29 | (also known as |
d4c8c97c | 30 | .BR AF_LOCAL ) |
77117f4f MK |
31 | socket family is used to communicate between processes on the same machine |
32 | efficiently. | |
4891f52a | 33 | Traditionally, UNIX domain sockets can be either unnamed, |
9ee4a2b6 | 34 | or bound to a filesystem pathname (marked as being of type socket). |
77117f4f | 35 | Linux also supports an abstract namespace which is independent of the |
9ee4a2b6 | 36 | filesystem. |
c6d039a3 | 37 | .P |
d02879f7 | 38 | Valid socket types in the UNIX domain are: |
77117f4f | 39 | .BR SOCK_STREAM , |
d02879f7 | 40 | for a stream-oriented socket; |
77117f4f MK |
41 | .BR SOCK_DGRAM , |
42 | for a datagram-oriented socket that preserves message boundaries | |
008f1ecc | 43 | (as on most UNIX implementations, UNIX domain datagram |
77117f4f MK |
44 | sockets are always reliable and don't reorder datagrams); |
45 | and (since Linux 2.6.4) | |
46 | .BR SOCK_SEQPACKET , | |
0d7e8d59 MK |
47 | for a sequenced-packet socket that is connection-oriented, |
48 | preserves message boundaries, | |
77117f4f | 49 | and delivers messages in the order that they were sent. |
c6d039a3 | 50 | .P |
4891f52a | 51 | UNIX domain sockets support passing file descriptors or process credentials |
77117f4f | 52 | to other processes using ancillary data. |
c634028a | 53 | .SS Address format |
008f1ecc | 54 | A UNIX domain socket address is represented in the following structure: |
c6d039a3 | 55 | .P |
77117f4f | 56 | .in +4n |
e646a1ba | 57 | .EX |
63bc262c | 58 | .\" #define UNIX_PATH_MAX 108 |
5ffdc2fd | 59 | .\" |
77117f4f MK |
60 | struct sockaddr_un { |
61 | sa_family_t sun_family; /* AF_UNIX */ | |
b65f4c69 | 62 | char sun_path[108]; /* Pathname */ |
77117f4f | 63 | }; |
b8302363 | 64 | .EE |
77117f4f | 65 | .in |
c6d039a3 | 66 | .P |
d02879f7 | 67 | The |
77117f4f | 68 | .I sun_family |
d02879f7 | 69 | field always contains |
77117f4f | 70 | .BR AF_UNIX . |
05bf3361 | 71 | On Linux, |
840aa3c7 | 72 | .I sun_path |
7903a735 | 73 | is 108 bytes in size; see also BUGS, below. |
c6d039a3 | 74 | .P |
3aa341fc | 75 | Various system calls (for example, |
d02879f7 MK |
76 | .BR bind (2), |
77 | .BR connect (2), | |
78 | and | |
79 | .BR sendto (2)) | |
80 | take a | |
b8017cf5 | 81 | .I sockaddr_un |
d02879f7 MK |
82 | argument as input. |
83 | Some other system calls (for example, | |
84 | .BR getsockname (2), | |
85 | .BR getpeername (2), | |
86 | .BR recvfrom (2), | |
87 | and | |
88 | .BR accept (2)) | |
89 | return an argument of this type. | |
c6d039a3 | 90 | .P |
d02879f7 MK |
91 | Three types of address are distinguished in the |
92 | .I sockaddr_un | |
93 | structure: | |
4279e42d AC |
94 | .TP |
95 | pathname | |
1c7b2458 MK |
96 | a UNIX domain socket can be bound to a null-terminated |
97 | filesystem pathname using | |
77117f4f | 98 | .BR bind (2). |
d02879f7 MK |
99 | When the address of a pathname socket is returned |
100 | (by one of the system calls noted above), | |
77117f4f | 101 | its length is |
5711c04f | 102 | .IP |
1ae6b2c7 AC |
103 | .in +4n |
104 | .EX | |
105 | offsetof(struct sockaddr_un, sun_path) + strlen(sun_path) + 1 | |
106 | .EE | |
107 | .in | |
5711c04f | 108 | .IP |
77117f4f MK |
109 | and |
110 | .I sun_path | |
111 | contains the null-terminated pathname. | |
d02879f7 MK |
112 | (On Linux, the above |
113 | .BR offsetof () | |
114 | expression equates to the same value as | |
115 | .IR sizeof(sa_family_t) , | |
116 | but some other implementations include other fields before | |
117 | .IR sun_path , | |
118 | so the | |
119 | .BR offsetof () | |
120 | expression more portably describes the size of the address structure.) | |
121 | .IP | |
122 | For further details of pathname sockets, see below. | |
4279e42d AC |
123 | .TP |
124 | unnamed | |
77117f4f MK |
125 | A stream socket that has not been bound to a pathname using |
126 | .BR bind (2) | |
127 | has no name. | |
128 | Likewise, the two sockets created by | |
129 | .BR socketpair (2) | |
130 | are unnamed. | |
d02879f7 | 131 | When the address of an unnamed socket is returned, |
77117f4f MK |
132 | its length is |
133 | .IR "sizeof(sa_family_t)" , | |
134 | and | |
135 | .I sun_path | |
136 | should not be inspected. | |
137 | .\" There is quite some variation across implementations: FreeBSD | |
138 | .\" says the length is 16 bytes, HP-UX 11 says it's zero bytes. | |
4279e42d AC |
139 | .TP |
140 | abstract | |
d02879f7 MK |
141 | an abstract socket address is distinguished (from a pathname socket) |
142 | by the fact that | |
1ae6b2c7 | 143 | .I sun_path[0] |
b957f81f | 144 | is a null byte (\[aq]\e0\[aq]). |
156a0e0d MK |
145 | The socket's address in this namespace is given by the additional |
146 | bytes in | |
1ae6b2c7 | 147 | .I sun_path |
156a0e0d | 148 | that are covered by the specified length of the address structure. |
77117f4f | 149 | (Null bytes in the name have no special significance.) |
9ee4a2b6 | 150 | The name has no connection with filesystem pathnames. |
d02879f7 | 151 | When the address of an abstract socket is returned, |
156a0e0d MK |
152 | the returned |
153 | .I addrlen | |
154 | is greater than | |
1ae6b2c7 | 155 | .I sizeof(sa_family_t) |
156a0e0d MK |
156 | (i.e., greater than 2), and the name of the socket is contained in |
157 | the first | |
1ae6b2c7 | 158 | .I (addrlen \- sizeof(sa_family_t)) |
156a0e0d MK |
159 | bytes of |
160 | .IR sun_path . | |
d02879f7 MK |
161 | .SS Pathname sockets |
162 | When binding a socket to a pathname, a few rules should be observed | |
163 | for maximum portability and ease of coding: | |
cdede5cd | 164 | .IP \[bu] 3 |
d02879f7 MK |
165 | The pathname in |
166 | .I sun_path | |
167 | should be null-terminated. | |
cdede5cd | 168 | .IP \[bu] |
d02879f7 MK |
169 | The length of the pathname, including the terminating null byte, |
170 | should not exceed the size of | |
171 | .IR sun_path . | |
cdede5cd | 172 | .IP \[bu] |
d02879f7 MK |
173 | The |
174 | .I addrlen | |
175 | argument that describes the enclosing | |
176 | .I sockaddr_un | |
177 | structure should have a value of at least: | |
5711c04f | 178 | .IP |
1ae6b2c7 AC |
179 | .in +4n |
180 | .EX | |
181 | offsetof(struct sockaddr_un, sun_path)+strlen(addr.sun_path)+1 | |
182 | .EE | |
183 | .in | |
d02879f7 | 184 | .IP |
b8017cf5 | 185 | or, more simply, |
d02879f7 MK |
186 | .I addrlen |
187 | can be specified as | |
188 | .IR "sizeof(struct sockaddr_un)" . | |
c6d039a3 | 189 | .P |
d02879f7 MK |
190 | There is some variation in how implementations handle UNIX domain |
191 | socket addresses that do not follow the above rules. | |
192 | For example, some (but not all) implementations | |
193 | .\" Linux does this, including for the case where the supplied path | |
194 | .\" is 108 bytes | |
195 | append a null terminator if none is present in the supplied | |
196 | .IR sun_path . | |
c6d039a3 | 197 | .P |
d02879f7 MK |
198 | When coding portable applications, |
199 | keep in mind that some implementations | |
200 | .\" HP-UX | |
201 | have | |
202 | .I sun_path | |
203 | as short as 92 bytes. | |
204 | .\" Modern BSDs generally have 104, Tru64 and AIX have 104, | |
205 | .\" Solaris and Irix have 108 | |
c6d039a3 | 206 | .P |
d02879f7 MK |
207 | Various system calls |
208 | .RB ( accept (2), | |
209 | .BR recvfrom (2), | |
210 | .BR getsockname (2), | |
211 | .BR getpeername (2)) | |
212 | return socket address structures. | |
213 | When applied to UNIX domain sockets, the value-result | |
214 | .I addrlen | |
215 | argument supplied to the call should be initialized as above. | |
216 | Upon return, the argument is set to indicate the | |
217 | .I actual | |
218 | size of the address structure. | |
219 | The caller should check the value returned in this argument: | |
220 | if the output value exceeds the input value, | |
221 | then there is no guarantee that a null terminator is present in | |
222 | .IR sun_path . | |
223 | (See BUGS.) | |
9f213833 MK |
224 | .\" |
225 | .SS Pathname socket ownership and permissions | |
226 | In the Linux implementation, | |
227 | pathname sockets honor the permissions of the directory they are in. | |
a23d8efa | 228 | Creation of a new socket fails if the process does not have write and |
9f213833 | 229 | search (execute) permission on the directory in which the socket is created. |
c6d039a3 | 230 | .P |
9f213833 MK |
231 | On Linux, |
232 | connecting to a stream socket object requires write permission on that socket; | |
233 | sending a datagram to a datagram socket likewise | |
234 | requires write permission on that socket. | |
235 | POSIX does not make any statement about the effect of the permissions | |
7f98a239 | 236 | on a socket file, and on some systems (e.g., older BSDs), |
9f213833 MK |
237 | the socket permissions are ignored. |
238 | Portable programs should not rely on | |
239 | this feature for security. | |
c6d039a3 | 240 | .P |
9f213833 MK |
241 | When creating a new socket, the owner and group of the socket file |
242 | are set according to the usual rules. | |
243 | The socket file has all permissions enabled, | |
244 | other than those that are turned off by the process | |
245 | .BR umask (2). | |
c6d039a3 | 246 | .P |
9f213833 MK |
247 | The owner, group, and permissions of a pathname socket can be changed (using |
248 | .BR chown (2) | |
249 | and | |
250 | .BR chmod (2)). | |
251 | .\" However, fchown() and fchmod() do not seem to have an effect | |
252 | .\" | |
d1875c13 | 253 | .SS Abstract sockets |
44cca454 MK |
254 | Socket permissions have no meaning for abstract sockets: |
255 | the process | |
256 | .BR umask (2) | |
257 | has no effect when binding an abstract socket, | |
258 | and changing the ownership and permissions of the object (via | |
259 | .BR fchown (2) | |
260 | and | |
261 | .BR fchmod (2)) | |
262 | has no effect on the accessibility of the socket. | |
c6d039a3 | 263 | .P |
d1875c13 MK |
264 | Abstract sockets automatically disappear when all open references |
265 | to the socket are closed. | |
c6d039a3 | 266 | .P |
d1875c13 MK |
267 | The abstract socket namespace is a nonportable Linux extension. |
268 | .\" | |
c634028a | 269 | .SS Socket options |
464b254b | 270 | For historical reasons, these socket options are specified with a |
77117f4f MK |
271 | .B SOL_SOCKET |
272 | type even though they are | |
d4c8c97c | 273 | .B AF_UNIX |
77117f4f MK |
274 | specific. |
275 | They can be set with | |
276 | .BR setsockopt (2) | |
277 | and read with | |
278 | .BR getsockopt (2) | |
279 | by specifying | |
280 | .B SOL_SOCKET | |
281 | as the socket family. | |
282 | .TP | |
283 | .B SO_PASSCRED | |
928c3e7c | 284 | Enabling this socket option causes receipt of the credentials of |
421d34c6 MK |
285 | the sending process in an |
286 | .B SCM_CREDENTIALS ancillary | |
928c3e7c | 287 | message in each subsequently received message. |
421d34c6 MK |
288 | The returned credentials are those specified by the sender using |
289 | .BR SCM_CREDENTIALS , | |
290 | or a default that includes the sender's PID, real user ID, and real group ID, | |
291 | if the sender did not specify | |
292 | .B SCM_CREDENTIALS | |
293 | ancillary data. | |
c02ed554 MK |
294 | .IP |
295 | When this option is set and the socket is not yet connected, | |
77117f4f | 296 | a unique name in the abstract namespace will be generated automatically. |
744c8fa8 MK |
297 | .IP |
298 | The value given as an argument to | |
299 | .BR setsockopt (2) | |
300 | and returned as the result of | |
301 | .BR getsockopt (2) | |
302 | is an integer boolean flag. | |
366a9bff MK |
303 | .TP |
304 | .B SO_PASSSEC | |
ffad6a01 MK |
305 | Enables receiving of the SELinux security label of the peer socket |
306 | in an ancillary message of type | |
1ae6b2c7 | 307 | .B SCM_SECURITY |
ffad6a01 | 308 | (see below). |
744c8fa8 MK |
309 | .IP |
310 | The value given as an argument to | |
311 | .BR setsockopt (2) | |
312 | and returned as the result of | |
313 | .BR getsockopt (2) | |
314 | is an integer boolean flag. | |
315 | .IP | |
316 | The | |
317 | .B SO_PASSSEC | |
318 | option is supported for UNIX domain datagram sockets | |
366a9bff MK |
319 | .\" commit 877ce7c1b3afd69a9b1caeb1b9964c992641f52a |
320 | since Linux 2.6.18; | |
321 | support for UNIX domain stream sockets was added | |
322 | .\" commit 37a9a8df8ce9de6ea73349c9ac8bdf6ba4ec4f70 | |
323 | in Linux 4.2. | |
ffab8460 | 324 | .TP |
1ae6b2c7 | 325 | .B SO_PEEK_OFF |
ffab8460 MK |
326 | See |
327 | .BR socket (7). | |
94950b9a MK |
328 | .TP |
329 | .B SO_PEERCRED | |
3d3cddde MK |
330 | This read-only socket option returns the |
331 | credentials of the peer process connected to this socket. | |
94950b9a MK |
332 | The returned credentials are those that were in effect at the time |
333 | of the call to | |
b34c2340 AT |
334 | .BR connect (2), |
335 | .BR listen (2), | |
94950b9a MK |
336 | or |
337 | .BR socketpair (2). | |
3d3cddde MK |
338 | .IP |
339 | The argument to | |
340 | .BR getsockopt (2) | |
341 | is a pointer to a | |
94950b9a MK |
342 | .I ucred |
343 | structure; define the | |
344 | .B _GNU_SOURCE | |
345 | feature test macro to obtain the definition of that structure from | |
346 | .IR <sys/socket.h> . | |
3d3cddde MK |
347 | .IP |
348 | The use of this option is possible only for connected | |
349 | .B AF_UNIX | |
350 | stream sockets and for | |
351 | .B AF_UNIX | |
352 | stream and datagram socket pairs created using | |
353 | .BR socketpair (2). | |
e6f90c3f SS |
354 | .TP |
355 | .B SO_PEERSEC | |
356 | This read-only socket option returns the | |
357 | security context of the peer socket connected to this socket. | |
358 | By default, this will be the same as the security context of | |
359 | the process that created the peer socket unless overridden | |
360 | by the policy or by a process with the required permissions. | |
361 | .IP | |
362 | The argument to | |
363 | .BR getsockopt (2) | |
14c11c82 | 364 | is a pointer to a buffer of the specified length in bytes |
e6f90c3f SS |
365 | into which the security context string will be copied. |
366 | If the buffer length is less than the length of the security | |
367 | context string, then | |
368 | .BR getsockopt (2) | |
29494dfe | 369 | returns \-1, sets |
e6f90c3f SS |
370 | .I errno |
371 | to | |
29494dfe MK |
372 | .BR ERANGE , |
373 | and returns the required length via | |
374 | .IR optlen . | |
e6f90c3f | 375 | The caller should allocate at least |
1ae6b2c7 | 376 | .B NAME_MAX |
29494dfe | 377 | bytes for the buffer initially, although this is not guaranteed |
14c11c82 MK |
378 | to be sufficient. |
379 | Resizing the buffer to the returned length | |
e6f90c3f SS |
380 | and retrying may be necessary. |
381 | .IP | |
382 | The security context string may include a terminating null character | |
383 | in the returned length, but is not guaranteed to do so: a security | |
384 | context "foo" might be represented as either {'f','o','o'} of length 3 | |
385 | or {'f','o','o','\\0'} of length 4, which are considered to be | |
14c11c82 | 386 | interchangeable. |
29494dfe MK |
387 | The string is printable, does not contain non-terminating null characters, |
388 | and is in an unspecified encoding (in particular, it | |
e6f90c3f SS |
389 | is not guaranteed to be ASCII or UTF-8). |
390 | .IP | |
391 | The use of this option for sockets in the | |
392 | .B AF_UNIX | |
29494dfe MK |
393 | address family is supported since Linux 2.6.2 for connected stream sockets, |
394 | and since Linux 4.18 | |
e6f90c3f | 395 | .\" commit 0b811db2cb2aabc910e53d34ebb95a15997c33e7 |
14c11c82 | 396 | also for stream and datagram socket pairs created using |
e6f90c3f | 397 | .BR socketpair (2). |
366a9bff | 398 | .\" |
c634028a | 399 | .SS Autobind feature |
0cf2caa4 | 400 | If a |
0b80cf56 | 401 | .BR bind (2) |
0cf2caa4 MK |
402 | call specifies |
403 | .I addrlen | |
404 | as | |
405 | .IR sizeof(sa_family_t) , | |
449dd4e2 | 406 | .\" i.e., sizeof(short) |
0cf2caa4 | 407 | or the |
1ae6b2c7 | 408 | .B SO_PASSCRED |
0cf2caa4 MK |
409 | socket option was specified for a socket that was |
410 | not explicitly bound to an address, | |
411 | then the socket is autobound to an abstract address. | |
412 | The address consists of a null byte | |
413 | followed by 5 bytes in the character set | |
9bc87ed0 | 414 | .IR [0\-9a\-f] . |
e4b01162 | 415 | Thus, there is a limit of 2\[ha]20 autobind addresses. |
1e4e3bad | 416 | (From Linux 2.1.15, when the autobind feature was added, |
e4b01162 | 417 | 8 bytes were used, and the limit was thus 2\[ha]32 autobind addresses. |
1e4e3bad | 418 | The change to 5 bytes came in Linux 2.3.15.) |
19e19f5f | 419 | .SS Sockets API |
77117f4f | 420 | The following paragraphs describe domain-specific details and |
008f1ecc | 421 | unsupported features of the sockets API for UNIX domain sockets on Linux. |
c6d039a3 | 422 | .P |
008f1ecc | 423 | UNIX domain sockets do not support the transmission of |
77117f4f MK |
424 | out-of-band data (the |
425 | .B MSG_OOB | |
426 | flag for | |
427 | .BR send (2) | |
428 | and | |
429 | .BR recv (2)). | |
c6d039a3 | 430 | .P |
77117f4f MK |
431 | The |
432 | .BR send (2) | |
433 | .B MSG_MORE | |
008f1ecc | 434 | flag is not supported by UNIX domain sockets. |
c6d039a3 | 435 | .P |
c9a39fea MK |
436 | Before Linux 3.4, |
437 | .\" commit 9f6f9af7694ede6314bed281eec74d588ba9474f | |
438 | the use of | |
77e75b90 MK |
439 | .B MSG_TRUNC |
440 | in the | |
441 | .I flags | |
442 | argument of | |
443 | .BR recv (2) | |
c9a39fea | 444 | was not supported by UNIX domain sockets. |
c6d039a3 | 445 | .P |
77117f4f MK |
446 | The |
447 | .B SO_SNDBUF | |
008f1ecc | 448 | socket option does have an effect for UNIX domain sockets, but the |
77117f4f MK |
449 | .B SO_RCVBUF |
450 | option does not. | |
451 | For datagram sockets, the | |
452 | .B SO_SNDBUF | |
453 | value imposes an upper limit on the size of outgoing datagrams. | |
454 | This limit is calculated as the doubled (see | |
455 | .BR socket (7)) | |
456 | option value less 32 bytes used for overhead. | |
c634028a | 457 | .SS Ancillary messages |
77117f4f MK |
458 | Ancillary data is sent and received using |
459 | .BR sendmsg (2) | |
460 | and | |
461 | .BR recvmsg (2). | |
05bf3361 | 462 | For historical reasons, the ancillary message types listed below |
77117f4f MK |
463 | are specified with a |
464 | .B SOL_SOCKET | |
465 | type even though they are | |
d4c8c97c | 466 | .B AF_UNIX |
77117f4f | 467 | specific. |
05bf3361 | 468 | To send them, set the |
77117f4f MK |
469 | .I cmsg_level |
470 | field of the struct | |
471 | .I cmsghdr | |
472 | to | |
473 | .B SOL_SOCKET | |
474 | and the | |
475 | .I cmsg_type | |
476 | field to the type. | |
05bf3361 | 477 | For more information, see |
77117f4f MK |
478 | .BR cmsg (3). |
479 | .TP | |
480 | .B SCM_RIGHTS | |
481 | Send or receive a set of open file descriptors from another process. | |
482 | The data portion contains an integer array of the file descriptors. | |
87996200 | 483 | .IP |
13600496 MK |
484 | Commonly, this operation is referred to as "passing a file descriptor" |
485 | to another process. | |
486 | However, more accurately, | |
487 | what is being passed is a reference to an open file description (see | |
488 | .BR open (2)), | |
489 | and in the receiving process it is likely that a different | |
490 | file descriptor number will be used. | |
491 | Semantically, this operation is equivalent to duplicating | |
492 | .RB ( dup (2)) | |
493 | a file descriptor into the file descriptor table of another process. | |
8bdcf4bf | 494 | .IP |
4564dd1f MK |
495 | If the buffer used to receive the ancillary data containing |
496 | file descriptors is too small (or is absent), | |
497 | then the ancillary data is truncated (or discarded) | |
498 | and the excess file descriptors are automatically closed | |
499 | in the receiving process. | |
500 | .IP | |
e2340cf7 MK |
501 | If the number of file descriptors received in the ancillary data would |
502 | cause the process to exceed its | |
503 | .B RLIMIT_NOFILE | |
504 | resource limit (see | |
505 | .BR getrlimit (2)), | |
506 | the excess file descriptors are automatically closed | |
507 | in the receiving process. | |
508 | .IP | |
8bdcf4bf | 509 | The kernel constant |
1ae6b2c7 | 510 | .B SCM_MAX_FD |
8bdcf4bf | 511 | defines a limit on the number of file descriptors in the array. |
1221abb6 | 512 | Attempting to send an array larger than this limit causes |
8bdcf4bf MK |
513 | .BR sendmsg (2) |
514 | to fail with the error | |
515 | .BR EINVAL . | |
1ae6b2c7 | 516 | .B SCM_MAX_FD |
8bdcf4bf | 517 | has the value 253 |
8bdcf4bf | 518 | .\" commit bba14de98753cb6599a2dae0e520714b2153522d |
b324e17d | 519 | (or 255 before Linux 2.6.38). |
77117f4f MK |
520 | .TP |
521 | .B SCM_CREDENTIALS | |
008f1ecc | 522 | Send or receive UNIX credentials. |
77117f4f MK |
523 | This can be used for authentication. |
524 | The credentials are passed as a | |
525 | .I struct ucred | |
526 | ancillary message. | |
6a141329 | 527 | This structure is defined in |
b1587ca8 MK |
528 | .I <sys/socket.h> |
529 | as follows: | |
5711c04f | 530 | .IP |
77117f4f | 531 | .in +4n |
b8302363 | 532 | .EX |
77117f4f | 533 | struct ucred { |
b65f4c69 MK |
534 | pid_t pid; /* Process ID of the sending process */ |
535 | uid_t uid; /* User ID of the sending process */ | |
536 | gid_t gid; /* Group ID of the sending process */ | |
77117f4f | 537 | }; |
b8302363 | 538 | .EE |
77117f4f | 539 | .in |
5711c04f | 540 | .IP |
b1587ca8 | 541 | Since glibc 2.8, the |
1bc510f5 | 542 | .B _GNU_SOURCE |
e417acb0 MK |
543 | feature test macro must be defined (before including |
544 | .I any | |
545 | header files) in order to obtain the definition | |
b1587ca8 | 546 | of this structure. |
5711c04f | 547 | .IP |
77117f4f | 548 | The credentials which the sender specifies are checked by the kernel. |
f1081bdc | 549 | A privileged process is allowed to specify values that do not match its own. |
77117f4f | 550 | The sender must specify its own process ID (unless it has the capability |
863d6b7d MK |
551 | .BR CAP_SYS_ADMIN , |
552 | in which case the PID of any existing process may be specified), | |
06b8a13b | 553 | its real user ID, effective user ID, or saved set-user-ID (unless it has |
77117f4f | 554 | .BR CAP_SETUID ), |
06b8a13b | 555 | and its real group ID, effective group ID, or saved set-group-ID |
77117f4f MK |
556 | (unless it has |
557 | .BR CAP_SETGID ). | |
bdef8021 | 558 | .IP |
77117f4f MK |
559 | To receive a |
560 | .I struct ucred | |
b66d5714 | 561 | message, the |
77117f4f MK |
562 | .B SO_PASSCRED |
563 | option must be enabled on the socket. | |
ffad6a01 MK |
564 | .TP |
565 | .B SCM_SECURITY | |
566 | Receive the SELinux security context (the security label) | |
567 | of the peer socket. | |
568 | The received ancillary data is a null-terminated string containing | |
569 | the security context. | |
570 | The receiver should allocate at least | |
1ae6b2c7 | 571 | .B NAME_MAX |
ffad6a01 MK |
572 | bytes in the data portion of the ancillary message for this data. |
573 | .IP | |
574 | To receive the security context, the | |
575 | .B SO_PASSSEC | |
576 | option must be enabled on the socket (see above). | |
c6d039a3 | 577 | .P |
5b5cb195 MK |
578 | When sending ancillary data with |
579 | .BR sendmsg (2), | |
580 | only one item of each of the above types may be included in the sent message. | |
c6d039a3 | 581 | .P |
5219daec MK |
582 | At least one byte of real data should be sent when sending ancillary data. |
583 | On Linux, this is required to successfully send ancillary data over | |
584 | a UNIX domain stream socket. | |
585 | When sending ancillary data over a UNIX domain datagram socket, | |
586 | it is not necessary on Linux to send any accompanying real data. | |
587 | However, portable applications should also include at least one byte | |
588 | of real data when sending ancillary data over a datagram socket. | |
c6d039a3 | 589 | .P |
5af0f223 MK |
590 | When receiving from a stream socket, |
591 | ancillary data forms a kind of barrier for the received data. | |
592 | For example, suppose that the sender transmits as follows: | |
c6d039a3 | 593 | .P |
5af0f223 MK |
594 | .RS |
595 | .PD 0 | |
22356d97 | 596 | .IP (1) 5 |
5af0f223 MK |
597 | .BR sendmsg (2) |
598 | of four bytes, with no ancillary data. | |
22356d97 | 599 | .IP (2) |
5af0f223 MK |
600 | .BR sendmsg (2) |
601 | of one byte, with ancillary data. | |
22356d97 | 602 | .IP (3) |
5af0f223 MK |
603 | .BR sendmsg (2) |
604 | of four bytes, with no ancillary data. | |
605 | .PD | |
606 | .RE | |
c6d039a3 | 607 | .P |
5af0f223 MK |
608 | Suppose that the receiver now performs |
609 | .BR recvmsg (2) | |
610 | calls each with a buffer size of 20 bytes. | |
611 | The first call will receive five bytes of data, | |
612 | along with the ancillary data sent by the second | |
613 | .BR sendmsg (2) | |
614 | call. | |
897367f9 | 615 | The next call will receive the remaining four bytes of data. |
c6d039a3 | 616 | .P |
c0e56ed6 | 617 | If the space allocated for receiving incoming ancillary data is too small |
c8772146 MK |
618 | then the ancillary data is truncated to the number of headers |
619 | that will fit in the supplied buffer (or, in the case of an | |
1ae6b2c7 | 620 | .B SCM_RIGHTS |
c8772146 | 621 | file descriptor list, the list of file descriptors may be truncated). |
c0e56ed6 MK |
622 | If no buffer is provided for incoming ancillary data (i.e., the |
623 | .I msg_control | |
624 | field of the | |
625 | .I msghdr | |
626 | structure supplied to | |
627 | .BR recvmsg (2) | |
628 | is NULL), | |
629 | then the incoming ancillary data is discarded. | |
630 | In both of these cases, the | |
1ae6b2c7 | 631 | .B MSG_CTRUNC |
c8772146 MK |
632 | flag will be set in the |
633 | .I msg.msg_flags | |
634 | value returned by | |
635 | .BR recvmsg (2). | |
636 | .\" | |
fbea0f81 MK |
637 | .SS Ioctls |
638 | The following | |
639 | .BR ioctl (2) | |
640 | calls return information in | |
641 | .IR value . | |
642 | The correct syntax is: | |
c6d039a3 | 643 | .P |
fbea0f81 MK |
644 | .RS |
645 | .nf | |
646 | .BI int " value"; | |
f0d77d97 | 647 | .IB error " = ioctl(" unix_socket ", " ioctl_type ", &" value ");" |
fbea0f81 MK |
648 | .fi |
649 | .RE | |
c6d039a3 | 650 | .P |
fbea0f81 MK |
651 | .I ioctl_type |
652 | can be: | |
653 | .TP | |
654 | .B SIOCINQ | |
170e5f0d JC |
655 | For |
656 | .B SOCK_STREAM | |
311bf2f6 | 657 | sockets, this call returns the number of unread bytes in the receive buffer. |
fbea0f81 MK |
658 | The socket must not be in LISTEN state, otherwise an error |
659 | .RB ( EINVAL ) | |
660 | is returned. | |
661 | .B SIOCINQ | |
662 | is defined in | |
663 | .IR <linux/sockios.h> . | |
fd00f831 | 664 | .\" FIXME . https://www.sourceware.org/bugzilla/show_bug.cgi?id=12002, |
fbea0f81 MK |
665 | .\" filed 2010-09-10, may cause SIOCINQ to be defined in glibc headers |
666 | Alternatively, | |
667 | you can use the synonymous | |
668 | .BR FIONREAD , | |
669 | defined in | |
670 | .IR <sys/ioctl.h> . | |
7aed61d9 | 671 | .\" SIOCOUTQ also has an effect for UNIX domain sockets, but not |
fbea0f81 MK |
672 | .\" quite what userland might expect. It seems to return the number |
673 | .\" of bytes allocated for buffers containing pending output. | |
674 | .\" That number is normally larger than the number of bytes of pending | |
675 | .\" output. Since this info is, from userland's point of view, imprecise, | |
676 | .\" and it may well change, probably best not to document this now. | |
170e5f0d JC |
677 | For |
678 | .B SOCK_DGRAM | |
311bf2f6 | 679 | sockets, |
170e5f0d | 680 | the returned value is the same as |
311bf2f6 | 681 | for Internet domain datagram sockets; |
170e5f0d JC |
682 | see |
683 | .BR udp (7). | |
77117f4f MK |
684 | .SH ERRORS |
685 | .TP | |
686 | .B EADDRINUSE | |
9ee4a2b6 | 687 | The specified local address is already in use or the filesystem socket |
77117f4f MK |
688 | object already exists. |
689 | .TP | |
7934bcdf MK |
690 | .B EBADF |
691 | This error can occur for | |
692 | .BR sendmsg (2) | |
693 | when sending a file descriptor as ancillary data over | |
694 | a UNIX domain socket (see the description of | |
695 | .BR SCM_RIGHTS , | |
696 | above), and indicates that the file descriptor number that | |
3eb078c5 | 697 | is being sent is not valid (e.g., it is not an open file descriptor). |
7934bcdf | 698 | .TP |
77117f4f | 699 | .B ECONNREFUSED |
1fe284ab | 700 | The remote address specified by |
77117f4f | 701 | .BR connect (2) |
1fe284ab | 702 | was not a listening socket. |
d02879f7 | 703 | This error can also occur if the target pathname is not a socket. |
77117f4f MK |
704 | .TP |
705 | .B ECONNRESET | |
706 | Remote socket was unexpectedly closed. | |
707 | .TP | |
708 | .B EFAULT | |
709 | User memory address was not valid. | |
710 | .TP | |
711 | .B EINVAL | |
712 | Invalid argument passed. | |
1fe284ab | 713 | A common cause is that the value |
40656bc7 | 714 | .B AF_UNIX |
1fe284ab | 715 | was not specified in the |
77117f4f | 716 | .I sun_type |
1fe284ab | 717 | field of passed addresses, or the socket was in an |
77117f4f MK |
718 | invalid state for the applied operation. |
719 | .TP | |
720 | .B EISCONN | |
721 | .BR connect (2) | |
722 | called on an already connected socket or a target address was | |
723 | specified on a connected socket. | |
724 | .TP | |
0e6dbf30 KI |
725 | .B ENFILE |
726 | The system-wide limit on the total number of open files has been reached. | |
727 | .TP | |
ec55a2b6 MK |
728 | .B ENOENT |
729 | The pathname in the remote address specified to | |
9470f355 | 730 | .BR connect (2) |
ec55a2b6 MK |
731 | did not exist. |
732 | .TP | |
77117f4f MK |
733 | .B ENOMEM |
734 | Out of memory. | |
735 | .TP | |
736 | .B ENOTCONN | |
737 | Socket operation needs a target address, but the socket is not connected. | |
738 | .TP | |
739 | .B EOPNOTSUPP | |
740 | Stream operation called on non-stream oriented socket or tried to | |
741 | use the out-of-band data option. | |
742 | .TP | |
743 | .B EPERM | |
744 | The sender passed invalid credentials in the | |
745 | .IR "struct ucred" . | |
746 | .TP | |
747 | .B EPIPE | |
748 | Remote socket was closed on a stream socket. | |
749 | If enabled, a | |
750 | .B SIGPIPE | |
751 | is sent as well. | |
752 | This can be avoided by passing the | |
753 | .B MSG_NOSIGNAL | |
754 | flag to | |
110039c1 | 755 | .BR send (2) |
77117f4f | 756 | or |
110039c1 | 757 | .BR sendmsg (2). |
77117f4f MK |
758 | .TP |
759 | .B EPROTONOSUPPORT | |
cd0221ea MK |
760 | Passed protocol is not |
761 | .BR AF_UNIX . | |
77117f4f MK |
762 | .TP |
763 | .B EPROTOTYPE | |
764 | Remote socket does not match the local socket type | |
765 | .RB ( SOCK_DGRAM | |
d1c9ea80 | 766 | versus |
9ca2e0c1 | 767 | .BR SOCK_STREAM ). |
77117f4f MK |
768 | .TP |
769 | .B ESOCKTNOSUPPORT | |
770 | Unknown socket type. | |
dc4eea68 | 771 | .TP |
863d6b7d MK |
772 | .B ESRCH |
773 | While sending an ancillary message containing credentials | |
774 | .RB ( SCM_CREDENTIALS ), | |
775 | the caller specified a PID that does not match any existing process. | |
776 | .TP | |
dc4eea68 MK |
777 | .B ETOOMANYREFS |
778 | This error can occur for | |
779 | .BR sendmsg (2) | |
4529d4e5 | 780 | when sending a file descriptor as ancillary data over |
dc4eea68 MK |
781 | a UNIX domain socket (see the description of |
782 | .BR SCM_RIGHTS , | |
783 | above). | |
784 | It occurs if the number of "in-flight" file descriptors exceeds the | |
785 | .B RLIMIT_NOFILE | |
786 | resource limit and the caller does not have the | |
1ae6b2c7 | 787 | .B CAP_SYS_RESOURCE |
dc4eea68 MK |
788 | capability. |
789 | An in-flight file descriptor is one that has been sent using | |
790 | .BR sendmsg (2) | |
791 | but has not yet been accepted in the recipient process using | |
792 | .BR recvmsg (2). | |
5711c04f | 793 | .IP |
70fdcbc2 MK |
794 | This error is diagnosed since mainline Linux 4.5 |
795 | (and in some earlier kernel versions where the fix has been backported). | |
dc4eea68 MK |
796 | .\" commit 712f4aad406bb1ed67f3f98d04c044191f0ff593 |
797 | In earlier kernel versions, | |
798 | it was possible to place an unlimited number of file descriptors in flight, | |
799 | by sending each file descriptor with | |
800 | .BR sendmsg (2) | |
801 | and then closing the file descriptor so that it was not accounted against the | |
802 | .B RLIMIT_NOFILE | |
803 | resource limit. | |
c6d039a3 | 804 | .P |
77117f4f | 805 | Other errors can be generated by the generic socket layer or |
9ee4a2b6 | 806 | by the filesystem while generating a filesystem socket object. |
77117f4f MK |
807 | See the appropriate manual pages for more information. |
808 | .SH VERSIONS | |
809 | .B SCM_CREDENTIALS | |
810 | and the abstract namespace were introduced with Linux 2.2 and should not | |
811 | be used in portable programs. | |
812 | (Some BSD-derived systems also support credential passing, | |
813 | but the implementation details differ.) | |
814 | .SH NOTES | |
00b78c5f MK |
815 | Binding to a socket with a filename creates a socket |
816 | in the filesystem that must be deleted by the caller when it is no | |
817 | longer needed (using | |
818 | .BR unlink (2)). | |
819 | The usual UNIX close-behind semantics apply; the socket can be unlinked | |
820 | at any time and will be finally removed from the filesystem when the last | |
821 | reference to it is closed. | |
c6d039a3 | 822 | .P |
00b78c5f | 823 | To pass file descriptors or credentials over a |
1ae6b2c7 | 824 | .B SOCK_STREAM |
d3e7786d | 825 | socket, you must |
dbba2b26 | 826 | send or receive at least one byte of nonancillary data in the same |
00b78c5f MK |
827 | .BR sendmsg (2) |
828 | or | |
829 | .BR recvmsg (2) | |
830 | call. | |
c6d039a3 | 831 | .P |
00b78c5f MK |
832 | UNIX domain stream sockets do not support the notion of out-of-band data. |
833 | .\" | |
d02879f7 MK |
834 | .SH BUGS |
835 | When binding a socket to an address, | |
3aa341fc | 836 | Linux is one of the implementations that append a null terminator |
d02879f7 MK |
837 | if none is supplied in |
838 | .IR sun_path . | |
839 | In most cases this is unproblematic: | |
840 | when the socket address is retrieved, | |
841 | it will be one byte longer than that supplied when the socket was bound. | |
842 | However, there is one case where confusing behavior can result: | |
843 | if 108 non-null bytes are supplied when a socket is bound, | |
844 | then the addition of the null terminator takes the length of | |
845 | the pathname beyond | |
846 | .IR sizeof(sun_path) . | |
847 | Consequently, when retrieving the socket address | |
848 | (for example, via | |
849 | .BR accept (2)), | |
850 | .\" The behavior on Solaris is quite similar. | |
851 | if the input | |
852 | .I addrlen | |
853 | argument for the retrieving call is specified as | |
854 | .IR "sizeof(struct sockaddr_un)" , | |
855 | then the returned address structure | |
856 | .I won't | |
857 | have a null terminator in | |
858 | .IR sun_path . | |
c6d039a3 | 859 | .P |
d02879f7 MK |
860 | In addition, some implementations |
861 | .\" i.e., traditional BSD | |
862 | don't require a null terminator when binding a socket (the | |
863 | .I addrlen | |
864 | argument is used to determine the length of | |
865 | .IR sun_path ) | |
866 | and when the socket address is retrieved on these implementations, | |
867 | there is no null terminator in | |
868 | .IR sun_path . | |
c6d039a3 | 869 | .P |
b8017cf5 | 870 | Applications that retrieve socket addresses can (portably) code |
d02879f7 | 871 | to handle the possibility that there is no null terminator in |
1ae6b2c7 | 872 | .I sun_path |
d02879f7 | 873 | by respecting the fact that the number of valid bytes in the pathname is: |
c6d039a3 | 874 | .P |
1ae6b2c7 AC |
875 | .in +4n |
876 | .EX | |
877 | strnlen(addr.sun_path, addrlen \- offsetof(sockaddr_un, sun_path)) | |
878 | .EE | |
879 | .in | |
d02879f7 MK |
880 | .\" The following patch to amend kernel behavior was rejected: |
881 | .\" http://thread.gmane.org/gmane.linux.kernel.api/2437 | |
882 | .\" Subject: [patch] Fix handling of overlength pathname in AF_UNIX sun_path | |
883 | .\" 2012-04-17 | |
884 | .\" And there was a related discussion in the Austin list: | |
885 | .\" http://thread.gmane.org/gmane.comp.standards.posix.austin.general/5735 | |
886 | .\" Subject: Having a sun_path with no null terminator | |
887 | .\" 2012-04-18 | |
888 | .\" | |
889 | .\" FIXME . Track http://austingroupbugs.net/view.php?id=561 | |
c6d039a3 | 890 | .P |
d02879f7 MK |
891 | Alternatively, an application can retrieve |
892 | the socket address by allocating a buffer of size | |
893 | .I "sizeof(struct sockaddr_un)+1" | |
894 | that is zeroed out before the retrieval. | |
895 | The retrieving call can specify | |
896 | .I addrlen | |
897 | as | |
898 | .IR "sizeof(struct sockaddr_un)" , | |
899 | and the extra zero byte ensures that there will be | |
900 | a null terminator for the string returned in | |
901 | .IR sun_path : | |
c6d039a3 | 902 | .P |
a2b7a144 MK |
903 | .in +4n |
904 | .EX | |
d02879f7 | 905 | void *addrp; |
fe5dba13 | 906 | \& |
d02879f7 MK |
907 | addrlen = sizeof(struct sockaddr_un); |
908 | addrp = malloc(addrlen + 1); | |
909 | if (addrp == NULL) | |
910 | /* Handle error */ ; | |
911 | memset(addrp, 0, addrlen + 1); | |
fe5dba13 | 912 | \& |
3e35b19b | 913 | if (getsockname(sfd, (struct sockaddr *) addrp, &addrlen)) == \-1) |
d02879f7 | 914 | /* handle error */ ; |
fe5dba13 | 915 | \& |
d1a71985 | 916 | printf("sun_path = %s\en", ((struct sockaddr_un *) addrp)\->sun_path); |
b8302363 | 917 | .EE |
e646a1ba | 918 | .in |
c6d039a3 | 919 | .P |
d02879f7 MK |
920 | This sort of messiness can be avoided if it is guaranteed |
921 | that the applications that | |
922 | .I create | |
923 | pathname sockets follow the rules outlined above under | |
924 | .IR "Pathname sockets" . | |
a14af333 | 925 | .SH EXAMPLES |
84c8cae2 MK |
926 | The following code demonstrates the use of sequenced-packet |
927 | sockets for local interprocess communication. | |
eb73e8ad | 928 | It consists of two programs. |
15545eb6 | 929 | The server program waits for a connection from the client program. |
84c8cae2 MK |
930 | The client sends each of its command-line arguments in separate messages. |
931 | The server treats the incoming messages as integers and adds them up. | |
eb73e8ad | 932 | The client sends the command string "END". |
84c8cae2 MK |
933 | The server sends back a message containing the sum of the client's integers. |
934 | The client prints the sum and exits. | |
15545eb6 | 935 | The server waits for the next client to connect. |
84c8cae2 | 936 | To stop the server, the client is called with the command-line argument "DOWN". |
c6d039a3 | 937 | .P |
15545eb6 | 938 | The following output was recorded while running the server in the background |
84c8cae2 MK |
939 | and repeatedly executing the client. |
940 | Execution of the server program ends when it receives the "DOWN" command. | |
15545eb6 HS |
941 | .SS Example output |
942 | .in +4n | |
b8302363 | 943 | .EX |
eb73e8ad | 944 | $ \fB./server &\fP |
15545eb6 | 945 | [1] 25887 |
eb73e8ad | 946 | $ \fB./client 3 4\fP |
15545eb6 | 947 | Result = 7 |
eb73e8ad | 948 | $ \fB./client 11 \-5\fP |
15545eb6 | 949 | Result = 6 |
eb73e8ad | 950 | $ \fB./client DOWN\fP |
15545eb6 HS |
951 | Result = 0 |
952 | [1]+ Done ./server | |
953 | $ | |
b8302363 | 954 | .EE |
15545eb6 HS |
955 | .in |
956 | .SS Program source | |
c7885256 | 957 | \& |
35200b55 | 958 | .\" SRC BEGIN (connection.h) |
e7d0bb47 | 959 | .EX |
15545eb6 HS |
960 | /* |
961 | * File connection.h | |
962 | */ | |
fe5dba13 | 963 | \& |
15545eb6 HS |
964 | #define SOCKET_NAME "/tmp/9Lq7BNBnBycd6nxy.socket" |
965 | #define BUFFER_SIZE 12 | |
35200b55 AC |
966 | .EE |
967 | .\" SRC END | |
968 | .P | |
969 | .\" SRC BEGIN (server.c) | |
970 | .EX | |
15545eb6 HS |
971 | /* |
972 | * File server.c | |
973 | */ | |
fe5dba13 | 974 | \& |
15545eb6 HS |
975 | #include <stdio.h> |
976 | #include <stdlib.h> | |
977 | #include <string.h> | |
978 | #include <sys/socket.h> | |
979 | #include <sys/un.h> | |
980 | #include <unistd.h> | |
981 | #include "connection.h" | |
fe5dba13 | 982 | \& |
15545eb6 HS |
983 | int |
984 | main(int argc, char *argv[]) | |
985 | { | |
986 | struct sockaddr_un name; | |
987 | int down_flag = 0; | |
988 | int ret; | |
989 | int connection_socket; | |
990 | int data_socket; | |
991 | int result; | |
992 | char buffer[BUFFER_SIZE]; | |
fe5dba13 | 993 | \& |
46b20ca1 | 994 | /* Create local socket. */ |
fe5dba13 | 995 | \& |
15545eb6 HS |
996 | connection_socket = socket(AF_UNIX, SOCK_SEQPACKET, 0); |
997 | if (connection_socket == \-1) { | |
998 | perror("socket"); | |
999 | exit(EXIT_FAILURE); | |
1000 | } | |
fe5dba13 | 1001 | \& |
15545eb6 | 1002 | /* |
eb73e8ad MK |
1003 | * For portability clear the whole structure, since some |
1004 | * implementations have additional (nonstandard) fields in | |
1005 | * the structure. | |
15545eb6 | 1006 | */ |
fe5dba13 | 1007 | \& |
012b86a0 | 1008 | memset(&name, 0, sizeof(name)); |
fe5dba13 | 1009 | \& |
46b20ca1 | 1010 | /* Bind socket to socket name. */ |
fe5dba13 | 1011 | \& |
15545eb6 HS |
1012 | name.sun_family = AF_UNIX; |
1013 | strncpy(name.sun_path, SOCKET_NAME, sizeof(name.sun_path) \- 1); | |
fe5dba13 | 1014 | \& |
15545eb6 | 1015 | ret = bind(connection_socket, (const struct sockaddr *) &name, |
012b86a0 | 1016 | sizeof(name)); |
15545eb6 HS |
1017 | if (ret == \-1) { |
1018 | perror("bind"); | |
1019 | exit(EXIT_FAILURE); | |
1020 | } | |
fe5dba13 | 1021 | \& |
15545eb6 | 1022 | /* |
eb73e8ad MK |
1023 | * Prepare for accepting connections. The backlog size is set |
1024 | * to 20. So while one request is being processed other requests | |
1025 | * can be waiting. | |
15545eb6 | 1026 | */ |
fe5dba13 | 1027 | \& |
15545eb6 HS |
1028 | ret = listen(connection_socket, 20); |
1029 | if (ret == \-1) { | |
1030 | perror("listen"); | |
1031 | exit(EXIT_FAILURE); | |
1032 | } | |
fe5dba13 | 1033 | \& |
46b20ca1 | 1034 | /* This is the main loop for handling connections. */ |
fe5dba13 | 1035 | \& |
15545eb6 | 1036 | for (;;) { |
fe5dba13 | 1037 | \& |
46b20ca1 | 1038 | /* Wait for incoming connection. */ |
fe5dba13 | 1039 | \& |
15545eb6 | 1040 | data_socket = accept(connection_socket, NULL, NULL); |
3cb43b95 | 1041 | if (data_socket == \-1) { |
15545eb6 HS |
1042 | perror("accept"); |
1043 | exit(EXIT_FAILURE); | |
1044 | } | |
fe5dba13 | 1045 | \& |
15545eb6 | 1046 | result = 0; |
52900faa | 1047 | for (;;) { |
fe5dba13 | 1048 | \& |
46b20ca1 | 1049 | /* Wait for next data packet. */ |
fe5dba13 | 1050 | \& |
b9bf9029 | 1051 | ret = read(data_socket, buffer, sizeof(buffer)); |
15545eb6 | 1052 | if (ret == \-1) { |
eb73e8ad | 1053 | perror("read"); |
15545eb6 HS |
1054 | exit(EXIT_FAILURE); |
1055 | } | |
fe5dba13 | 1056 | \& |
46b20ca1 | 1057 | /* Ensure buffer is 0\-terminated. */ |
fe5dba13 | 1058 | \& |
b9bf9029 | 1059 | buffer[sizeof(buffer) \- 1] = 0; |
fe5dba13 | 1060 | \& |
46b20ca1 | 1061 | /* Handle commands. */ |
fe5dba13 | 1062 | \& |
b9bf9029 | 1063 | if (!strncmp(buffer, "DOWN", sizeof(buffer))) { |
15545eb6 HS |
1064 | down_flag = 1; |
1065 | break; | |
1066 | } | |
fe5dba13 | 1067 | \& |
b9bf9029 | 1068 | if (!strncmp(buffer, "END", sizeof(buffer))) { |
15545eb6 HS |
1069 | break; |
1070 | } | |
fe5dba13 | 1071 | \& |
46b20ca1 | 1072 | /* Add received summand. */ |
fe5dba13 | 1073 | \& |
15545eb6 HS |
1074 | result += atoi(buffer); |
1075 | } | |
fe5dba13 | 1076 | \& |
46b20ca1 | 1077 | /* Send result. */ |
fe5dba13 | 1078 | \& |
15545eb6 | 1079 | sprintf(buffer, "%d", result); |
b9bf9029 | 1080 | ret = write(data_socket, buffer, sizeof(buffer)); |
15545eb6 | 1081 | if (ret == \-1) { |
eb73e8ad | 1082 | perror("write"); |
15545eb6 HS |
1083 | exit(EXIT_FAILURE); |
1084 | } | |
fe5dba13 | 1085 | \& |
46b20ca1 | 1086 | /* Close socket. */ |
fe5dba13 | 1087 | \& |
15545eb6 | 1088 | close(data_socket); |
fe5dba13 | 1089 | \& |
46b20ca1 | 1090 | /* Quit on DOWN command. */ |
fe5dba13 | 1091 | \& |
15545eb6 HS |
1092 | if (down_flag) { |
1093 | break; | |
1094 | } | |
1095 | } | |
fe5dba13 | 1096 | \& |
15545eb6 | 1097 | close(connection_socket); |
fe5dba13 | 1098 | \& |
46b20ca1 | 1099 | /* Unlink the socket. */ |
fe5dba13 | 1100 | \& |
15545eb6 | 1101 | unlink(SOCKET_NAME); |
fe5dba13 | 1102 | \& |
15545eb6 HS |
1103 | exit(EXIT_SUCCESS); |
1104 | } | |
35200b55 AC |
1105 | .EE |
1106 | .\" SRC END | |
1107 | .P | |
1108 | .\" SRC BEGIN (client.c) | |
1109 | .EX | |
15545eb6 HS |
1110 | /* |
1111 | * File client.c | |
1112 | */ | |
fe5dba13 | 1113 | \& |
15545eb6 HS |
1114 | #include <errno.h> |
1115 | #include <stdio.h> | |
1116 | #include <stdlib.h> | |
1117 | #include <string.h> | |
1118 | #include <sys/socket.h> | |
1119 | #include <sys/un.h> | |
1120 | #include <unistd.h> | |
1121 | #include "connection.h" | |
fe5dba13 | 1122 | \& |
15545eb6 HS |
1123 | int |
1124 | main(int argc, char *argv[]) | |
1125 | { | |
24a31d63 | 1126 | struct sockaddr_un addr; |
15545eb6 HS |
1127 | int ret; |
1128 | int data_socket; | |
1129 | char buffer[BUFFER_SIZE]; | |
fe5dba13 | 1130 | \& |
46b20ca1 | 1131 | /* Create local socket. */ |
fe5dba13 | 1132 | \& |
15545eb6 HS |
1133 | data_socket = socket(AF_UNIX, SOCK_SEQPACKET, 0); |
1134 | if (data_socket == \-1) { | |
1135 | perror("socket"); | |
1136 | exit(EXIT_FAILURE); | |
1137 | } | |
fe5dba13 | 1138 | \& |
15545eb6 | 1139 | /* |
eb73e8ad MK |
1140 | * For portability clear the whole structure, since some |
1141 | * implementations have additional (nonstandard) fields in | |
1142 | * the structure. | |
15545eb6 | 1143 | */ |
fe5dba13 | 1144 | \& |
012b86a0 | 1145 | memset(&addr, 0, sizeof(addr)); |
fe5dba13 | 1146 | \& |
46b20ca1 | 1147 | /* Connect socket to socket address. */ |
fe5dba13 | 1148 | \& |
24a31d63 MK |
1149 | addr.sun_family = AF_UNIX; |
1150 | strncpy(addr.sun_path, SOCKET_NAME, sizeof(addr.sun_path) \- 1); | |
fe5dba13 | 1151 | \& |
7551caea | 1152 | ret = connect(data_socket, (const struct sockaddr *) &addr, |
012b86a0 | 1153 | sizeof(addr)); |
15545eb6 | 1154 | if (ret == \-1) { |
d1a71985 | 1155 | fprintf(stderr, "The server is down.\en"); |
15545eb6 HS |
1156 | exit(EXIT_FAILURE); |
1157 | } | |
fe5dba13 | 1158 | \& |
46b20ca1 | 1159 | /* Send arguments. */ |
fe5dba13 | 1160 | \& |
b42296e4 | 1161 | for (size_t i = 1; i < argc; ++i) { |
15545eb6 HS |
1162 | ret = write(data_socket, argv[i], strlen(argv[i]) + 1); |
1163 | if (ret == \-1) { | |
eb73e8ad | 1164 | perror("write"); |
15545eb6 HS |
1165 | break; |
1166 | } | |
1167 | } | |
fe5dba13 | 1168 | \& |
46b20ca1 | 1169 | /* Request result. */ |
fe5dba13 | 1170 | \& |
7551caea | 1171 | strcpy(buffer, "END"); |
15545eb6 HS |
1172 | ret = write(data_socket, buffer, strlen(buffer) + 1); |
1173 | if (ret == \-1) { | |
eb73e8ad | 1174 | perror("write"); |
15545eb6 HS |
1175 | exit(EXIT_FAILURE); |
1176 | } | |
fe5dba13 | 1177 | \& |
46b20ca1 | 1178 | /* Receive result. */ |
fe5dba13 | 1179 | \& |
b9bf9029 | 1180 | ret = read(data_socket, buffer, sizeof(buffer)); |
15545eb6 | 1181 | if (ret == \-1) { |
eb73e8ad | 1182 | perror("read"); |
15545eb6 HS |
1183 | exit(EXIT_FAILURE); |
1184 | } | |
fe5dba13 | 1185 | \& |
46b20ca1 | 1186 | /* Ensure buffer is 0\-terminated. */ |
fe5dba13 | 1187 | \& |
b9bf9029 | 1188 | buffer[sizeof(buffer) \- 1] = 0; |
fe5dba13 | 1189 | \& |
d1a71985 | 1190 | printf("Result = %s\en", buffer); |
fe5dba13 | 1191 | \& |
46b20ca1 | 1192 | /* Close socket. */ |
fe5dba13 | 1193 | \& |
15545eb6 | 1194 | close(data_socket); |
fe5dba13 | 1195 | \& |
15545eb6 HS |
1196 | exit(EXIT_SUCCESS); |
1197 | } | |
e7d0bb47 | 1198 | .EE |
35200b55 | 1199 | .\" SRC END |
c6d039a3 | 1200 | .P |
7a275383 MK |
1201 | For examples of the use of |
1202 | .BR SCM_RIGHTS , | |
c751683c | 1203 | see |
7a275383 MK |
1204 | .BR cmsg (3) |
1205 | and | |
1206 | .BR seccomp_unotify (2). | |
47297adb | 1207 | .SH SEE ALSO |
77117f4f MK |
1208 | .BR recvmsg (2), |
1209 | .BR sendmsg (2), | |
1210 | .BR socket (2), | |
1211 | .BR socketpair (2), | |
1212 | .BR cmsg (3), | |
1213 | .BR capabilities (7), | |
1214 | .BR credentials (7), | |
170e5f0d JC |
1215 | .BR socket (7), |
1216 | .BR udp (7) |