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