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