1UNIX(7) Linux Programmer's Manual UNIX(7)
2
6 unix - 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 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 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 domain sockets support passing file descriptors or process creden‐
31 tials to 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 offsetof(struct sockaddr_un, sun_path) + strlen(sun_path)
51 + 1, and sun_path 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'). 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 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 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 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 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 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 The send(2) MSG_MORE flag is not supported by UNIX domain sockets.
102 The use of MSG_TRUNC in the flags argument of recv(2) is not supported
104 by UNIX domain sockets.
105 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 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 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 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 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 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 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 Ioctls
153 The following ioctl(2) calls return information in value. The correct
154 syntax is:
155 int value;
157 error = ioctl(unix_socket, ioctl_type, &value);
158 ioctl_type can be:
160 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
169 EADDRINUSE
170 The specified local address is already in use or the file system
171 socket object already exists.
172 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 ECONNRESET
179 Remote socket was unexpectedly closed.
180 EFAULT User memory address was not valid.
182 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 EISCONN
189 connect(2) called on an already connected socket or a target
190 address was specified on a connected socket.
191 ENOENT The pathname in the remote address specified to connect(2) did
193 not exist.
194 ENOMEM Out of memory.
196 ENOTCONN
198 Socket operation needs a target address, but the socket is not
199 connected.
200 EOPNOTSUPP
202 Stream operation called on non-stream oriented socket or tried
203 to use the out-of-band data option.
204 EPERM The sender passed invalid credentials in the struct ucred.
206 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 EPROTONOSUPPORT
212 Passed protocol is not AF_UNIX.
213 EPROTOTYPE
215 Remote socket does not match the local socket type (SOCK_DGRAM
216 versus SOCK_STREAM)
217 ESOCKTNOSUPPORT
219 Unknown socket type.
220 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
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
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 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 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 UNIX domain stream sockets do not support the notion of out-of-band
253 data.
254
256 See bind(2).
257 For an example of the use of SCM_RIGHTS see cmsg(3).
259
261 recvmsg(2), sendmsg(2), socket(2), socketpair(2), cmsg(3), capabili‐
262 ties(7), credentials(7), socket(7)
263
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/.
268Linux 2012-05-10 UNIX(7)