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

NAME

6       unix, AF_UNIX, AF_LOCAL - 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  sockets can be either unnamed, or bound to a file system pathname
19       (marked as being of type socket).   Linux  also  supports  an  abstract
20       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 sockets support passing file descriptors or process credentials to
31       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  sizeof(sa_family_t) + strlen(sun_path) + 1, and sun_path
51          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').  All of the remaining bytes
61          in sun_path define the "name" of the socket.   (Null  bytes  in  the
62          name have no special significance.)  The name has no connection with
63          file system pathnames.  The socket's address in  this  namespace  is
64          given  by the rest of the bytes in sun_path.  When the address of an
65          abstract socket is returned by getsockname(2),  getpeername(2),  and
66          accept(2),  its  length  is sizeof(struct sockaddr_un), and sun_path
67          contains the abstract name.  The abstract socket namespace is a non-
68          portable Linux extension.
69
70   Socket Options
71       For  historical  reasons  these  socket  options  are  specified with a
72       SOL_SOCKET type even though they are AF_UNIX specific.  They can be set
73       with setsockopt(2) and read with getsockopt(2) by specifying SOL_SOCKET
74       as the socket family.
75
76       SO_PASSCRED
77              Enables the receiving of the credentials of the sending  process
78              ancillary  message.   When  this option is set and the socket is
79              not yet connected a unique name in the abstract  namespace  will
80              be generated automatically.  Expects an integer boolean flag.
81
82   Sockets API
83       The  following  paragraphs  describe domain-specific details and unsup‐
84       ported features of the sockets API for Unix domain sockets on Linux.
85
86       Unix domain sockets do not support the transmission of out-of-band data
87       (the MSG_OOB flag for send(2) and recv(2)).
88
89       The send(2) MSG_MORE flag is not supported by Unix domain sockets.
90
91       The  use of MSG_TRUNC in the flags argument of recv(2) is not supported
92       by Unix domain sockets.
93
94       The SO_SNDBUF socket option does have an effect for Unix  domain  sock‐
95       ets,  but  the  SO_RCVBUF  option  does not.  For datagram sockets, the
96       SO_SNDBUF value imposes an upper limit on the size  of  outgoing  data‐
97       grams.   This limit is calculated as the doubled (see socket(7)) option
98       value less 32 bytes used for overhead.
99
100   Ancillary Messages
101       Ancillary data is sent and received using  sendmsg(2)  and  recvmsg(2).
102       For  historical  reasons  the  ancillary message types listed below are
103       specified with a SOL_SOCKET type even though they are AF_UNIX specific.
104       To  send  them  set  the  cmsg_level  field  of  the  struct cmsghdr to
105       SOL_SOCKET and the cmsg_type field to the type.  For  more  information
106       see cmsg(3).
107
108       SCM_RIGHTS
109              Send  or  receive  a  set  of open file descriptors from another
110              process.  The data portion contains an integer array of the file
111              descriptors.   The passed file descriptors behave as though they
112              have been created with dup(2).
113
114       SCM_CREDENTIALS
115              Send or receive Unix credentials.  This can be used for  authen‐
116              tication.   The  credentials are passed as a struct ucred ancil‐
117              lary message.  Thus structure is defined  in  <sys/socket.h>  as
118              follows:
119
120                  struct ucred {
121                      pid_t pid;    /* process ID of the sending process */
122                      uid_t uid;    /* user ID of the sending process */
123                      gid_t gid;    /* group ID of the sending process */
124                  };
125
126              Since  glibc  2.8,  the  _GNU_SOURCE  feature test macro must be
127              defined in order to obtain the definition of this structure.
128
129              The credentials which the sender specifies are  checked  by  the
130              kernel.   A process with effective user ID 0 is allowed to spec‐
131              ify values that do not match its own.  The sender  must  specify
132              its own process ID (unless it has the capability CAP_SYS_ADMIN),
133              its user ID, effective user ID, or saved set-user-ID (unless  it
134              has  CAP_SETUID), and its group ID, effective group ID, or saved
135              set-group-ID (unless it has CAP_SETGID).  To  receive  a  struct
136              ucred  message  the  SO_PASSCRED  option  must be enabled on the
137              socket.
138

ERRORS

140       EADDRINUSE
141              Selected local address is already taken or  file  system  socket
142              object already exists.
143
144       ECONNREFUSED
145              connect(2)  called  with  a  socket object that isn't listening.
146              This can happen when the remote socket does  not  exist  or  the
147              filename is not a socket.
148
149       ECONNRESET
150              Remote socket was unexpectedly closed.
151
152       EFAULT User memory address was not valid.
153
154       EINVAL Invalid  argument passed.  A common cause is the missing setting
155              of AF_UNIX in the sun_type field  of  passed  addresses  or  the
156              socket being in an invalid state for the applied operation.
157
158       EISCONN
159              connect(2)  called  on  an  already connected socket or a target
160              address was specified on a connected socket.
161
162       ENOMEM Out of memory.
163
164       ENOTCONN
165              Socket operation needs a target address, but the socket  is  not
166              connected.
167
168       EOPNOTSUPP
169              Stream  operation  called on non-stream oriented socket or tried
170              to use the out-of-band data option.
171
172       EPERM  The sender passed invalid credentials in the struct ucred.
173
174       EPIPE  Remote socket was closed on a stream socket.  If enabled, a SIG‐
175              PIPE  is  sent  as  well.   This  can  be avoided by passing the
176              MSG_NOSIGNAL flag to sendmsg(2) or recvmsg(2).
177
178       EPROTONOSUPPORT
179              Passed protocol is not AF_UNIX.
180
181       EPROTOTYPE
182              Remote socket does not match the local socket  type  (SOCK_DGRAM
183              vs.  SOCK_STREAM)
184
185       ESOCKTNOSUPPORT
186              Unknown socket type.
187
188       Other  errors  can  be  generated by the generic socket layer or by the
189       file system while generating a file  system  socket  object.   See  the
190       appropriate manual pages for more information.
191

VERSIONS

193       SCM_CREDENTIALS  and  the abstract namespace were introduced with Linux
194       2.2 and should not be used in  portable  programs.   (Some  BSD-derived
195       systems also support credential passing, but the implementation details
196       differ.)
197

NOTES

199       In the Linux implementation, sockets which are visible in the file sys‐
200       tem  honor  the permissions of the directory they are in.  Their owner,
201       group and their permissions can be changed.  Creation of a  new  socket
202       will  fail if the process does not have write and search (execute) per‐
203       mission on the directory the socket is created in.  Connecting  to  the
204       socket  object  requires  read/write permission.  This behavior differs
205       from many BSD-derived systems which ignore permissions for  Unix  sock‐
206       ets.  Portable programs should not rely on this feature for security.
207
208       Binding to a socket with a filename creates a socket in the file system
209       that must be deleted by the caller when it is no longer  needed  (using
210       unlink(2)).   The  usual  Unix close-behind semantics apply; the socket
211       can be unlinked at any time and will be finally removed from  the  file
212       system when the last reference to it is closed.
213
214       To pass file descriptors or credentials over a SOCK_STREAM, you need to
215       send or receive at least one byte of non-ancillary  data  in  the  same
216       sendmsg(2) or recvmsg(2) call.
217
218       Unix  domain  stream  sockets  do not support the notion of out-of-band
219       data.
220

EXAMPLE

222       See bind(2).
223

SEE ALSO

225       recvmsg(2), sendmsg(2), socket(2),  socketpair(2),  cmsg(3),  capabili‐
226       ties(7), credentials(7), socket(7)
227

COLOPHON

229       This  page  is  part of release 3.22 of the Linux man-pages project.  A
230       description of the project, and information about reporting  bugs,  can
231       be found at http://www.kernel.org/doc/man-pages/.
232
233
234
235Linux                             2008-12-01                           UNIX(7)
Impressum