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.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 276