]>
Commit | Line | Data |
---|---|---|
fea681da MK |
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 | .\" | |
305a0578 | 7 | .\" Modified, 2003-12-02, Michael Kerrisk, <mtk-manpages@gmx.net> |
fea681da | 8 | .\" Modified, 2003-09-23, Adam Langley |
305a0578 | 9 | .\" Modified, 2004-05-27, Michael Kerrisk, <mtk-manpages@gmx.net> |
fea681da MK |
10 | .\" Added SOCK_SEQPACKET |
11 | .\" | |
69289f8a | 12 | .TH UNIX 7 2004-05-27 "Linux" "Linux Programmer's Manual" |
fea681da | 13 | .SH NAME |
c13182ef | 14 | unix, PF_UNIX, AF_UNIX, PF_LOCAL, AF_LOCAL \- Sockets for local |
35478399 | 15 | interprocess communication |
fea681da MK |
16 | .SH SYNOPSIS |
17 | .B #include <sys/socket.h> | |
18 | .br | |
19 | .B #include <sys/un.h> | |
20 | ||
21 | .IB unix_socket " = socket(PF_UNIX, type, 0);" | |
22 | .br | |
23 | .IB error " = socketpair(PF_UNIX, type, 0, int *" sv ");" | |
fea681da MK |
24 | .SH DESCRIPTION |
25 | The | |
26 | .B PF_UNIX | |
27 | (also known as | |
28 | .BR PF_LOCAL ) | |
29 | socket family is used to communicate between processes on the same machine | |
c13182ef MK |
30 | efficiently. |
31 | Unix sockets can be either anonymous (created by | |
fea681da | 32 | .BR socketpair (2)) |
c13182ef | 33 | or associated with a file of type socket. |
fea681da MK |
34 | Linux also supports an abstract namespace which is independent of the |
35 | file system. | |
36 | ||
37 | Valid types are: | |
38 | .BR SOCK_STREAM , | |
39 | for a stream-oriented socket and | |
40 | .BR SOCK_DGRAM , | |
41 | for a datagram-oriented socket that preserves message boundaries | |
42 | (as on most Unix implementations, Unix domain datagram | |
43 | sockets are always reliable and don't reorder datagrams); | |
44 | and (since kernel 2.6.4) | |
45 | .BR SOCK_SEQPACKET , | |
46 | for a connection-oriented socket that preserves message boundaries | |
c13182ef | 47 | and delivers messages in the order that they were sent. |
fea681da | 48 | |
c13182ef | 49 | Unix sockets support passing file descriptors or process credentials |
56185b42 | 50 | to other processes using ancillary data. |
2b2581ee | 51 | .SS Address Format |
c13182ef MK |
52 | A Unix address is defined as a filename in the filesystem or |
53 | as a unique string in the abstract namespace. | |
54 | Sockets created by | |
fea681da | 55 | .BR socketpair (2) |
c13182ef MK |
56 | are anonymous. |
57 | For non-anonymous sockets the target address can be set | |
fea681da | 58 | using |
c13182ef | 59 | .BR connect (2). |
fea681da | 60 | The local address can be set using |
c13182ef | 61 | .BR bind (2). |
fea681da | 62 | When a socket is connected and it doesn't already have a local address a |
c13182ef | 63 | unique address in the abstract namespace will be generated automatically. |
fea681da | 64 | |
87866492 | 65 | .in +0.25i |
fea681da | 66 | .nf |
87866492 | 67 | #define UNIX_PATH_MAX 108 |
fea681da | 68 | |
fea681da | 69 | struct sockaddr_un { |
87866492 MK |
70 | sa_family_t sun_family; /* AF_UNIX */ |
71 | char sun_path[UNIX_PATH_MAX]; /* pathname */ | |
fea681da MK |
72 | }; |
73 | .fi | |
87866492 | 74 | .in -0.25i |
fea681da | 75 | |
c13182ef | 76 | .B sun_family |
fea681da MK |
77 | always contains |
78 | .BR AF_UNIX . | |
79 | .B sun_path | |
80 | contains the zero-terminated pathname of the socket in the file system. | |
c13182ef | 81 | If |
fea681da | 82 | .B sun_path |
c13182ef | 83 | starts with a null byte (''\0'), |
28d88c17 | 84 | then it refers to the abstract namespace maintained by |
fea681da | 85 | the Unix protocol module. |
c13182ef | 86 | The socket's address in this namespace is given by the rest of the |
56185b42 | 87 | bytes in |
fea681da MK |
88 | .BR sun_path . |
89 | Note that names in the abstract namespace are not zero-terminated. | |
2b2581ee | 90 | .SS Socket Options |
c13182ef | 91 | For historical reasons these socket options are specified with a |
fea681da | 92 | SOL_SOCKET type even though they are PF_UNIX specific. |
c13182ef | 93 | They can be set with |
fea681da | 94 | .BR setsockopt (2) |
c13182ef | 95 | and read with |
fea681da MK |
96 | .BR getsockopt (2) |
97 | by specifying SOL_SOCKET as the socket family. | |
98 | .TP | |
99 | .B SO_PASSCRED | |
c13182ef MK |
100 | Enables the receiving of the credentials of the sending process |
101 | ancillary message. | |
56185b42 | 102 | When this option is set and the socket is not yet connected |
fea681da | 103 | a unique name in the abstract namespace will be generated automatically. |
c13182ef | 104 | Expects an integer boolean flag. |
2b2581ee | 105 | .SS (Un)supported Features |
c13182ef | 106 | The following paragraphs describe domain-specific details and |
f406c335 MK |
107 | unsupported features of the sockets API for Unix domain sockets on Linux. |
108 | ||
c13182ef MK |
109 | Unix domain sockets do not support the transmission of |
110 | out-of-band data (the | |
86097253 MK |
111 | .B MSG_OOB |
112 | flag for | |
113 | .BR send (2) | |
114 | and | |
115 | .BR recv (2)). | |
116 | ||
117 | The | |
f406c335 | 118 | .BR send (2) |
86097253 | 119 | .B MSG_MORE |
4291b3e4 | 120 | flag is not supported by Unix domain sockets. |
86097253 | 121 | |
f406c335 MK |
122 | The |
123 | .B SO_SNDBUF | |
4291b3e4 | 124 | socket option does have an effect for Unix domain sockets, but the |
f406c335 MK |
125 | .B SO_RCVBUF |
126 | option does not. | |
127 | For datagram sockets, the | |
128 | .B SO_SNDBUF | |
129 | value imposes an upper limit on the size of outgoing datagrams. | |
130 | This limit is calculated as the doubled (see | |
131 | .BR socket (7)) | |
132 | option value less 32 bytes used for overhead. | |
2b2581ee | 133 | .SS Ancillary Messages |
fea681da MK |
134 | Ancillary data is sent and received using |
135 | .BR sendmsg (2) | |
136 | and | |
137 | .BR recvmsg (2). | |
138 | For historical reasons the ancillary message types listed below | |
c13182ef | 139 | are specified with a SOL_SOCKET type even though they are PF_UNIX |
56185b42 | 140 | specific. |
fea681da MK |
141 | To send them set the |
142 | .B cmsg_level | |
c13182ef | 143 | field of the struct |
fea681da | 144 | .B cmsghdr |
c13182ef MK |
145 | to SOL_SOCKET and the |
146 | .B cmsg_type | |
147 | field to the type. | |
148 | For more information see | |
149 | .BR cmsg (3). | |
fea681da MK |
150 | .TP |
151 | .B SCM_RIGHTS | |
c13182ef | 152 | Send or receive a set of open file descriptors from another process. |
fea681da MK |
153 | The data portion contains an integer array of the file descriptors. |
154 | The passed file descriptors behave as though they have been created with | |
155 | .BR dup (2). | |
fea681da MK |
156 | .TP |
157 | .B SCM_CREDENTIALS | |
c13182ef MK |
158 | Send or receive Unix credentials. |
159 | This can be used for authentication. | |
160 | The credentials are passed as a | |
8478ee02 | 161 | .I struct ucred |
fea681da MK |
162 | ancillary message. |
163 | ||
87866492 | 164 | .in +0.25i |
fea681da | 165 | .nf |
fea681da | 166 | struct ucred { |
c13182ef MK |
167 | pid_t pid; /* process ID of the sending process */ |
168 | uid_t uid; /* user ID of the sending process */ | |
169 | gid_t gid; /* group ID of the sending process */ | |
fea681da MK |
170 | }; |
171 | .fi | |
87866492 | 172 | .in -0.25i |
c13182ef | 173 | |
fea681da | 174 | The credentials which the sender specifies are checked by the kernel. |
c13182ef MK |
175 | A process with effective user ID 0 is allowed to specify values that do |
176 | not match its own. | |
fea681da MK |
177 | The sender must specify its own process ID (unless it has the capability |
178 | .BR CAP_SYS_ADMIN ), | |
c7400a2c | 179 | its user ID, effective user ID, or saved set-user-ID (unless it has |
fea681da | 180 | .BR CAP_SETUID ), |
c13182ef | 181 | and its group ID, effective group ID, or saved set-group-ID |
56185b42 | 182 | (unless it has |
fea681da MK |
183 | .BR CAP_SETGID ). |
184 | To receive a | |
8478ee02 | 185 | .I struct ucred |
fea681da | 186 | message the |
c13182ef | 187 | .B SO_PASSCRED |
fea681da | 188 | option must be enabled on the socket. |
fea681da MK |
189 | .SH ERRORS |
190 | .TP | |
191 | .B ENOMEM | |
192 | Out of memory. | |
193 | .TP | |
194 | .B ECONNREFUSED | |
195 | .BR connect (2) | |
c13182ef MK |
196 | called with a socket object that isn't listening. |
197 | This can happen when | |
fea681da MK |
198 | the remote socket does not exist or the filename is not a socket. |
199 | .TP | |
200 | .B EINVAL | |
c13182ef MK |
201 | Invalid argument passed. |
202 | A common cause is the missing setting of AF_UNIX | |
203 | in the | |
204 | .I sun_type | |
205 | field of passed addresses or the socket being in an | |
56185b42 | 206 | invalid state for the applied operation. |
fea681da MK |
207 | .TP |
208 | .B EOPNOTSUPP | |
c13182ef | 209 | Stream operation called on non-stream oriented socket or tried to |
fea681da MK |
210 | use the out-of-band data option. |
211 | .TP | |
212 | .B EPROTONOSUPPORT | |
213 | Passed protocol is not PF_UNIX. | |
214 | .TP | |
215 | .B ESOCKTNOSUPPORT | |
216 | Unknown socket type. | |
c13182ef | 217 | .TP |
fea681da MK |
218 | .B EPROTOTYPE |
219 | Remote socket does not match the local socket type (SOCK_DGRAM vs. | |
220 | SOCK_STREAM) | |
221 | .TP | |
222 | .B EADDRINUSE | |
c13182ef MK |
223 | Selected local address is already taken or filesystem socket |
224 | object already exists. | |
fea681da MK |
225 | .TP |
226 | .B EISCONN | |
227 | .BR connect (2) | |
228 | called on an already connected socket or a target address was | |
229 | specified on a connected socket. | |
230 | .TP | |
231 | .B ENOTCONN | |
232 | Socket operation needs a target address, but the socket is not connected. | |
233 | .TP | |
234 | .B ECONNRESET | |
235 | Remote socket was unexpectedly closed. | |
236 | .TP | |
237 | .B EPIPE | |
c13182ef MK |
238 | Remote socket was closed on a stream socket. |
239 | If enabled, a | |
240 | .B SIGPIPE | |
241 | is sent as well. | |
242 | This can be avoided by passing the | |
fea681da MK |
243 | .B MSG_NOSIGNAL |
244 | flag to | |
245 | .BR sendmsg (2) | |
246 | or | |
247 | .BR recvmsg (2). | |
248 | .TP | |
249 | .B EFAULT | |
250 | User memory address was not valid. | |
251 | .TP | |
252 | .B EPERM | |
253 | The sender passed invalid credentials in the | |
8478ee02 | 254 | .IR "struct ucred" . |
fea681da | 255 | .PP |
c13182ef MK |
256 | Other errors can be generated by the generic socket layer or |
257 | by the filesystem while generating a filesystem socket object. | |
258 | See the appropriate manual pages for more information. | |
2b2581ee MK |
259 | .SH VERSIONS |
260 | .B SCM_CREDENTIALS | |
261 | and the abstract namespace were introduced with Linux 2.2 and should not | |
262 | be used in portable programs. | |
263 | (Some BSD-derived systems also support credential passing, | |
264 | but the implementation details differ.) | |
265 | .SH NOTES | |
266 | In the Linux implementation, sockets which are visible in the | |
d9bfdb9c | 267 | filesystem honor the permissions of the directory they are in. |
2b2581ee MK |
268 | Their owner, group and their permissions can be changed. |
269 | Creation of a new socket will fail if the process does not have write and | |
270 | search (execute) permission on the directory the socket is created in. | |
271 | Connecting to the socket object requires read/write permission. | |
272 | This behavior differs from many BSD-derived systems which | |
273 | ignore permissions for Unix sockets. | |
274 | Portable programs should not rely on | |
275 | this feature for security. | |
276 | ||
277 | Binding to a socket with a filename creates a socket | |
278 | in the file system that must be deleted by the caller when it is no | |
279 | longer needed (using | |
280 | .BR unlink (2)). | |
281 | The usual Unix close-behind semantics apply; the socket can be unlinked | |
282 | at any time and will be finally removed from the file system when the last | |
283 | reference to it is closed. | |
284 | ||
285 | To pass file descriptors or credentials over a SOCK_STREAM, you need | |
286 | to send or receive at least one byte of non-ancillary data in the same | |
287 | .BR sendmsg (2) | |
288 | or | |
289 | .BR recvmsg (2) | |
290 | call. | |
291 | ||
292 | Unix domain stream sockets do not support the notion of out-of-band data. | |
a7413163 | 293 | .SH EXAMPLE |
988db661 | 294 | See |
a7413163 | 295 | .BR bind (2). |
fea681da MK |
296 | .SH "SEE ALSO" |
297 | .BR recvmsg (2), | |
298 | .BR sendmsg (2), | |
299 | .BR socket (2), | |
300 | .BR socketpair (2), | |
301 | .BR cmsg (3), | |
302 | .BR capabilities (7), | |
53a1443c | 303 | .BR credentials (7), |
fea681da | 304 | .BR socket (7) |