1UNIX(7) Linux Programmer's Manual UNIX(7)
2
6 unix, AF_UNIX, AF_LOCAL - Sockets for local interprocess communication
7
9 #include <sys/socket.h>
10 #include <sys/un.h>
11 unix_socket = socket(AF_UNIX, type, 0);
13 error = socketpair(AF_UNIX, type, 0, int *sv);
14
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 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 Unix sockets support passing file descriptors or process credentials to
31 other processes using ancillary data.
32 Address Format
34 A Unix domain socket address is represented in the following structure:
35 #define UNIX_PATH_MAX 108
37 struct sockaddr_un {
39 sa_family_t sun_family; /* AF_UNIX */
40 char sun_path[UNIX_PATH_MAX]; /* pathname */
41 };
42 sun_family always contains AF_UNIX.
44 Three types of address are distinguished in this structure:
46 * 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 * 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 * 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 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 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 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 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 The send(2) MSG_MORE flag is not supported by Unix domain sockets.
90 The use of MSG_TRUNC in the flags argument of recv(2) is not supported
92 by Unix domain sockets.
93 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 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 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 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 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 Since glibc 2.8, the _GNU_SOURCE feature test macro must be
127 defined in order to obtain the definition of this structure.
128 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
140 EADDRINUSE
141 Selected local address is already taken or file system socket
142 object already exists.
143 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 ECONNRESET
150 Remote socket was unexpectedly closed.
151 EFAULT User memory address was not valid.
153 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 EISCONN
159 connect(2) called on an already connected socket or a target
160 address was specified on a connected socket.
161 ENOMEM Out of memory.
163 ENOTCONN
165 Socket operation needs a target address, but the socket is not
166 connected.
167 EOPNOTSUPP
169 Stream operation called on non-stream oriented socket or tried
170 to use the out-of-band data option.
171 EPERM The sender passed invalid credentials in the struct ucred.
173 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 EPROTONOSUPPORT
179 Passed protocol is not AF_UNIX.
180 EPROTOTYPE
182 Remote socket does not match the local socket type (SOCK_DGRAM
183 vs. SOCK_STREAM)
184 ESOCKTNOSUPPORT
186 Unknown socket type.
187 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
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
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 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 To pass file descriptors or credentials over a SOCK_STREAM, you need to
215 send or receive at least one byte of nonancillary data in the same
216 sendmsg(2) or recvmsg(2) call.
217 Unix domain stream sockets do not support the notion of out-of-band
219 data.
220
222 See bind(2).
223
225 recvmsg(2), sendmsg(2), socket(2), socketpair(2), cmsg(3), capabili‐
226 ties(7), credentials(7), socket(7)
227
229 This page is part of release 3.25 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/.
232Linux 2008-12-01 UNIX(7)