original/man7/unix.7

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