man7/unix.7

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