1.\" Copyright (c) 1991, 1993
2.\" The Regents of the University of California. All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\" notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\" notice, this list of conditions and the following disclaimer in the
11.\" documentation and/or other materials provided with the distribution.
12.\" 3. All advertising materials mentioning features or use of this software
13.\" must display the following acknowledgement:
14.\" This product includes software developed by the University of
15.\" California, Berkeley and its contributors.
16.\" 4. Neither the name of the University nor the names of its contributors
17.\" may be used to endorse or promote products derived from this software
18.\" without specific prior written permission.
19.\"
20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30.\" SUCH DAMAGE.
31.\"
32.\" @(#)unix.4 8.1 (Berkeley) 6/9/93
33.\" $FreeBSD: head/share/man/man4/unix.4 153603 2005-12-21 08:23:04Z maxim $
34.\"
35.Dd July 15, 2001
36.Dt UNIX 4
37.Os
38.Sh NAME
39.Nm unix
40.Nd UNIX-domain protocol family
41.Sh SYNOPSIS
42.In sys/types.h
43.In sys/un.h
44.Sh DESCRIPTION
45The
46.Ux Ns -domain
47protocol family is a collection of protocols
48that provides local (on-machine) interprocess
49communication through the normal
50.Xr socket 2
51mechanisms.
52The
53.Ux Ns -domain
54family supports the
55.Dv SOCK_STREAM
56and
57.Dv SOCK_DGRAM
58socket types and uses
59file system pathnames for addressing.
60.Sh ADDRESSING
61.Ux Ns -domain
62addresses are variable-length file system pathnames of
63at most 104 characters.
64The include file
65.In sys/un.h
66defines this address:
67.Bd -literal -offset indent
68struct sockaddr_un {
69 u_char sun_len;
70 u_char sun_family;
71 char sun_path[104];
72};
73.Ed
74.Pp
75Binding a name to a
76.Ux Ns -domain
77socket with
78.Xr bind 2
79causes a socket file to be created in the file system.
80This file is
81.Em not
82removed when the socket is closed \(em
83.Xr unlink 2
84must be used to remove the file.
85.Pp
86The length of
87.Ux Ns -domain
88address, required by
89.Xr bind 2
90and
91.Xr connect 2 ,
92can be calculated by the macro
93.Fn SUN_LEN
94defined in
95.In sys/un.h .
96The
97.Va sun_path
98field must be terminated by a
99.Dv NUL
100character to be used with
101.Fn SUN_LEN ,
102but the terminating
103.Dv NUL
104is
105.Em not
106part of the address.
107.Pp
108The
109.Ux Ns -domain
110protocol family does not support broadcast addressing or any form
111of
112.Dq wildcard
113matching on incoming messages.
114All addresses are absolute- or relative-pathnames
115of other
116.Ux Ns -domain
117sockets.
118Normal file system access-control mechanisms are also
119applied when referencing pathnames; e.g., the destination
120of a
121.Xr connect 2
122or
123.Xr sendto 2
124must be writable.
125.Sh PROTOCOLS
126The
127.Ux Ns -domain
128protocol family is comprised of simple
129transport protocols that support the
130.Dv SOCK_STREAM
131and
132.Dv SOCK_DGRAM
133abstractions.
134.Dv SOCK_STREAM
135sockets also support the communication of
136.Ux
137file descriptors through the use of the
138.Va msg_control
139field in the
140.Fa msg
141argument to
142.Xr sendmsg 2
143and
144.Xr recvmsg 2 .
145.Pp
146Any valid descriptor may be sent in a message.
147The file descriptor(s) to be passed are described using a
148.Vt "struct cmsghdr"
149that is defined in the include file
150.In sys/socket.h .
151The type of the message is
152.Dv SCM_RIGHTS ,
153and the data portion of the messages is an array of integers
154representing the file descriptors to be passed.
155The number of descriptors being passed is defined
156by the length field of the message;
157the length field is the sum of the size of the header
158plus the size of the array of file descriptors.
159.Pp
160The received descriptor is a
161.Em duplicate
162of the sender's descriptor, as if it were created with a call to
163.Xr dup 2 .
164Per-process descriptor flags, set with
165.Xr fcntl 2 ,
166are
167.Em not
168passed to a receiver.
169Descriptors that are awaiting delivery, or that are
170purposely not received, are automatically closed by the system
171when the destination socket is closed.
172.Pp
173The effective credentials (i.e., the user ID and group list) of a
174peer on a
175.Dv SOCK_STREAM
176socket may be obtained using the
177.Dv LOCAL_PEERCRED
178socket option.
179This may be used by a server to obtain and verify the credentials of
180its client, and vice versa by the client to verify the credentials
181of the server.
182These will arrive in the form of a filled in
183.Vt "struct xucred"
184(defined in
185.In sys/ucred.h ) .
186The credentials presented to the server (the
187.Xr listen 2
188caller) are those of the client when it called
189.Xr connect 2 ;
190the credentials presented to the client (the
191.Xr connect 2
192caller) are those of the server when it called
193.Xr listen 2 .
194This mechanism is reliable; there is no way for either party to influence
195the credentials presented to its peer except by calling the appropriate
196system call (e.g.,
197.Xr connect 2
198or
199.Xr listen 2 )
200under different effective credentials.
201.Pp
202.Tn UNIX
203domain sockets support a number of socket options which can be set with
204.Xr setsockopt 2
205and tested with
206.Xr getsockopt 2 :
207.Bl -tag -width ".Dv LOCAL_CONNWAIT"
208.It Dv LOCAL_CREDS
209This option may be enabled on a
210.Dv SOCK_DGRAM
211or a
212.Dv SOCK_STREAM
213socket.
214This option provides a mechanism for the receiver to
215receive the credentials of the process as a
216.Xr recvmsg 2
217control message.
218The
219.Va msg_control
220field in the
221.Vt msghdr
222structure points to a buffer that contains a
223.Vt cmsghdr
224structure followed by a variable length
225.Vt sockcred
226structure, defined in
227.In sys/socket.h
228as follows:
229.Bd -literal
230struct sockcred {
231 uid_t sc_uid; /* real user id */
232 uid_t sc_euid; /* effective user id */
233 gid_t sc_gid; /* real group id */
234 gid_t sc_egid; /* effective group id */
235 int sc_ngroups; /* number of supplemental groups */
236 gid_t sc_groups[1]; /* variable length */
237};
238.Ed
239.Pp
240The
241.Fn SOCKCREDSIZE
242macro computes the size of the
243.Vt sockcred
244structure for a specified number
245of groups.
246The
247.Vt cmsghdr
248fields have the following values:
249.Bd -literal
250cmsg_len = CMSG_LEN(SOCKCREDSIZE(ngroups))
251cmsg_level = SOL_SOCKET
252cmsg_type = SCM_CREDS
253.Ed
254.It Dv LOCAL_CONNWAIT
255Used with
256.Dv SOCK_STREAM
257sockets, this option causes the
258.Xr connect 2
259function to block until
260.Xr accept 2
261has been called on the listening socket.
262.El
263.Sh SEE ALSO
264.Xr socket 2 ,
265.Xr intro 4
266.Rs
267.%T "An Introductory 4.3 BSD Interprocess Communication Tutorial"
268.%B PS1
269.%N 7
270.Re
271.Rs
272.%T "An Advanced 4.3 BSD Interprocess Communication Tutorial"
273.%B PS1
274.%N 8
275.Re
2.\" The Regents of the University of California. All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\" notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\" notice, this list of conditions and the following disclaimer in the
11.\" documentation and/or other materials provided with the distribution.
12.\" 3. All advertising materials mentioning features or use of this software
13.\" must display the following acknowledgement:
14.\" This product includes software developed by the University of
15.\" California, Berkeley and its contributors.
16.\" 4. Neither the name of the University nor the names of its contributors
17.\" may be used to endorse or promote products derived from this software
18.\" without specific prior written permission.
19.\"
20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30.\" SUCH DAMAGE.
31.\"
32.\" @(#)unix.4 8.1 (Berkeley) 6/9/93
33.\" $FreeBSD: head/share/man/man4/unix.4 153603 2005-12-21 08:23:04Z maxim $
34.\"
35.Dd July 15, 2001
36.Dt UNIX 4
37.Os
38.Sh NAME
39.Nm unix
40.Nd UNIX-domain protocol family
41.Sh SYNOPSIS
42.In sys/types.h
43.In sys/un.h
44.Sh DESCRIPTION
45The
46.Ux Ns -domain
47protocol family is a collection of protocols
48that provides local (on-machine) interprocess
49communication through the normal
50.Xr socket 2
51mechanisms.
52The
53.Ux Ns -domain
54family supports the
55.Dv SOCK_STREAM
56and
57.Dv SOCK_DGRAM
58socket types and uses
59file system pathnames for addressing.
60.Sh ADDRESSING
61.Ux Ns -domain
62addresses are variable-length file system pathnames of
63at most 104 characters.
64The include file
65.In sys/un.h
66defines this address:
67.Bd -literal -offset indent
68struct sockaddr_un {
69 u_char sun_len;
70 u_char sun_family;
71 char sun_path[104];
72};
73.Ed
74.Pp
75Binding a name to a
76.Ux Ns -domain
77socket with
78.Xr bind 2
79causes a socket file to be created in the file system.
80This file is
81.Em not
82removed when the socket is closed \(em
83.Xr unlink 2
84must be used to remove the file.
85.Pp
86The length of
87.Ux Ns -domain
88address, required by
89.Xr bind 2
90and
91.Xr connect 2 ,
92can be calculated by the macro
93.Fn SUN_LEN
94defined in
95.In sys/un.h .
96The
97.Va sun_path
98field must be terminated by a
99.Dv NUL
100character to be used with
101.Fn SUN_LEN ,
102but the terminating
103.Dv NUL
104is
105.Em not
106part of the address.
107.Pp
108The
109.Ux Ns -domain
110protocol family does not support broadcast addressing or any form
111of
112.Dq wildcard
113matching on incoming messages.
114All addresses are absolute- or relative-pathnames
115of other
116.Ux Ns -domain
117sockets.
118Normal file system access-control mechanisms are also
119applied when referencing pathnames; e.g., the destination
120of a
121.Xr connect 2
122or
123.Xr sendto 2
124must be writable.
125.Sh PROTOCOLS
126The
127.Ux Ns -domain
128protocol family is comprised of simple
129transport protocols that support the
130.Dv SOCK_STREAM
131and
132.Dv SOCK_DGRAM
133abstractions.
134.Dv SOCK_STREAM
135sockets also support the communication of
136.Ux
137file descriptors through the use of the
138.Va msg_control
139field in the
140.Fa msg
141argument to
142.Xr sendmsg 2
143and
144.Xr recvmsg 2 .
145.Pp
146Any valid descriptor may be sent in a message.
147The file descriptor(s) to be passed are described using a
148.Vt "struct cmsghdr"
149that is defined in the include file
150.In sys/socket.h .
151The type of the message is
152.Dv SCM_RIGHTS ,
153and the data portion of the messages is an array of integers
154representing the file descriptors to be passed.
155The number of descriptors being passed is defined
156by the length field of the message;
157the length field is the sum of the size of the header
158plus the size of the array of file descriptors.
159.Pp
160The received descriptor is a
161.Em duplicate
162of the sender's descriptor, as if it were created with a call to
163.Xr dup 2 .
164Per-process descriptor flags, set with
165.Xr fcntl 2 ,
166are
167.Em not
168passed to a receiver.
169Descriptors that are awaiting delivery, or that are
170purposely not received, are automatically closed by the system
171when the destination socket is closed.
172.Pp
173The effective credentials (i.e., the user ID and group list) of a
174peer on a
175.Dv SOCK_STREAM
176socket may be obtained using the
177.Dv LOCAL_PEERCRED
178socket option.
179This may be used by a server to obtain and verify the credentials of
180its client, and vice versa by the client to verify the credentials
181of the server.
182These will arrive in the form of a filled in
183.Vt "struct xucred"
184(defined in
185.In sys/ucred.h ) .
186The credentials presented to the server (the
187.Xr listen 2
188caller) are those of the client when it called
189.Xr connect 2 ;
190the credentials presented to the client (the
191.Xr connect 2
192caller) are those of the server when it called
193.Xr listen 2 .
194This mechanism is reliable; there is no way for either party to influence
195the credentials presented to its peer except by calling the appropriate
196system call (e.g.,
197.Xr connect 2
198or
199.Xr listen 2 )
200under different effective credentials.
201.Pp
202.Tn UNIX
203domain sockets support a number of socket options which can be set with
204.Xr setsockopt 2
205and tested with
206.Xr getsockopt 2 :
207.Bl -tag -width ".Dv LOCAL_CONNWAIT"
208.It Dv LOCAL_CREDS
209This option may be enabled on a
210.Dv SOCK_DGRAM
211or a
212.Dv SOCK_STREAM
213socket.
214This option provides a mechanism for the receiver to
215receive the credentials of the process as a
216.Xr recvmsg 2
217control message.
218The
219.Va msg_control
220field in the
221.Vt msghdr
222structure points to a buffer that contains a
223.Vt cmsghdr
224structure followed by a variable length
225.Vt sockcred
226structure, defined in
227.In sys/socket.h
228as follows:
229.Bd -literal
230struct sockcred {
231 uid_t sc_uid; /* real user id */
232 uid_t sc_euid; /* effective user id */
233 gid_t sc_gid; /* real group id */
234 gid_t sc_egid; /* effective group id */
235 int sc_ngroups; /* number of supplemental groups */
236 gid_t sc_groups[1]; /* variable length */
237};
238.Ed
239.Pp
240The
241.Fn SOCKCREDSIZE
242macro computes the size of the
243.Vt sockcred
244structure for a specified number
245of groups.
246The
247.Vt cmsghdr
248fields have the following values:
249.Bd -literal
250cmsg_len = CMSG_LEN(SOCKCREDSIZE(ngroups))
251cmsg_level = SOL_SOCKET
252cmsg_type = SCM_CREDS
253.Ed
254.It Dv LOCAL_CONNWAIT
255Used with
256.Dv SOCK_STREAM
257sockets, this option causes the
258.Xr connect 2
259function to block until
260.Xr accept 2
261has been called on the listening socket.
262.El
263.Sh SEE ALSO
264.Xr socket 2 ,
265.Xr intro 4
266.Rs
267.%T "An Introductory 4.3 BSD Interprocess Communication Tutorial"
268.%B PS1
269.%N 7
270.Re
271.Rs
272.%T "An Advanced 4.3 BSD Interprocess Communication Tutorial"
273.%B PS1
274.%N 8
275.Re