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$ 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.Ar sun_path 98field must be terminated by a NUL character to be used with 99.Fn SUN_LEN , 100but the terminating NUL is 101.Em not 102part of the address. 103.Pp 104The 105.Ux Ns -domain 106protocol family does not support broadcast addressing or any form 107of 108.Dq wildcard 109matching on incoming messages. 110All addresses are absolute- or relative-pathnames 111of other 112.Ux Ns -domain 113sockets. 114Normal file system access-control mechanisms are also 115applied when referencing pathnames; e.g., the destination 116of a 117.Xr connect 2 118or 119.Xr sendto 2 120must be writable. 121.Sh PROTOCOLS 122The 123.Ux Ns -domain 124protocol family is comprised of simple 125transport protocols that support the 126.Dv SOCK_STREAM 127and 128.Dv SOCK_DGRAM 129abstractions. 130.Dv SOCK_STREAM 131sockets also support the communication of 132.Ux 133file descriptors through the use of the 134.Va msg_control 135field in the 136.Fa msg 137argument to 138.Xr sendmsg 2 139and 140.Xr recvmsg 2 . 141.Pp 142Any valid descriptor may be sent in a message. 143The file descriptor(s) to be passed are described using a 144.Vt "struct cmsghdr" 145that is defined in the include file 146.In sys/socket.h . 147The type of the message is 148.Dv SCM_RIGHTS , 149and the data portion of the messages is an array of integers 150representing the file descriptors to be passed. 151The number of descriptors being passed is defined 152by the length field of the message; 153the length field is the sum of the size of the header 154plus the size of the array of file descriptors. 155.Pp 156The received descriptor is a 157.Em duplicate 158of the sender's descriptor, as if it were created with a call to 159.Xr dup 2 . 160Per-process descriptor flags, set with 161.Xr fcntl 2 , 162are 163.Em not 164passed to a receiver. 165Descriptors that are awaiting delivery, or that are 166purposely not received, are automatically closed by the system 167when the destination socket is closed. 168.Pp 169The effective credentials (i.e., the user ID and group list) of a 170peer on a 171.Dv SOCK_STREAM 172socket may be obtained using the 173.Dv LOCAL_PEERCRED 174socket option. 175This may be used by a server to obtain and verify the credentials of 176its client, and vice versa by the client to verify the credentials 177of the server. 178These will arrive in the form of a filled in 179.Vt "struct xucred" 180(defined in 181.In sys/ucred.h ) . 182The credentials presented to the server (the 183.Xr listen 2 184caller) are those of the client when it called 185.Xr connect 2 ; 186the credentials presented to the client (the 187.Xr connect 2 188caller) are those of the server when it called 189.Xr listen 2 . 190This mechanism is reliable; there is no way for either party to influence 191the credentials presented to its peer except by calling the appropriate 192system call (e.g., 193.Xr connect 2 194or 195.Xr listen 2 ) 196under different effective credentials. 197.Pp 198 199.Tn UNIX 200domain sockets support a number of socket options which can be set with 201.Xr setsockopt 2 202and tested with 203.Xr getsockopt 2 : 204.Bl -tag -width ".Dv LOCAL_CONNWAIT" 205.It Dv LOCAL_CREDS 206This option may be enabled on a 207.Dv SOCK_DGRAM 208or a 209.Dv SOCK_STREAM 210socket. This option provides a mechanism for the receiver to 211receive the credentials of the process as a 212.Xr recvmsg 2 213control message. The msg_control field in the msghdr structure points 214to a buffer that contains a cmsghdr structure followed by a variable 215length sockcred structure, defined in 216.Pa \*[Lt]sys/socket.h\*[Gt] 217as follows: 218.Bd -literal 219struct sockcred { 220 id_t sc_uid; /* real user id */ 221 uid_t sc_euid; /* effective user id */ 222 gid_t sc_gid; /* real group id */ 223 gid_t sc_egid; /* effective group id */ 224 int sc_ngroups; /* number of supplemental groups */ 225 gid_t sc_groups[1]; /* variable length */ 226}; 227.Ed 228.Pp 229The 230.Fn SOCKCREDSIZE 231macro computes the size of the sockcred structure for a specified number 232of groups. 233The cmsghdr fields have the following values: 234.Bd -literal 235cmsg_len = sizeof(struct cmsghdr) + SOCKCREDSIZE(ngroups) 236cmsg_level = SOL_SOCKET 237cmsg_type = SCM_CREDS 238.Ed 239.It Dv LOCAL_CONNWAIT 240Used with 241.Dv SOCK_STREAM 242sockets, this option causes the 243.Xr connect 2 244function to block until 245.Xr accept 2 246has been called on the listening socket. 247.Sh SEE ALSO 248.Xr socket 2 , 249.Xr intro 4 250.Rs 251.%T "An Introductory 4.3 BSD Interprocess Communication Tutorial" 252.%B PS1 253.%N 7 254.Re 255.Rs 256.%T "An Advanced 4.3 BSD Interprocess Communication Tutorial" 257.%B PS1 258.%N 8 259.Re 260