raw/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, 2 Dec 2002, Michael Kerrisk, mtk16@ext.canterbury.ac.nz
   8 .\"
   9 .TH UNIX  7 2002-12-02 "Linux Man Page" "Linux Programmer's Manual"
  10 .SH NAME
  11 unix, PF_UNIX, AF_UNIX, PF_LOCAL, AF_LOCAL \- Sockets for local interprocess communication.
  12 .SH SYNOPSIS
  13 .B #include <sys/socket.h>
  14 .br
  15 .B #include <sys/un.h>
  16
  17 .IB unix_socket " = socket(PF_UNIX, type, 0);"
  18 .br
  19 .IB error " = socketpair(PF_UNIX, type, 0, int *" sv ");"
  20
  21 .SH DESCRIPTION
  22 The
  23 .B PF_UNIX
  24 (also known as
  25 .BR PF_LOCAL )
  26 socket family is used to communicate between processes on the same machine
  27 efficiently. Unix sockets can be either anonymous (created by
  28 .BR socketpair (2))
  29 or associated with a file of type socket.
  30 Linux also supports an abstract namespace which is independent of the
  31 file system.
  32
  33 Valid types are
  34 .B SOCK_STREAM
  35 for a stream oriented socket and
  36 .B SOCK_DGRAM
  37 for a datagram oriented socket that preserves message boundaries. Unix
  38 sockets are always reliable and don't reorder datagrams.
  39
  40 Unix sockets support passing file descriptors or process credentials to other
  41 processes using ancillary data.
  42
  43 .SH "ADDRESS FORMAT"
  44 A unix address is defined as a filename in the filesystem or
  45 as a unique string in the abstract namespace. Sockets created by
  46 .BR socketpair (2)
  47 are anonymous. For non-anonymous sockets the target address can be set
  48 using
  49 .BR connect (2).
  50 The local address can be set using
  51 .BR bind (2).
  52 When a socket is connected and it doesn't already have a local address a
  53 unique address in the abstract namespace will be generated automatically.
  54
  55 .RS
  56 .nf
  57 #define UNIX_PATH_MAX   108
  58
  59 .ta 4n 17n 42n
  60 struct sockaddr_un {
  61         sa_family_t     sun_family;     /* AF_UNIX */
  62         char    sun_path[UNIX_PATH_MAX];        /* pathname */
  63 };
  64 .fi
  65 .RE
  66
  67 .B sun_family
  68 always contains
  69 .BR AF_UNIX .
  70 .B sun_path
  71 contains the zero-terminated pathname of the socket in the file system.
  72 If
  73 .B sun_path
  74 starts with a zero byte it refers to the abstract namespace maintained by
  75 the Unix protocol module.
  76 The socket's address in this namespace is given by the rest of the bytes in
  77 .BR sun_path .
  78 Note that names in the abstract namespace are not zero-terminated.
  79
  80 .SH "SOCKET OPTIONS"
  81 For historical reasons these socket options are specified with a
  82 SOL_SOCKET type even though they are PF_UNIX specific.
  83 They can be set with
  84 .BR setsockopt (2)
  85 and read with
  86 .BR getsockopt (2)
  87 by specifying SOL_SOCKET as the socket family.
  88 .TP
  89 .B SO_PASSCRED
  90 Enables the receiving of the credentials of the sending process
  91 ancillary message. When this option is set and the socket is not yet connected
  92 a unique name in the abstract namespace will be generated automatically.
  93 Expects an integer boolean flag.
  94
  95 .SH "ANCILLARY MESSAGES"
  96 Ancillary data is sent and received using
  97 .BR sendmsg (2)
  98 and
  99 .BR recvmsg (2).
 100 For historical reasons the ancillary message types listed below
 101 are specified with a SOL_SOCKET type even though they are PF_UNIX specific.
 102 To send them set the
 103 .B cmsg_level
 104 field of the struct
 105 .B cmsghdr
 106 to SOL_SOCKET and the
 107 .B cmsg_type
 108 field to the type. For more information see
 109 .BR cmsg (3).
 110
 111 .TP
 112 .B SCM_RIGHTS
 113 Send or receive a set of open file descriptors from another process.
 114 The data portion contains an integer array of the file descriptors.
 115 The passed file descriptors behave as though they have been created with
 116 .BR dup (2).
 117
 118 .TP
 119 .B SCM_CREDENTIALS
 120 Send or receive unix credentials.  This can be used for authentication.
 121 The credentials are passed as a
 122 .B struct ucred
 123 ancillary message.
 124
 125 .RS
 126 .nf
 127 .ta 4n 11n 17n
 128 struct ucred {
 129         pid_t   pid;    /* process id of the sending process */
 130         uid_t   uid;    /* user id of the sending process */
 131         gid_t   gid;    /* group id of the sending process */
 132 };
 133 .fi
 134 .RE
 135
 136 The credentials which the sender specifies are checked by the kernel.
 137 A process with effective user ID 0 is allowed to specify values that do
 138 not match his own.
 139 The sender must specify its own process ID (unless it has the capability
 140 .BR CAP_SYS_ADMIN ),
 141 its user ID, effective user ID or set user ID (unless it has
 142 .BR CAP_SETUID ),
 143 and its group id, effective group ID or set group ID (unless it has
 144 .BR CAP_SETGID ).
 145 To receive a
 146 .B struct ucred
 147 message the
 148 .B SO_PASSCRED
 149 option must be enabled on the socket.
 150
 151 .SH VERSIONS
 152 .B SCM_CREDENTIALS
 153 and the abstract namespace were introduced with Linux 2.2 and should not
 154 be used in portable programs.
 155 (Some BSD-derived systems also support credential passing,
 156 but the implementation details differ.)
 157
 158 .SH NOTES
 159 In the Linux implementation, sockets which are visible in the
 160 filesystem honour the permissions of the directory they are in. Their
 161 owner, group and their permissions can be changed.
 162 Creation of a new socket will fail if the process does not have write and
 163 search (execute) permission on the directory the socket is created in.
 164 Connecting to the socket object requires read/write permission.
 165 This behavior differs from many BSD-derived systems which
 166 ignore permissions for Unix sockets. Portable programs should not rely on
 167 this feature for security.
 168
 169 Binding to a socket with a filename creates a socket
 170 in the file system that must be deleted by the caller when it is no
 171 longer needed (using
 172 .BR unlink (2)).
 173 The usual Unix close-behind semantics apply; the socket can be unlinked
 174 at any time and will be finally removed from the file system when the last
 175 reference to it is closed.
 176
 177 To pass file descriptors or credentials you need to send/read at least
 178 one byte of data.
 179
 180 Unix domain stream sockets do not support the notion of out-of-band data.
 181 .SH ERRORS
 182 .TP
 183 .B ENOMEM
 184 Out of memory.
 185 .TP
 186 .B ECONNREFUSED
 187 .BR connect (2)
 188 called with a socket object that isn't listening. This can happen when
 189 the remote socket does not exist or the filename is not a socket.
 190 .TP
 191 .B EINVAL
 192 Invalid argument passed. A common cause is the missing setting of AF_UNIX
 193 in the sun_type field of passed addresses or the socket being in an invalid
 194 state for the applied operation.
 195 .TP
 196 .B EOPNOTSUPP
 197 Stream operation called on non-stream oriented socket or tried to
 198 use the out-of-band data option.
 199 .TP
 200 .B EPROTONOSUPPORT
 201 Passed protocol is not PF_UNIX.
 202 .TP
 203 .B ESOCKTNOSUPPORT
 204 Unknown socket type.
 205 .TP
 206 .B EPROTOTYPE
 207 Remote socket does not match the local socket type (SOCK_DGRAM vs.
 208 SOCK_STREAM)
 209 .TP
 210 .B EADDRINUSE
 211 Selected local address is already taken or filesystem socket object already
 212 exists.
 213 .TP
 214 .B EISCONN
 215 .BR connect (2)
 216 called on an already connected socket or a target address was
 217 specified on a connected socket.
 218 .TP
 219 .B ENOTCONN
 220 Socket operation needs a target address, but the socket is not connected.
 221 .TP
 222 .B ECONNRESET
 223 Remote socket was unexpectedly closed.
 224 .TP
 225 .B EPIPE
 226 Remote socket was closed on a stream socket. If enabled, a
 227 .B SIGPIPE
 228 is sent as well. This can be avoided by passing the
 229 .B MSG_NOSIGNAL
 230 flag to
 231 .BR sendmsg (2)
 232 or
 233 .BR recvmsg (2).
 234 .TP
 235 .B EFAULT
 236 User memory address was not valid.
 237 .TP
 238 .B EPERM
 239 The sender passed invalid credentials in the
 240 .BR "struct ucred" .
 241 .PP
 242 Other errors can be generated by the generic socket layer or
 243 by the filesystem while generating a filesystem socket object. See
 244 the appropriate manual pages for more information.
 245 .SH "SEE ALSO"
 246 .BR recvmsg (2),
 247 .BR sendmsg (2),
 248 .BR socket (2),
 249 .BR socketpair (2),
 250 .BR cmsg (3),
 251 .BR capabilities (7),
 252 .BR socket (7)
 253 .\" .SH CREDITS
 254 .\" This man page was written by Andi Kleen.