man7/unix.7

   1 .\" This man page is Copyright (C) 1999 Andi Kleen <ak@muc.de>.
   2 .\" Permission is granted to distribute possibly modified copies
   3 .\" of this page provided the header is included verbatim,
   4 .\" and in case of nontrivial modification author and date
   5 .\" of the modification is added to the header.
   6 .\"
   7 .\" Modified, 2003-12-02, Michael Kerrisk, <mtk.manpages@gmail.com>
   8 .\" Modified, 2003-09-23, Adam Langley
   9 .\" Modified, 2004-05-27, Michael Kerrisk, <mtk.manpages@gmail.com>
  10 .\"     Added SOCK_SEQPACKET
  11 .\" 2008-05-27, mtk, Provide a clear description of the three types of
  12 .\"     address that can appear in the sockaddr_un structure: pathname,
  13 .\"     unnamed, and abstract.
  14 .\"
  15 .TH UNIX  7 2012-05-10 "Linux" "Linux Programmer's Manual"
  16 .SH NAME
  17 unix \- sockets for local interprocess communication
  18 .SH SYNOPSIS
  19 .B #include <sys/socket.h>
  20 .br
  21 .B #include <sys/un.h>
  22
  23 .IB unix_socket " = socket(AF_UNIX, type, 0);"
  24 .br
  25 .IB error " = socketpair(AF_UNIX, type, 0, int *" sv ");"
  26 .SH DESCRIPTION
  27 The
  28 .B AF_UNIX
  29 (also known as
  30 .BR AF_LOCAL )
  31 socket family is used to communicate between processes on the same machine
  32 efficiently.
  33 Traditionally, UNIX domain sockets can be either unnamed,
  34 or bound to a file system pathname (marked as being of type socket).
  35 Linux also supports an abstract namespace which is independent of the
  36 file system.
  37
  38 Valid types are:
  39 .BR SOCK_STREAM ,
  40 for a stream-oriented socket and
  41 .BR SOCK_DGRAM ,
  42 for a datagram-oriented socket that preserves message boundaries
  43 (as on most UNIX implementations, UNIX domain datagram
  44 sockets are always reliable and don't reorder datagrams);
  45 and (since Linux 2.6.4)
  46 .BR SOCK_SEQPACKET ,
  47 for a connection-oriented socket that preserves message boundaries
  48 and delivers messages in the order that they were sent.
  49
  50 UNIX domain sockets support passing file descriptors or process credentials
  51 to other processes using ancillary data.
  52 .SS Address format
  53 A UNIX domain socket address is represented in the following structure:
  54 .in +4n
  55 .nf
  56
  57 #define UNIX_PATH_MAX    108
  58
  59 struct sockaddr_un {
  60     sa_family_t sun_family;               /* AF_UNIX */
  61     char        sun_path[UNIX_PATH_MAX];  /* pathname */
  62 };
  63 .fi
  64 .in
  65 .PP
  66 .I sun_family
  67 always contains
  68 .BR AF_UNIX .
  69
  70 Three types of address are distinguished in this structure:
  71 .IP * 3
  72 .IR pathname :
  73 a UNIX domain socket can be bound to a null-terminated file
  74 system pathname using
  75 .BR bind (2).
  76 When the address of the socket is returned by
  77 .BR getsockname (2),
  78 .BR getpeername (2),
  79 and
  80 .BR accept (2),
  81 its length is
  82 .IR "offsetof(struct sockaddr_un, sun_path) + strlen(sun_path) + 1" ,
  83 and
  84 .I sun_path
  85 contains the null-terminated pathname.
  86 .IP *
  87 .IR unnamed :
  88 A stream socket that has not been bound to a pathname using
  89 .BR bind (2)
  90 has no name.
  91 Likewise, the two sockets created by
  92 .BR socketpair (2)
  93 are unnamed.
  94 When the address of an unnamed socket is returned by
  95 .BR getsockname (2),
  96 .BR getpeername (2),
  97 and
  98 .BR accept (2),
  99 its length is
 100 .IR "sizeof(sa_family_t)" ,
 101 and
 102 .I sun_path
 103 should not be inspected.
 104 .\" There is quite some variation across implementations: FreeBSD
 105 .\" says the length is 16 bytes, HP-UX 11 says it's zero bytes.
 106 .IP *
 107 .IR abstract :
 108 an abstract socket address is distinguished by the fact that
 109 .IR sun_path[0]
 110 is a null byte (\(aq\\0\(aq).
 111 The socket's address in this namespace is given by the additional
 112 bytes in
 113 .IR sun_path
 114 that are covered by the specified length of the address structure.
 115 (Null bytes in the name have no special significance.)
 116 The name has no connection with file system pathnames.
 117 When the address of an abstract socket is returned by
 118 .BR getsockname (2),
 119 .BR getpeername (2),
 120 and
 121 .BR accept (2),
 122 the returned
 123 .I addrlen
 124 is greater than
 125 .IR "sizeof(sa_family_t)"
 126 (i.e., greater than 2), and the name of the socket is contained in
 127 the first
 128 .IR "(addrlen \- sizeof(sa_family_t))"
 129 bytes of
 130 .IR sun_path .
 131 The abstract socket namespace is a nonportable Linux extension.
 132 .SS Socket options
 133 For historical reasons these socket options are specified with a
 134 .B SOL_SOCKET
 135 type even though they are
 136 .B AF_UNIX
 137 specific.
 138 They can be set with
 139 .BR setsockopt (2)
 140 and read with
 141 .BR getsockopt (2)
 142 by specifying
 143 .B SOL_SOCKET
 144 as the socket family.
 145 .TP
 146 .B SO_PASSCRED
 147 Enables the receiving of the credentials of the sending process in an
 148 ancillary message.
 149 When this option is set and the socket is not yet connected
 150 a unique name in the abstract namespace will be generated automatically.
 151 Expects an integer boolean flag.
 152 .SS Autobind feature
 153 If a
 154 .BR bind (2)
 155 call specifies
 156 .I addrlen
 157 as
 158 .IR sizeof(sa_family_t) ,
 159 .\" i.e. sizeof(short)
 160 or the
 161 .BR SO_PASSCRED
 162 socket option was specified for a socket that was
 163 not explicitly bound to an address,
 164 then the socket is autobound to an abstract address.
 165 The address consists of a null byte
 166 followed by 5 bytes in the character set
 167 .IR [0-9a-f] .
 168 Thus, there is a limit of 2^20 autobind addresses.
 169 (From Linux 2.1.15, when the autobind feature was added,
 170 8 bytes were used, and the limit was thus 2^32 autobind addresses.
 171 The change to 5 bytes came in Linux 2.3.15.)
 172 .SS Sockets API
 173 The following paragraphs describe domain-specific details and
 174 unsupported features of the sockets API for UNIX domain sockets on Linux.
 175
 176 UNIX domain sockets do not support the transmission of
 177 out-of-band data (the
 178 .B MSG_OOB
 179 flag for
 180 .BR send (2)
 181 and
 182 .BR recv (2)).
 183
 184 The
 185 .BR send (2)
 186 .B MSG_MORE
 187 flag is not supported by UNIX domain sockets.
 188
 189 The use of
 190 .B MSG_TRUNC
 191 in the
 192 .I flags
 193 argument of
 194 .BR recv (2)
 195 is not supported by UNIX domain sockets.
 196
 197 The
 198 .B SO_SNDBUF
 199 socket option does have an effect for UNIX domain sockets, but the
 200 .B SO_RCVBUF
 201 option does not.
 202 For datagram sockets, the
 203 .B SO_SNDBUF
 204 value imposes an upper limit on the size of outgoing datagrams.
 205 This limit is calculated as the doubled (see
 206 .BR socket (7))
 207 option value less 32 bytes used for overhead.
 208 .SS Ancillary messages
 209 Ancillary data is sent and received using
 210 .BR sendmsg (2)
 211 and
 212 .BR recvmsg (2).
 213 For historical reasons the ancillary message types listed below
 214 are specified with a
 215 .B SOL_SOCKET
 216 type even though they are
 217 .B AF_UNIX
 218 specific.
 219 To send them set the
 220 .I cmsg_level
 221 field of the struct
 222 .I cmsghdr
 223 to
 224 .B SOL_SOCKET
 225 and the
 226 .I cmsg_type
 227 field to the type.
 228 For more information see
 229 .BR cmsg (3).
 230 .TP
 231 .B SCM_RIGHTS
 232 Send or receive a set of open file descriptors from another process.
 233 The data portion contains an integer array of the file descriptors.
 234 The passed file descriptors behave as though they have been created with
 235 .BR dup (2).
 236 .TP
 237 .B SCM_CREDENTIALS
 238 Send or receive UNIX credentials.
 239 This can be used for authentication.
 240 The credentials are passed as a
 241 .I struct ucred
 242 ancillary message.
 243 Thus structure is defined in
 244 .I <sys/socket.h>
 245 as follows:
 246
 247 .in +4n
 248 .nf
 249 struct ucred {
 250     pid_t pid;    /* process ID of the sending process */
 251     uid_t uid;    /* user ID of the sending process */
 252     gid_t gid;    /* group ID of the sending process */
 253 };
 254 .fi
 255 .in
 256
 257 Since glibc 2.8, the
 258 .B _GNU_SOURCE
 259 feature test macro must be defined (before including
 260 .I any
 261 header files) in order to obtain the definition
 262 of this structure.
 263
 264 The credentials which the sender specifies are checked by the kernel.
 265 A process with effective user ID 0 is allowed to specify values that do
 266 not match its own.
 267 The sender must specify its own process ID (unless it has the capability
 268 .BR CAP_SYS_ADMIN ),
 269 its user ID, effective user ID, or saved set-user-ID (unless it has
 270 .BR CAP_SETUID ),
 271 and its group ID, effective group ID, or saved set-group-ID
 272 (unless it has
 273 .BR CAP_SETGID ).
 274 To receive a
 275 .I struct ucred
 276 message the
 277 .B SO_PASSCRED
 278 option must be enabled on the socket.
 279 .SS Ioctls
 280 The following
 281 .BR ioctl (2)
 282 calls return information in
 283 .IR value .
 284 The correct syntax is:
 285 .PP
 286 .RS
 287 .nf
 288 .BI int " value";
 289 .IB error " = ioctl(" unix_socket ", " ioctl_type ", &" value ");"
 290 .fi
 291 .RE
 292 .PP
 293 .I ioctl_type
 294 can be:
 295 .TP
 296 .B SIOCINQ
 297 Returns the amount of queued unread data in the receive buffer.
 298 The socket must not be in LISTEN state, otherwise an error
 299 .RB ( EINVAL )
 300 is returned.
 301 .B SIOCINQ
 302 is defined in
 303 .IR <linux/sockios.h> .
 304 .\" FIXME http://sources.redhat.com/bugzilla/show_bug.cgi?id=12002,
 305 .\" filed 2010-09-10, may cause SIOCINQ to be defined in glibc headers
 306 Alternatively,
 307 you can use the synonymous
 308 .BR FIONREAD ,
 309 defined in
 310 .IR <sys/ioctl.h> .
 311 .\" SIOCOUTQ also has an effect for UNIX domain sockets, but not
 312 .\" quite what userland might expect. It seems to return the number
 313 .\" of bytes allocated for buffers containing pending output.
 314 .\" That number is normally larger than the number of bytes of pending
 315 .\" output. Since this info is, from userland's point of view, imprecise,
 316 .\" and it may well change, probably best not to document this now.
 317 .SH ERRORS
 318 .TP
 319 .B EADDRINUSE
 320 The specified local address is already in use or the file system socket
 321 object already exists.
 322 .TP
 323 .B ECONNREFUSED
 324 The remote address specified by
 325 .BR connect (2)
 326 was not a listening socket.
 327 This error can also occur if the target filename is not a socket.
 328 .TP
 329 .B ECONNRESET
 330 Remote socket was unexpectedly closed.
 331 .TP
 332 .B EFAULT
 333 User memory address was not valid.
 334 .TP
 335 .B EINVAL
 336 Invalid argument passed.
 337 A common cause is that the value
 338 .B AF_UNIX
 339 was not specified in the
 340 .I sun_type
 341 field of passed addresses, or the socket was in an
 342 invalid state for the applied operation.
 343 .TP
 344 .B EISCONN
 345 .BR connect (2)
 346 called on an already connected socket or a target address was
 347 specified on a connected socket.
 348 .TP
 349 .B ENOENT
 350 The pathname in the remote address specified to
 351 .BR connect (2)
 352 did not exist.
 353 .TP
 354 .B ENOMEM
 355 Out of memory.
 356 .TP
 357 .B ENOTCONN
 358 Socket operation needs a target address, but the socket is not connected.
 359 .TP
 360 .B EOPNOTSUPP
 361 Stream operation called on non-stream oriented socket or tried to
 362 use the out-of-band data option.
 363 .TP
 364 .B EPERM
 365 The sender passed invalid credentials in the
 366 .IR "struct ucred" .
 367 .TP
 368 .B EPIPE
 369 Remote socket was closed on a stream socket.
 370 If enabled, a
 371 .B SIGPIPE
 372 is sent as well.
 373 This can be avoided by passing the
 374 .B MSG_NOSIGNAL
 375 flag to
 376 .BR sendmsg (2)
 377 or
 378 .BR recvmsg (2).
 379 .TP
 380 .B EPROTONOSUPPORT
 381 Passed protocol is not
 382 .BR AF_UNIX .
 383 .TP
 384 .B EPROTOTYPE
 385 Remote socket does not match the local socket type
 386 .RB ( SOCK_DGRAM
 387 versus
 388 .BR SOCK_STREAM )
 389 .TP
 390 .B ESOCKTNOSUPPORT
 391 Unknown socket type.
 392 .PP
 393 Other errors can be generated by the generic socket layer or
 394 by the file system while generating a file system socket object.
 395 See the appropriate manual pages for more information.
 396 .SH VERSIONS
 397 .B SCM_CREDENTIALS
 398 and the abstract namespace were introduced with Linux 2.2 and should not
 399 be used in portable programs.
 400 (Some BSD-derived systems also support credential passing,
 401 but the implementation details differ.)
 402 .SH NOTES
 403 In the Linux implementation, sockets which are visible in the
 404 file system honor the permissions of the directory they are in.
 405 Their owner, group and their permissions can be changed.
 406 Creation of a new socket will fail if the process does not have write and
 407 search (execute) permission on the directory the socket is created in.
 408 Connecting to the socket object requires read/write permission.
 409 This behavior differs from many BSD-derived systems which
 410 ignore permissions for UNIX domain sockets.
 411 Portable programs should not rely on
 412 this feature for security.
 413
 414 Binding to a socket with a filename creates a socket
 415 in the file system that must be deleted by the caller when it is no
 416 longer needed (using
 417 .BR unlink (2)).
 418 The usual UNIX close-behind semantics apply; the socket can be unlinked
 419 at any time and will be finally removed from the file system when the last
 420 reference to it is closed.
 421
 422 To pass file descriptors or credentials over a
 423 .BR SOCK_STREAM ,
 424 you need
 425 to send or receive at least one byte of nonancillary data in the same
 426 .BR sendmsg (2)
 427 or
 428 .BR recvmsg (2)
 429 call.
 430
 431 UNIX domain stream sockets do not support the notion of out-of-band data.
 432 .SH EXAMPLE
 433 See
 434 .BR bind (2).
 435
 436 For an example of the use of
 437 .BR SCM_RIGHTS
 438 see
 439 .BR cmsg (3).
 440 .SH SEE ALSO
 441 .BR recvmsg (2),
 442 .BR sendmsg (2),
 443 .BR socket (2),
 444 .BR socketpair (2),
 445 .BR cmsg (3),
 446 .BR capabilities (7),
 447 .BR credentials (7),
 448 .BR socket (7)