Penguin
Recent Changes
Annotated edit history of unix(7) version 2, including all changes. View license author blame.
Rev Author # Line
1 perry 1 UNIX
2 !!!UNIX
3 NAME
4 SYNOPSIS
5 DESCRIPTION
6 ADDRESS FORMAT
7 SOCKET OPTIONS
8 ANCILLARY MESSAGES
9 VERSIONS
10 NOTES
11 ERRORS
12 SEE ALSO
13 CREDITS
14 ----
15 !!NAME
16
17
18 unix, PF_UNIX, AF_UNIX, PF_LOCAL, AF_LOCAL - Sockets for local interprocess communication.
19 !!SYNOPSIS
20
21
22 __#include __
23 #include __
24
25
26 ''unix_socket'' __= socket(PF_UNIX, type, 0);__''
27 error'' __= socketpair(PF_UNIX, type, 0, int
28 *__''sv''__);__
29 !!DESCRIPTION
30
31
32 The __PF_UNIX__ (also known as __PF_LOCAL__) socket
33 family is used to communicate between processes on the same
34 machine efficiently. Unix sockets can be either anonymous
35 (created by socketpair(2)) or associated with a file
36 of socket type. Linux also supports an abstract namespace
37 which is independent of the file system.
38
39
40 Valid types are __SOCK_STREAM__ for a stream oriented
41 socket and __SOCK_DGRAM__ for a datagram oriented socket
42 that preserves message boundaries. Unix sockets are always
43 reliable and don't reorder datagrams.
44
45
46 Unix sockets support passing file descriptors or process
47 credentials to other processes as ancillary data to
48 datagrams.
49 !!ADDRESS FORMAT
50
51
52 A unix address is defined as a filename in the filesystem or
53 as a unique string in the abstract namespace. Sockets
54 created by socketpair(2) are anonymous. For
55 non-anonymous sockets the target address can be set using
56 connect(2). The local address can be set using
57 bind(2). When a socket is connected and it doesn't
58 already have a local address a unique address in the
59 abstract namespace will be generated
60 automatically.
61
62
63 #define UNIX_PATH_MAX 108
64 struct sockaddr_un {
65 sa_family_t sun_family; /* AF_UNIX */
66 char sun_path[[UNIX_PATH_MAX]; /* pathname */
67 };
68
69
70 __sun_family__ always contains __AF_UNIX__.
71 __sun_path__ contains the zero-terminated pathname of the
72 socket in the file system. If __sun_path__ starts with a
73 zero byte it refers to the abstract namespace maintained by
74 the Unix protocol module. The socket's address in this
75 namespace is given by the rest of the bytes in
76 __sun_path__. Note that names in the abstract namespace
77 are not zero-terminated.
78 !!SOCKET OPTIONS
79
80
81 For historical reasons these socket options are specified
82 with a SOL_SOCKET type even though they are PF_UNIX
83 specific. They can be set with setsockopt(2) and read
84 with getsockopt(2) by specifying SOL_SOCKET as the
85 socket family.
86
87
88 __SO_PASSCRED__ enables the receiving of the credentials
89 of the sending process ancillary message. When this option
90 is set and the socket is not connected yet an unique name in
91 the abstract namespace will be generated automatically.
92 Expects an integer boolean flag.
93 !!ANCILLARY MESSAGES
94
95
96 For historical reasons these ancillary message type are
97 specified with a SOL_SOCKET type even though they are
98 PF_UNIX specific. To send them set the __cmsg_level__
99 field of the struct __cmsghdr__ to SOL_SOCKET and the
100 __cmsg_type__ field to the type. For more information see
101 cmsg(3).
102
103
104 __SCM_RIGHTS__
105
106
107 Send or receive a set of open file descriptors from another
108 process. The data portion contains a integer array of the
109 file descriptors. The passed file descriptors behave as like
110 they have been created with dup(2).
111
112
113 __SCM_CREDENTIALS__
114
115
116 Send or receive unix credentials. This can be used for
117 authentication. The credentials are passed as a __struct
118 ucred__ ancillary message.
119
120
121 struct ucred {
122 pid_t pid; /* process id of the sending process */
123 uid_t uid; /* user id of the sending process */
124 gid_t gid; /* group id of the sending process */
125 };
126
127
128 The credentials which the sender specifies are checked by
129 the kernel. A process with effective user id 0 is allowed to
130 specify values that do not match his own. The sender must
131 specify its own process id (unless it has
132 __CAP_SYS_ADMIN__), its user id, effective user id or set
133 user id (unless it has __CAP_SETUID__), and its group id,
134 effective group id or set group id (unless it has
135 __CAP_SETGID__). To receive a __struct ucred__ message
136 the __SO_PASSCRED__ option must be enabled on the
137 socket.
138 !!VERSIONS
139
140
141 __SCM_CREDENTIALS__ and the abstract namespace were
142 introduced with Linux 2.2 and should not be used in portable
143 programs.
144 !!NOTES
145
146
147 In the Linux implementation, sockets which are visible in
148 the filesystem honour the permissions of the directory they
149 are in. Their owner, group and their permissions can be
150 changed. Creation of a new socket will fail if the process
151 does not have write and search (execute) permission on the
152 directory the socket is created in. Connecting to the socket
153 object requires read/write permission. This behavior differs
154 from many BSD derived systems which ignore permissions for
155 Unix sockets. Portable programs should not rely on this
156 feature for security.
157
158
159 Binding to a socket with a filename creates a socket in the
160 file system that must be deleted by the caller when it is no
161 longer needed (using unlink(2)). The usual Unix
162 close-behind semantics apply; the socket can be unlinked at
163 any time and will be finally removed from the file system
164 when the last reference to it is closed.
165
166
167 To pass file descriptors or credentials you need to
168 send/read at least one byte.
169 !!ERRORS
170
171
172 __ENOMEM__
173
174
175 Out of memory.
176
177
178 __ECONNREFUSED__
179
180
181 connect(2) called with a socket object that isn't
182 listening. This can happen when the remote socket does not
183 exist or the filename is not a socket.
184
185
186 __EINVAL__
187
188
189 Invalid argument passed. A common cause is the missing
190 setting of AF_UNIX in the sun_type field of passed addresses
191 or the socket being in an invalid state for the applied
192 operation.
193
194
195 __EOPNOTSUPP__
196
197
198 Stream operation called on non-stream oriented socket or
199 tried to use the out-of-band data option.
200
201
202 __EPROTONOSUPPORT__
203
204
205 Passed protocol is not PF_UNIX.
206
207
208 __ESOCKTNOSUPPORT__
209
210
211 Unknown socket type.
212
213
214 __EPROTOTYPE__
215
216
217 Remote socket does not match the local socket type
218 (SOCK_DGRAM vs. SOCK_STREAM)
219
220
221 __EADDRINUSE__
222
223
224 Selected local address is already taken or filesystem socket
225 object already exists.
226
227
228 __EISCONN__
229
230
231 connect(2) called on an already connected socket or a
232 target address was specified on a connected
233 socket.
234
235
236 __ENOTCONN__
237
238
239 Socket operation needs a target address, but the socket is
240 not connected.
241
242
243 __ECONNRESET__
244
245
246 Remote socket was unexpectedly closed.
247
248
249 __EPIPE__
250
251
252 Remote socket was closed on a stream socket. If enabled, a
253 __SIGPIPE__ is sent as well. This can be avoided by
254 passing the __MSG_NOSIGNAL__ flag to sendmsg(2) or
255 recvmsg(2).
256
257
258 __EFAULT__
259
260
261 User memory address was not valid.
262
263
264 __EPERM__
265
266
267 The sender passed invalid credentials in the __struct
268 ucred__.
269
270
271 Other errors can be generated by the generic socket layer or
272 by the filesystem while generating a filesystem socket
273 object. See the appropriate manual pages for more
274 information.
275 !!SEE ALSO
276
277
278 recvmsg(2), sendmsg(2), socket(2),
279 socketpair(2), cmsg(3),
2 StuartYeates 280 socket(7), WhyUnix
1 perry 281 !!CREDITS
282
283
284 This man page was written by Andi Kleen.
285 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.