1UNIX(7)                    Linux Programmer's Manual                   UNIX(7)
2
3
4

NAME

6       unix - sockets for local interprocess communication
7

SYNOPSIS

9       #include <sys/socket.h>
10       #include <sys/un.h>
11
12       unix_socket = socket(AF_UNIX, type, 0);
13       error = socketpair(AF_UNIX, type, 0, int *sv);
14

DESCRIPTION

16       The  AF_UNIX (also known as AF_LOCAL) socket family is used to communi‐
17       cate between processes on the same machine efficiently.  Traditionally,
18       UNIX  domain  sockets  can be either unnamed, or bound to a file system
19       pathname (marked as being of type  socket).   Linux  also  supports  an
20       abstract namespace which is independent of the file system.
21
22       Valid   types  are:  SOCK_STREAM,  for  a  stream-oriented  socket  and
23       SOCK_DGRAM, for  a  datagram-oriented  socket  that  preserves  message
24       boundaries (as on most UNIX implementations, UNIX domain datagram sock‐
25       ets are always reliable and don't reorder datagrams); and (since  Linux
26       2.6.4)  SOCK_SEQPACKET, for a connection-oriented socket that preserves
27       message boundaries and delivers messages in the order  that  they  were
28       sent.
29
30       UNIX domain sockets support passing file descriptors or process creden‐
31       tials to other processes using ancillary data.
32
33   Address format
34       A UNIX domain socket address is represented in the following structure:
35
36           #define UNIX_PATH_MAX    108
37
38           struct sockaddr_un {
39               sa_family_t sun_family;               /* AF_UNIX */
40               char        sun_path[UNIX_PATH_MAX];  /* pathname */
41           };
42
43       sun_family always contains AF_UNIX.
44
45       Three types of address are distinguished in this structure:
46
47       *  pathname: a UNIX domain socket can be  bound  to  a  null-terminated
48          file  system pathname using bind(2).  When the address of the socket
49          is returned by getsockname(2), getpeername(2),  and  accept(2),  its
50          length  is offsetof(struct sockaddr_un, sun_path) + strlen(sun_path)
51          + 1, and sun_path contains the null-terminated pathname.
52
53       *  unnamed: A stream socket that has not been bound to a pathname using
54          bind(2)  has  no name.  Likewise, the two sockets created by socket‐
55          pair(2) are unnamed.  When the  address  of  an  unnamed  socket  is
56          returned  by  getsockname(2),  getpeername(2),  and  accept(2),  its
57          length is sizeof(sa_family_t), and sun_path should not be inspected.
58
59       *  abstract: an abstract socket address is distinguished  by  the  fact
60          that  sun_path[0]  is  a  null byte ('\0').  The socket's address in
61          this namespace is given by the additional bytes in sun_path that are
62          covered  by  the  specified  length of the address structure.  (Null
63          bytes in the name have no special significance.)  The  name  has  no
64          connection  with  file  system  pathnames.   When  the address of an
65          abstract socket is returned by getsockname(2),  getpeername(2),  and
66          accept(2),  the returned addrlen is greater than sizeof(sa_family_t)
67          (i.e., greater than 2), and the name of the socket is  contained  in
68          the  first  (addrlen  - sizeof(sa_family_t)) bytes of sun_path.  The
69          abstract socket namespace is a nonportable Linux extension.
70
71   Socket options
72       For historical reasons  these  socket  options  are  specified  with  a
73       SOL_SOCKET type even though they are AF_UNIX specific.  They can be set
74       with setsockopt(2) and read with getsockopt(2) by specifying SOL_SOCKET
75       as the socket family.
76
77       SO_PASSCRED
78              Enables  the receiving of the credentials of the sending process
79              in an ancillary message.  When this option is set and the socket
80              is  not  yet  connected  a unique name in the abstract namespace
81              will be generated automatically.   Expects  an  integer  boolean
82              flag.
83
84   Autobind feature
85       If  a  bind(2)  call  specifies  addrlen as sizeof(sa_family_t), or the
86       SO_PASSCRED socket option was specified  for  a  socket  that  was  not
87       explicitly  bound  to  an  address,  then the socket is autobound to an
88       abstract address.  The address consists of a null byte  followed  by  5
89       bytes  in  the  character set [0-9a-f].  Thus, there is a limit of 2^20
90       autobind addresses.  (From Linux 2.1.15, when the autobind feature  was
91       added,  8  bytes  were  used,  and  the  limit  was  thus 2^32 autobind
92       addresses.  The change to 5 bytes came in Linux 2.3.15.)
93
94   Sockets API
95       The following paragraphs describe domain-specific  details  and  unsup‐
96       ported features of the sockets API for UNIX domain sockets on Linux.
97
98       UNIX domain sockets do not support the transmission of out-of-band data
99       (the MSG_OOB flag for send(2) and recv(2)).
100
101       The send(2) MSG_MORE flag is not supported by UNIX domain sockets.
102
103       The use of MSG_TRUNC in the flags argument of recv(2) is not  supported
104       by UNIX domain sockets.
105
106       The  SO_SNDBUF  socket option does have an effect for UNIX domain sock‐
107       ets, but the SO_RCVBUF option does  not.   For  datagram  sockets,  the
108       SO_SNDBUF  value  imposes  an upper limit on the size of outgoing data‐
109       grams.  This limit is calculated as the doubled (see socket(7))  option
110       value less 32 bytes used for overhead.
111
112   Ancillary messages
113       Ancillary  data  is  sent and received using sendmsg(2) and recvmsg(2).
114       For historical reasons the ancillary message  types  listed  below  are
115       specified with a SOL_SOCKET type even though they are AF_UNIX specific.
116       To send them  set  the  cmsg_level  field  of  the  struct  cmsghdr  to
117       SOL_SOCKET  and  the cmsg_type field to the type.  For more information
118       see cmsg(3).
119
120       SCM_RIGHTS
121              Send or receive a set of  open  file  descriptors  from  another
122              process.  The data portion contains an integer array of the file
123              descriptors.  The passed file descriptors behave as though  they
124              have been created with dup(2).
125
126       SCM_CREDENTIALS
127              Send  or receive UNIX credentials.  This can be used for authen‐
128              tication.  The credentials are passed as a struct  ucred  ancil‐
129              lary  message.   Thus  structure is defined in <sys/socket.h> as
130              follows:
131
132                  struct ucred {
133                      pid_t pid;    /* process ID of the sending process */
134                      uid_t uid;    /* user ID of the sending process */
135                      gid_t gid;    /* group ID of the sending process */
136                  };
137
138              Since glibc 2.8, the _GNU_SOURCE  feature  test  macro  must  be
139              defined  (before  including any header files) in order to obtain
140              the definition of this structure.
141
142              The credentials which the sender specifies are  checked  by  the
143              kernel.   A process with effective user ID 0 is allowed to spec‐
144              ify values that do not match its own.  The sender  must  specify
145              its own process ID (unless it has the capability CAP_SYS_ADMIN),
146              its user ID, effective user ID, or saved set-user-ID (unless  it
147              has  CAP_SETUID), and its group ID, effective group ID, or saved
148              set-group-ID (unless it has CAP_SETGID).  To  receive  a  struct
149              ucred  message  the  SO_PASSCRED  option  must be enabled on the
150              socket.
151
152   Ioctls
153       The following ioctl(2) calls return information in value.  The  correct
154       syntax is:
155
156              int value;
157              error = ioctl(unix_socket, ioctl_type, &value);
158
159       ioctl_type can be:
160
161       SIOCINQ
162              Returns  the amount of queued unread data in the receive buffer.
163              The socket must not be in LISTEN state, otherwise an error (EIN‐
164              VAL)  is  returned.   SIOCINQ  is  defined in <linux/sockios.h>.
165              Alternatively, you can use the synonymous FIONREAD,  defined  in
166              <sys/ioctl.h>.
167

ERRORS

169       EADDRINUSE
170              The specified local address is already in use or the file system
171              socket object already exists.
172
173       ECONNREFUSED
174              The remote address specified by connect(2) was not  a  listening
175              socket.  This error can also occur if the target filename is not
176              a socket.
177
178       ECONNRESET
179              Remote socket was unexpectedly closed.
180
181       EFAULT User memory address was not valid.
182
183       EINVAL Invalid argument passed.  A  common  cause  is  that  the  value
184              AF_UNIX  was  not  specified  in  the  sun_type  field of passed
185              addresses, or the socket was in an invalid state for the applied
186              operation.
187
188       EISCONN
189              connect(2)  called  on  an  already connected socket or a target
190              address was specified on a connected socket.
191
192       ENOENT The pathname in the remote address specified to  connect(2)  did
193              not exist.
194
195       ENOMEM Out of memory.
196
197       ENOTCONN
198              Socket  operation  needs a target address, but the socket is not
199              connected.
200
201       EOPNOTSUPP
202              Stream operation called on non-stream oriented socket  or  tried
203              to use the out-of-band data option.
204
205       EPERM  The sender passed invalid credentials in the struct ucred.
206
207       EPIPE  Remote socket was closed on a stream socket.  If enabled, a SIG‐
208              PIPE is sent as well.   This  can  be  avoided  by  passing  the
209              MSG_NOSIGNAL flag to sendmsg(2) or recvmsg(2).
210
211       EPROTONOSUPPORT
212              Passed protocol is not AF_UNIX.
213
214       EPROTOTYPE
215              Remote  socket  does not match the local socket type (SOCK_DGRAM
216              versus SOCK_STREAM)
217
218       ESOCKTNOSUPPORT
219              Unknown socket type.
220
221       Other errors can be generated by the generic socket  layer  or  by  the
222       file  system  while  generating  a  file system socket object.  See the
223       appropriate manual pages for more information.
224

VERSIONS

226       SCM_CREDENTIALS and the abstract namespace were introduced  with  Linux
227       2.2  and  should  not  be used in portable programs.  (Some BSD-derived
228       systems also support credential passing, but the implementation details
229       differ.)
230

NOTES

232       In the Linux implementation, sockets which are visible in the file sys‐
233       tem honor the permissions of the directory they are in.   Their  owner,
234       group  and  their permissions can be changed.  Creation of a new socket
235       will fail if the process does not have write and search (execute)  per‐
236       mission  on  the directory the socket is created in.  Connecting to the
237       socket object requires read/write permission.   This  behavior  differs
238       from  many BSD-derived systems which ignore permissions for UNIX domain
239       sockets.  Portable programs should not rely on this feature  for  secu‐
240       rity.
241
242       Binding to a socket with a filename creates a socket in the file system
243       that must be deleted by the caller when it is no longer  needed  (using
244       unlink(2)).   The  usual  UNIX close-behind semantics apply; the socket
245       can be unlinked at any time and will be finally removed from  the  file
246       system when the last reference to it is closed.
247
248       To pass file descriptors or credentials over a SOCK_STREAM, you need to
249       send or receive at least one byte of  nonancillary  data  in  the  same
250       sendmsg(2) or recvmsg(2) call.
251
252       UNIX  domain  stream  sockets  do not support the notion of out-of-band
253       data.
254

EXAMPLE

256       See bind(2).
257
258       For an example of the use of SCM_RIGHTS see cmsg(3).
259

SEE ALSO

261       recvmsg(2), sendmsg(2), socket(2),  socketpair(2),  cmsg(3),  capabili‐
262       ties(7), credentials(7), socket(7)
263

COLOPHON

265       This  page  is  part of release 3.53 of the Linux man-pages project.  A
266       description of the project, and information about reporting  bugs,  can
267       be found at http://www.kernel.org/doc/man-pages/.
268
269
270
271Linux                             2012-05-10                           UNIX(7)
Impressum