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 2010-11-15 "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 ('\\0').
 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 .SS Sockets API
 171 The following paragraphs describe domain-specific details and
 172 unsupported features of the sockets API for UNIX domain sockets on Linux.
 173
 174 UNIX domain sockets do not support the transmission of
 175 out-of-band data (the
 176 .B MSG_OOB
 177 flag for
 178 .BR send (2)
 179 and
 180 .BR recv (2)).
 181
 182 The
 183 .BR send (2)
 184 .B MSG_MORE
 185 flag is not supported by UNIX domain sockets.
 186
 187 The use of
 188 .B MSG_TRUNC
 189 in the
 190 .I flags
 191 argument of
 192 .BR recv (2)
 193 is not supported by UNIX domain sockets.
 194
 195 The
 196 .B SO_SNDBUF
 197 socket option does have an effect for UNIX domain sockets, but the
 198 .B SO_RCVBUF
 199 option does not.
 200 For datagram sockets, the
 201 .B SO_SNDBUF
 202 value imposes an upper limit on the size of outgoing datagrams.
 203 This limit is calculated as the doubled (see
 204 .BR socket (7))
 205 option value less 32 bytes used for overhead.
 206 .SS Ancillary Messages
 207 Ancillary data is sent and received using
 208 .BR sendmsg (2)
 209 and
 210 .BR recvmsg (2).
 211 For historical reasons the ancillary message types listed below
 212 are specified with a
 213 .B SOL_SOCKET
 214 type even though they are
 215 .B AF_UNIX
 216 specific.
 217 To send them set the
 218 .I cmsg_level
 219 field of the struct
 220 .I cmsghdr
 221 to
 222 .B SOL_SOCKET
 223 and the
 224 .I cmsg_type
 225 field to the type.
 226 For more information see
 227 .BR cmsg (3).
 228 .TP
 229 .B SCM_RIGHTS
 230 Send or receive a set of open file descriptors from another process.
 231 The data portion contains an integer array of the file descriptors.
 232 The passed file descriptors behave as though they have been created with
 233 .BR dup (2).
 234 .TP
 235 .B SCM_CREDENTIALS
 236 Send or receive UNIX credentials.
 237 This can be used for authentication.
 238 The credentials are passed as a
 239 .I struct ucred
 240 ancillary message.
 241 Thus structure is defined in
 242 .I <sys/socket.h>
 243 as follows:
 244
 245 .in +4n
 246 .nf
 247 struct ucred {
 248     pid_t pid;    /* process ID of the sending process */
 249     uid_t uid;    /* user ID of the sending process */
 250     gid_t gid;    /* group ID of the sending process */
 251 };
 252 .fi
 253 .in
 254
 255 Since glibc 2.8, the
 256 .B _GNU_SOURCE
 257 feature test macro must be defined (before including
 258 .I any
 259 header files) in order to obtain the definition
 260 of this structure.
 261
 262 The credentials which the sender specifies are checked by the kernel.
 263 A process with effective user ID 0 is allowed to specify values that do
 264 not match its own.
 265 The sender must specify its own process ID (unless it has the capability
 266 .BR CAP_SYS_ADMIN ),
 267 its user ID, effective user ID, or saved set-user-ID (unless it has
 268 .BR CAP_SETUID ),
 269 and its group ID, effective group ID, or saved set-group-ID
 270 (unless it has
 271 .BR CAP_SETGID ).
 272 To receive a
 273 .I struct ucred
 274 message the
 275 .B SO_PASSCRED
 276 option must be enabled on the socket.
 277 .SS Ioctls
 278 The following
 279 .BR ioctl (2)
 280 calls return information in
 281 .IR value .
 282 The correct syntax is:
 283 .PP
 284 .RS
 285 .nf
 286 .BI int " value";
 287 .IB error " = ioctl(" tcp_socket ", " ioctl_type ", &" value ");"
 288 .fi
 289 .RE
 290 .PP
 291 .I ioctl_type
 292 can be:
 293 .TP
 294 .B SIOCINQ
 295 Returns the amount of queued unread data in the receive buffer.
 296 The socket must not be in LISTEN state, otherwise an error
 297 .RB ( EINVAL )
 298 is returned.
 299 .B SIOCINQ
 300 is defined in
 301 .IR <linux/sockios.h> .
 302 .\" FIXME http://sources.redhat.com/bugzilla/show_bug.cgi?id=12002,
 303 .\" filed 2010-09-10, may cause SIOCINQ to be defined in glibc headers
 304 Alternatively,
 305 you can use the synonymous
 306 .BR FIONREAD ,
 307 defined in
 308 .IR <sys/ioctl.h> .
 309 .\" SIOCOUTQ also has an effect for UNIX domain sockets, but not
 310 .\" quite what userland might expect. It seems to return the number
 311 .\" of bytes allocated for buffers containing pending output.
 312 .\" That number is normally larger than the number of bytes of pending
 313 .\" output. Since this info is, from userland's point of view, imprecise,
 314 .\" and it may well change, probably best not to document this now.
 315 .SH ERRORS
 316 .TP
 317 .B EADDRINUSE
 318 The specified local address is already in use or the file system socket
 319 object already exists.
 320 .TP
 321 .B ECONNREFUSED
 322 The remote address specified by
 323 .BR connect (2)
 324 was not a listening socket.
 325 This error can also occur if the target filename is not a socket.
 326 .TP
 327 .B ECONNRESET
 328 Remote socket was unexpectedly closed.
 329 .TP
 330 .B EFAULT
 331 User memory address was not valid.
 332 .TP
 333 .B EINVAL
 334 Invalid argument passed.
 335 A common cause is that the value
 336 .B AF_UNIX
 337 was not specified in the
 338 .I sun_type
 339 field of passed addresses, or the socket was in an
 340 invalid state for the applied operation.
 341 .TP
 342 .B EISCONN
 343 .BR connect (2)
 344 called on an already connected socket or a target address was
 345 specified on a connected socket.
 346 .TP
 347 .B ENOENT
 348 The pathname in the remote address specified to
 349 .BR connect ()
 350 did not exist.
 351 .TP
 352 .B ENOMEM
 353 Out of memory.
 354 .TP
 355 .B ENOTCONN
 356 Socket operation needs a target address, but the socket is not connected.
 357 .TP
 358 .B EOPNOTSUPP
 359 Stream operation called on non-stream oriented socket or tried to
 360 use the out-of-band data option.
 361 .TP
 362 .B EPERM
 363 The sender passed invalid credentials in the
 364 .IR "struct ucred" .
 365 .TP
 366 .B EPIPE
 367 Remote socket was closed on a stream socket.
 368 If enabled, a
 369 .B SIGPIPE
 370 is sent as well.
 371 This can be avoided by passing the
 372 .B MSG_NOSIGNAL
 373 flag to
 374 .BR sendmsg (2)
 375 or
 376 .BR recvmsg (2).
 377 .TP
 378 .B EPROTONOSUPPORT
 379 Passed protocol is not
 380 .BR AF_UNIX .
 381 .TP
 382 .B EPROTOTYPE
 383 Remote socket does not match the local socket type
 384 .RB ( SOCK_DGRAM
 385 versus
 386 .BR SOCK_STREAM )
 387 .TP
 388 .B ESOCKTNOSUPPORT
 389 Unknown socket type.
 390 .PP
 391 Other errors can be generated by the generic socket layer or
 392 by the file system while generating a file system socket object.
 393 See the appropriate manual pages for more information.
 394 .SH VERSIONS
 395 .B SCM_CREDENTIALS
 396 and the abstract namespace were introduced with Linux 2.2 and should not
 397 be used in portable programs.
 398 (Some BSD-derived systems also support credential passing,
 399 but the implementation details differ.)
 400 .SH NOTES
 401 In the Linux implementation, sockets which are visible in the
 402 file system honor the permissions of the directory they are in.
 403 Their owner, group and their permissions can be changed.
 404 Creation of a new socket will fail if the process does not have write and
 405 search (execute) permission on the directory the socket is created in.
 406 Connecting to the socket object requires read/write permission.
 407 This behavior differs from many BSD-derived systems which
 408 ignore permissions for UNIX domain sockets.
 409 Portable programs should not rely on
 410 this feature for security.
 411
 412 Binding to a socket with a filename creates a socket
 413 in the file system that must be deleted by the caller when it is no
 414 longer needed (using
 415 .BR unlink (2)).
 416 The usual UNIX close-behind semantics apply; the socket can be unlinked
 417 at any time and will be finally removed from the file system when the last
 418 reference to it is closed.
 419
 420 To pass file descriptors or credentials over a
 421 .BR SOCK_STREAM ,
 422 you need
 423 to send or receive at least one byte of nonancillary data in the same
 424 .BR sendmsg (2)
 425 or
 426 .BR recvmsg (2)
 427 call.
 428
 429 UNIX domain stream sockets do not support the notion of out-of-band data.
 430 .SH EXAMPLE
 431 See
 432 .BR bind (2).
 433 .SH "SEE ALSO"
 434 .BR recvmsg (2),
 435 .BR sendmsg (2),
 436 .BR socket (2),
 437 .BR socketpair (2),
 438 .BR cmsg (3),
 439 .BR capabilities (7),
 440 .BR credentials (7),
 441 .BR socket (7)