original/man7/unix.7

   1 .\" This man page is Copyright (C) 1999 Andi Kleen <ak@muc.de>.
   2 .\" and Copyright (C) 2008-2014, Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" %%%LICENSE_START(VERBATIM_ONE_PARA)
   5 .\" and Copyright (C) 2008, 2012 Michael Kerrisk <mtk.manpages@gmail.com>
   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 2014-12-31 "Linux" "Linux Programmer's Manual"
  21 .SH NAME
  22 unix \- sockets for local interprocess communication
  23 .SH SYNOPSIS
  24 .B #include <sys/socket.h>
  25 .br
  26 .B #include <sys/un.h>
  27
  28 .IB unix_socket " = socket(AF_UNIX, type, 0);"
  29 .br
  30 .IB error " = socketpair(AF_UNIX, type, 0, int *" sv ");"
  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
  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 connection-oriented socket that preserves message boundaries
  53 and delivers messages in the order that they were sent.
  54
  55 UNIX domain sockets support passing file descriptors or process credentials
  56 to other processes using ancillary data.
  57 .SS Address format
  58 A UNIX domain socket address is represented in the following structure:
  59 .in +4n
  60 .nf
  61
  62 #define UNIX_PATH_MAX    108
  63
  64 struct sockaddr_un {
  65     sa_family_t sun_family;               /* AF_UNIX */
  66     char        sun_path[UNIX_PATH_MAX];  /* pathname */
  67 };
  68 .fi
  69 .in
  70 .PP
  71 The
  72 .I sun_family
  73 field always contains
  74 .BR AF_UNIX .
  75
  76 Various systems calls (for example,
  77 .BR bind (2),
  78 .BR connect (2),
  79 and
  80 .BR sendto (2))
  81 take a
  82 .I sockaddr_un
  83 argument as input.
  84 Some other system calls (for example,
  85 .BR getsockname (2),
  86 .BR getpeername (2),
  87 .BR recvfrom (2),
  88 and
  89 .BR accept (2))
  90 return an argument of this type.
  91
  92 Three types of address are distinguished in the
  93 .I sockaddr_un
  94 structure:
  95 .IP * 3
  96 .IR pathname :
  97 a UNIX domain socket can be bound to a null-terminated
  98 filesystem pathname using
  99 .BR bind (2).
 100 When the address of a pathname socket is returned
 101 (by one of the system calls noted above),
 102 its length is
 103
 104     offsetof(struct sockaddr_un, sun_path) + strlen(sun_path) + 1
 105
 106 and
 107 .I sun_path
 108 contains the null-terminated pathname.
 109 (On Linux, the above
 110 .BR offsetof ()
 111 expression equates to the same value as
 112 .IR sizeof(sa_family_t) ,
 113 but some other implementations include other fields before
 114 .IR sun_path ,
 115 so the
 116 .BR offsetof ()
 117 expression more portably describes the size of the address structure.)
 118 .IP
 119 For further details of pathname sockets, see below.
 120 .IP *
 121 .IR unnamed :
 122 A stream socket that has not been bound to a pathname using
 123 .BR bind (2)
 124 has no name.
 125 Likewise, the two sockets created by
 126 .BR socketpair (2)
 127 are unnamed.
 128 When the address of an unnamed socket is returned,
 129 its length is
 130 .IR "sizeof(sa_family_t)" ,
 131 and
 132 .I sun_path
 133 should not be inspected.
 134 .\" There is quite some variation across implementations: FreeBSD
 135 .\" says the length is 16 bytes, HP-UX 11 says it's zero bytes.
 136 .IP *
 137 .IR abstract :
 138 an abstract socket address is distinguished (from a pathname socket)
 139 by the fact that
 140 .IR sun_path[0]
 141 is a null byte (\(aq\\0\(aq).
 142 The socket's address in this namespace is given by the additional
 143 bytes in
 144 .IR sun_path
 145 that are covered by the specified length of the address structure.
 146 (Null bytes in the name have no special significance.)
 147 The name has no connection with filesystem pathnames.
 148 When the address of an abstract socket is returned,
 149 the returned
 150 .I addrlen
 151 is greater than
 152 .IR "sizeof(sa_family_t)"
 153 (i.e., greater than 2), and the name of the socket is contained in
 154 the first
 155 .IR "(addrlen \- sizeof(sa_family_t))"
 156 bytes of
 157 .IR sun_path .
 158 The abstract socket namespace is a nonportable Linux extension.
 159 .SS Pathname sockets
 160 When binding a socket to a pathname, a few rules should be observed
 161 for maximum portability and ease of coding:
 162 .IP * 3
 163 The pathname in
 164 .I sun_path
 165 should be null-terminated.
 166 .IP *
 167 The length of the pathname, including the terminating null byte,
 168 should not exceed the size of
 169 .IR sun_path .
 170 .IP *
 171 The
 172 .I addrlen
 173 argument that describes the enclosing
 174 .I sockaddr_un
 175 structure should have a value of at least:
 176
 177 .nf
 178     offsetof(struct sockaddr_un, sun_path)+strlen(addr.sun_path)+1
 179 .fi
 180 .IP
 181 or, more simply,
 182 .I addrlen
 183 can be specified as
 184 .IR "sizeof(struct sockaddr_un)" .
 185 .PP
 186 There is some variation in how implementations handle UNIX domain
 187 socket addresses that do not follow the above rules.
 188 For example, some (but not all) implementations
 189 .\" Linux does this, including for the case where the supplied path
 190 .\" is 108 bytes
 191 append a null terminator if none is present in the supplied
 192 .IR sun_path .
 193
 194 When coding portable applications,
 195 keep in mind that some implementations
 196 .\" HP-UX
 197 have
 198 .I sun_path
 199 as short as 92 bytes.
 200 .\" Modern BSDs generally have 104, Tru64 and AIX have 104,
 201 .\" Solaris and Irix have 108
 202
 203 Various system calls
 204 .RB ( accept (2),
 205 .BR recvfrom (2),
 206 .BR getsockname (2),
 207 .BR getpeername (2))
 208 return socket address structures.
 209 When applied to UNIX domain sockets, the value-result
 210 .I addrlen
 211 argument supplied to the call should be initialized as above.
 212 Upon return, the argument is set to indicate the
 213 .I actual
 214 size of the address structure.
 215 The caller should check the value returned in this argument:
 216 if the output value exceeds the input value,
 217 then there is no guarantee that a null terminator is present in
 218 .IR sun_path .
 219 (See BUGS.)
 220 .SS Socket options
 221 For historical reasons, these socket options are specified with a
 222 .B SOL_SOCKET
 223 type even though they are
 224 .B AF_UNIX
 225 specific.
 226 They can be set with
 227 .BR setsockopt (2)
 228 and read with
 229 .BR getsockopt (2)
 230 by specifying
 231 .B SOL_SOCKET
 232 as the socket family.
 233 .TP
 234 .B SO_PASSCRED
 235 Enables the receiving of the credentials of the sending process in an
 236 ancillary message.
 237 When this option is set and the socket is not yet connected
 238 a unique name in the abstract namespace will be generated automatically.
 239 Expects an integer boolean flag.
 240 .SS Autobind feature
 241 If a
 242 .BR bind (2)
 243 call specifies
 244 .I addrlen
 245 as
 246 .IR sizeof(sa_family_t) ,
 247 .\" i.e., sizeof(short)
 248 or the
 249 .BR SO_PASSCRED
 250 socket option was specified for a socket that was
 251 not explicitly bound to an address,
 252 then the socket is autobound to an abstract address.
 253 The address consists of a null byte
 254 followed by 5 bytes in the character set
 255 .IR [0-9a-f] .
 256 Thus, there is a limit of 2^20 autobind addresses.
 257 (From Linux 2.1.15, when the autobind feature was added,
 258 8 bytes were used, and the limit was thus 2^32 autobind addresses.
 259 The change to 5 bytes came in Linux 2.3.15.)
 260 .SS Sockets API
 261 The following paragraphs describe domain-specific details and
 262 unsupported features of the sockets API for UNIX domain sockets on Linux.
 263
 264 UNIX domain sockets do not support the transmission of
 265 out-of-band data (the
 266 .B MSG_OOB
 267 flag for
 268 .BR send (2)
 269 and
 270 .BR recv (2)).
 271
 272 The
 273 .BR send (2)
 274 .B MSG_MORE
 275 flag is not supported by UNIX domain sockets.
 276
 277 The use of
 278 .B MSG_TRUNC
 279 in the
 280 .I flags
 281 argument of
 282 .BR recv (2)
 283 is not supported by UNIX domain sockets.
 284
 285 The
 286 .B SO_SNDBUF
 287 socket option does have an effect for UNIX domain sockets, but the
 288 .B SO_RCVBUF
 289 option does not.
 290 For datagram sockets, the
 291 .B SO_SNDBUF
 292 value imposes an upper limit on the size of outgoing datagrams.
 293 This limit is calculated as the doubled (see
 294 .BR socket (7))
 295 option value less 32 bytes used for overhead.
 296 .SS Ancillary messages
 297 Ancillary data is sent and received using
 298 .BR sendmsg (2)
 299 and
 300 .BR recvmsg (2).
 301 For historical reasons the ancillary message types listed below
 302 are specified with a
 303 .B SOL_SOCKET
 304 type even though they are
 305 .B AF_UNIX
 306 specific.
 307 To send them set the
 308 .I cmsg_level
 309 field of the struct
 310 .I cmsghdr
 311 to
 312 .B SOL_SOCKET
 313 and the
 314 .I cmsg_type
 315 field to the type.
 316 For more information see
 317 .BR cmsg (3).
 318 .TP
 319 .B SCM_RIGHTS
 320 Send or receive a set of open file descriptors from another process.
 321 The data portion contains an integer array of the file descriptors.
 322 The passed file descriptors behave as though they have been created with
 323 .BR dup (2).
 324 .TP
 325 .B SCM_CREDENTIALS
 326 Send or receive UNIX credentials.
 327 This can be used for authentication.
 328 The credentials are passed as a
 329 .I struct ucred
 330 ancillary message.
 331 Thus structure is defined in
 332 .I <sys/socket.h>
 333 as follows:
 334
 335 .in +4n
 336 .nf
 337 struct ucred {
 338     pid_t pid;    /* process ID of the sending process */
 339     uid_t uid;    /* user ID of the sending process */
 340     gid_t gid;    /* group ID of the sending process */
 341 };
 342 .fi
 343 .in
 344
 345 Since glibc 2.8, the
 346 .B _GNU_SOURCE
 347 feature test macro must be defined (before including
 348 .I any
 349 header files) in order to obtain the definition
 350 of this structure.
 351
 352 The credentials which the sender specifies are checked by the kernel.
 353 A process with effective user ID 0 is allowed to specify values that do
 354 not match its own.
 355 The sender must specify its own process ID (unless it has the capability
 356 .BR CAP_SYS_ADMIN ),
 357 its user ID, effective user ID, or saved set-user-ID (unless it has
 358 .BR CAP_SETUID ),
 359 and its group ID, effective group ID, or saved set-group-ID
 360 (unless it has
 361 .BR CAP_SETGID ).
 362 To receive a
 363 .I struct ucred
 364 message the
 365 .B SO_PASSCRED
 366 option must be enabled on the socket.
 367 .SS Ioctls
 368 The following
 369 .BR ioctl (2)
 370 calls return information in
 371 .IR value .
 372 The correct syntax is:
 373 .PP
 374 .RS
 375 .nf
 376 .BI int " value";
 377 .IB error " = ioctl(" unix_socket ", " ioctl_type ", &" value ");"
 378 .fi
 379 .RE
 380 .PP
 381 .I ioctl_type
 382 can be:
 383 .TP
 384 .B SIOCINQ
 385 Returns the amount of queued unread data in the receive buffer.
 386 The socket must not be in LISTEN state, otherwise an error
 387 .RB ( EINVAL )
 388 is returned.
 389 .B SIOCINQ
 390 is defined in
 391 .IR <linux/sockios.h> .
 392 .\" FIXME . http://sources.redhat.com/bugzilla/show_bug.cgi?id=12002,
 393 .\" filed 2010-09-10, may cause SIOCINQ to be defined in glibc headers
 394 Alternatively,
 395 you can use the synonymous
 396 .BR FIONREAD ,
 397 defined in
 398 .IR <sys/ioctl.h> .
 399 .\" SIOCOUTQ also has an effect for UNIX domain sockets, but not
 400 .\" quite what userland might expect. It seems to return the number
 401 .\" of bytes allocated for buffers containing pending output.
 402 .\" That number is normally larger than the number of bytes of pending
 403 .\" output. Since this info is, from userland's point of view, imprecise,
 404 .\" and it may well change, probably best not to document this now.
 405 .SH ERRORS
 406 .TP
 407 .B EADDRINUSE
 408 The specified local address is already in use or the filesystem socket
 409 object already exists.
 410 .TP
 411 .B ECONNREFUSED
 412 The remote address specified by
 413 .BR connect (2)
 414 was not a listening socket.
 415 This error can also occur if the target pathname is not a socket.
 416 .TP
 417 .B ECONNRESET
 418 Remote socket was unexpectedly closed.
 419 .TP
 420 .B EFAULT
 421 User memory address was not valid.
 422 .TP
 423 .B EINVAL
 424 Invalid argument passed.
 425 A common cause is that the value
 426 .B AF_UNIX
 427 was not specified in the
 428 .I sun_type
 429 field of passed addresses, or the socket was in an
 430 invalid state for the applied operation.
 431 .TP
 432 .B EISCONN
 433 .BR connect (2)
 434 called on an already connected socket or a target address was
 435 specified on a connected socket.
 436 .TP
 437 .B ENOENT
 438 The pathname in the remote address specified to
 439 .BR connect (2)
 440 did not exist.
 441 .TP
 442 .B ENOMEM
 443 Out of memory.
 444 .TP
 445 .B ENOTCONN
 446 Socket operation needs a target address, but the socket is not connected.
 447 .TP
 448 .B EOPNOTSUPP
 449 Stream operation called on non-stream oriented socket or tried to
 450 use the out-of-band data option.
 451 .TP
 452 .B EPERM
 453 The sender passed invalid credentials in the
 454 .IR "struct ucred" .
 455 .TP
 456 .B EPIPE
 457 Remote socket was closed on a stream socket.
 458 If enabled, a
 459 .B SIGPIPE
 460 is sent as well.
 461 This can be avoided by passing the
 462 .B MSG_NOSIGNAL
 463 flag to
 464 .BR sendmsg (2)
 465 or
 466 .BR recvmsg (2).
 467 .TP
 468 .B EPROTONOSUPPORT
 469 Passed protocol is not
 470 .BR AF_UNIX .
 471 .TP
 472 .B EPROTOTYPE
 473 Remote socket does not match the local socket type
 474 .RB ( SOCK_DGRAM
 475 versus
 476 .BR SOCK_STREAM )
 477 .TP
 478 .B ESOCKTNOSUPPORT
 479 Unknown socket type.
 480 .PP
 481 Other errors can be generated by the generic socket layer or
 482 by the filesystem while generating a filesystem socket object.
 483 See the appropriate manual pages for more information.
 484 .SH VERSIONS
 485 .B SCM_CREDENTIALS
 486 and the abstract namespace were introduced with Linux 2.2 and should not
 487 be used in portable programs.
 488 (Some BSD-derived systems also support credential passing,
 489 but the implementation details differ.)
 490 .SH NOTES
 491 In the Linux implementation, sockets which are visible in the
 492 filesystem honor the permissions of the directory they are in.
 493 Their owner, group, and permissions can be changed.
 494 Creation of a new socket will fail if the process does not have write and
 495 search (execute) permission on the directory the socket is created in.
 496 Connecting to the socket object requires read/write permission.
 497 This behavior differs from many BSD-derived systems which
 498 ignore permissions for UNIX domain sockets.
 499 Portable programs should not rely on
 500 this feature for security.
 501
 502 Binding to a socket with a filename creates a socket
 503 in the filesystem that must be deleted by the caller when it is no
 504 longer needed (using
 505 .BR unlink (2)).
 506 The usual UNIX close-behind semantics apply; the socket can be unlinked
 507 at any time and will be finally removed from the filesystem when the last
 508 reference to it is closed.
 509
 510 To pass file descriptors or credentials over a
 511 .BR SOCK_STREAM ,
 512 you need
 513 to send or receive at least one byte of nonancillary data in the same
 514 .BR sendmsg (2)
 515 or
 516 .BR recvmsg (2)
 517 call.
 518
 519 UNIX domain stream sockets do not support the notion of out-of-band data.
 520 .\"
 521 .SH BUGS
 522 When binding a socket to an address,
 523 Linux is one of the implementations that appends a null terminator
 524 if none is supplied in
 525 .IR sun_path .
 526 In most cases this is unproblematic:
 527 when the socket address is retrieved,
 528 it will be one byte longer than that supplied when the socket was bound.
 529 However, there is one case where confusing behavior can result:
 530 if 108 non-null bytes are supplied when a socket is bound,
 531 then the addition of the null terminator takes the length of
 532 the pathname beyond
 533 .IR sizeof(sun_path) .
 534 Consequently, when retrieving the socket address
 535 (for example, via
 536 .BR accept (2)),
 537 .\" The behavior on Solaris is quite similar.
 538 if the input
 539 .I addrlen
 540 argument for the retrieving call is specified as
 541 .IR "sizeof(struct sockaddr_un)" ,
 542 then the returned address structure
 543 .I won't
 544 have a null terminator in
 545 .IR sun_path .
 546
 547 In addition, some implementations
 548 .\" i.e., traditional BSD
 549 don't require a null terminator when binding a socket (the
 550 .I addrlen
 551 argument is used to determine the length of
 552 .IR sun_path )
 553 and when the socket address is retrieved on these implementations,
 554 there is no null terminator in
 555 .IR sun_path .
 556
 557 Applications that retrieve socket addresses can (portably) code
 558 to handle the possibility that there is no null terminator in
 559 .IR sun_path
 560 by respecting the fact that the number of valid bytes in the pathname is:
 561
 562     strnlen(addr.sun_path, addrlen \- offsetof(sockaddr_un, sun_path))
 563 .\" The following patch to amend kernel behavior was rejected:
 564 .\" http://thread.gmane.org/gmane.linux.kernel.api/2437
 565 .\" Subject: [patch] Fix handling of overlength pathname in AF_UNIX sun_path
 566 .\" 2012-04-17
 567 .\" And there was a related discussion in the Austin list:
 568 .\" http://thread.gmane.org/gmane.comp.standards.posix.austin.general/5735
 569 .\" Subject: Having a sun_path with no null terminator
 570 .\" 2012-04-18
 571 .\"
 572 .\" FIXME . Track http://austingroupbugs.net/view.php?id=561
 573
 574 Alternatively, an application can retrieve
 575 the socket address by allocating a buffer of size
 576 .I "sizeof(struct sockaddr_un)+1"
 577 that is zeroed out before the retrieval.
 578 The retrieving call can specify
 579 .I addrlen
 580 as
 581 .IR "sizeof(struct sockaddr_un)" ,
 582 and the extra zero byte ensures that there will be
 583 a null terminator for the string returned in
 584 .IR sun_path :
 585
 586 .nf
 587 .in +3
 588 void *addrp;
 589
 590 addrlen = sizeof(struct sockaddr_un);
 591 addrp = malloc(addrlen + 1);
 592 if (addrp == NULL)
 593     /* Handle error */ ;
 594 memset(addrp, 0, addrlen + 1);
 595
 596 if (getsockname(sfd, (struct sockaddr *) addrp, &addrlen)) == \-1)
 597     /* handle error */ ;
 598
 599 printf("sun_path = %s\\n", ((struct sockaddr_un *) addrp)\->sun_path);
 600 .in
 601 .fi
 602
 603 This sort of messiness can be avoided if it is guaranteed
 604 that the applications that
 605 .I create
 606 pathname sockets follow the rules outlined above under
 607 .IR "Pathname sockets" .
 608 .SH EXAMPLE
 609 See
 610 .BR bind (2).
 611
 612 For an example of the use of
 613 .BR SCM_RIGHTS
 614 see
 615 .BR cmsg (3).
 616 .SH SEE ALSO
 617 .BR recvmsg (2),
 618 .BR sendmsg (2),
 619 .BR socket (2),
 620 .BR socketpair (2),
 621 .BR cmsg (3),
 622 .BR capabilities (7),
 623 .BR credentials (7),
 624 .BR socket (7)
 625 .SH COLOPHON
 626 This page is part of release 3.79 of the Linux
 627 .I man-pages
 628 project.
 629 A description of the project,
 630 information about reporting bugs,
 631 and the latest version of this page,
 632 can be found at
 633 \%http://www.kernel.org/doc/man\-pages/.