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 March 19, 2013 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 , 56.Dv SOCK_SEQPACKET , 57and 58.Dv SOCK_DGRAM 59socket types and uses 60file system pathnames for addressing. 61.Sh ADDRESSING 62.Ux Ns -domain 63addresses are variable-length file system pathnames of 64at most 104 characters. 65The include file 66.In sys/un.h 67defines this address: 68.Bd -literal -offset indent 69struct sockaddr_un { 70 u_char sun_len; 71 u_char sun_family; 72 char sun_path[104]; 73}; 74.Ed 75.Pp 76Binding a name to a 77.Ux Ns -domain 78socket with 79.Xr bind 2 80causes a socket file to be created in the file system. 81This file is 82.Em not 83removed when the socket is closed \(em 84.Xr unlink 2 85must be used to remove the file. 86.Pp 87The length of 88.Ux Ns -domain 89address, required by 90.Xr bind 2 91and 92.Xr connect 2 , 93can be calculated by the macro 94.Fn SUN_LEN 95defined in 96.In sys/un.h . 97The 98.Va sun_path 99field must be terminated by a 100.Dv NUL 101character to be used with 102.Fn SUN_LEN , 103but the terminating 104.Dv NUL 105is 106.Em not 107part of the address. 108.Pp 109The 110.Ux Ns -domain 111protocol family does not support broadcast addressing or any form 112of 113.Dq wildcard 114matching on incoming messages. 115All addresses are absolute- or relative-pathnames 116of other 117.Ux Ns -domain 118sockets. 119Normal file system access-control mechanisms are also 120applied when referencing pathnames; e.g., the destination 121of a 122.Xr connect 2 123or 124.Xr sendto 2 125must be writable. 126.Sh PASSING FILE DESCRIPTORS 127The 128.Ux Ns -domain 129sockets support the communication of 130.Ux 131file descriptors through the use of the 132.Va msg_control 133field in the 134.Fa msg 135argument to 136.Xr sendmsg 2 137and 138.Xr recvmsg 2 . 139.Pp 140Any valid descriptor may be sent in a message. 141The file descriptor(s) to be passed are described using a 142.Vt "struct cmsghdr" 143that is defined in the include file 144.In sys/socket.h . 145The type of the message is 146.Dv SCM_RIGHTS , 147and the data portion of the messages is an array of integers 148representing the file descriptors to be passed. 149The number of descriptors being passed is defined 150by the length field of the message; 151the length field is the sum of the size of the header 152plus the size of the array of file descriptors. 153.Pp 154The received descriptor is a 155.Em duplicate 156of the sender's descriptor, as if it were created via 157.Li dup(fd) 158or 159.Li fcntl(fd, F_DUPFD_CLOEXEC, 0) 160depending on whether 161.Dv MSG_CMSG_CLOEXEC 162is passed in the 163.Xr recvmsg 2 164call. 165Descriptors that are awaiting delivery, or that are 166purposely not received, are automatically closed by the system 167when the destination socket is closed. 168.Sh SOCKET OPTIONS 169.Tn UNIX 170domain sockets support a number of socket options which can be set with 171.Xr setsockopt 2 172and tested with 173.Xr getsockopt 2 : 174.Bl -tag -width ".Dv LOCAL_CONNWAIT" 175.It Dv LOCAL_CREDS 176This option may be enabled on 177.Dv SOCK_DGRAM , 178.Dv SOCK_SEQPACKET , 179or a 180.Dv SOCK_STREAM 181socket. 182This option provides a mechanism for the receiver to 183receive the credentials of the process as a 184.Xr recvmsg 2 185control message. 186The 187.Va msg_control 188field in the 189.Vt msghdr 190structure points to a buffer that contains a 191.Vt cmsghdr 192structure followed by a variable length 193.Vt sockcred 194structure, defined in 195.In sys/socket.h 196as follows: 197.Bd -literal 198struct sockcred { 199 uid_t sc_uid; /* real user id */ 200 uid_t sc_euid; /* effective user id */ 201 gid_t sc_gid; /* real group id */ 202 gid_t sc_egid; /* effective group id */ 203 int sc_ngroups; /* number of supplemental groups */ 204 gid_t sc_groups[1]; /* variable length */ 205}; 206.Ed 207.Pp 208The 209.Fn SOCKCREDSIZE 210macro computes the size of the 211.Vt sockcred 212structure for a specified number 213of groups. 214The 215.Vt cmsghdr 216fields have the following values: 217.Bd -literal 218cmsg_len = CMSG_LEN(SOCKCREDSIZE(ngroups)) 219cmsg_level = SOL_SOCKET 220cmsg_type = SCM_CREDS 221.Ed 222.Pp 223On 224.Dv SOCK_STREAM 225and 226.Dv SOCK_SEQPACKET 227sockets credentials are passed only on the first read from a socket, 228then system clears the option on socket. 229.It Dv LOCAL_CONNWAIT 230Used with 231.Dv SOCK_STREAM 232sockets, this option causes the 233.Xr connect 2 234function to block until 235.Xr accept 2 236has been called on the listening socket. 237.It Dv LOCAL_PEERCRED 238Requested via 239.Xr getsockopt 2 240on a 241.Dv SOCK_STREAM 242socket returns credentials of the remote side. 243These will arrive in the form of a filled in 244.Vt xucred 245structure, defined in 246.In sys/ucred.h 247as follows: 248.Bd -literal 249struct xucred { 250 u_int cr_version; /* structure layout version */ 251 uid_t cr_uid; /* effective user id */ 252 short cr_ngroups; /* number of groups */ 253 gid_t cr_groups[XU_NGROUPS]; /* groups */ 254}; 255.Ed 256The 257.Vt cr_version 258fields should be checked against 259.Dv XUCRED_VERSION 260define. 261.Pp 262The credentials presented to the server (the 263.Xr listen 2 264caller) are those of the client when it called 265.Xr connect 2 ; 266the credentials presented to the client (the 267.Xr connect 2 268caller) are those of the server when it called 269.Xr listen 2 . 270This mechanism is reliable; there is no way for either party to influence 271the credentials presented to its peer except by calling the appropriate 272system call (e.g., 273.Xr connect 2 274or 275.Xr listen 2 ) 276under different effective credentials. 277.Pp 278To reliably obtain peer credentials on a 279.Dv SOCK_DGRAM 280socket refer to the 281.Dv LOCAL_CREDS 282socket option. 283.El 284.Sh SEE ALSO 285.Xr connect 2 , 286.Xr dup 2 , 287.Xr fcntl 2 , 288.Xr getsockopt 2 , 289.Xr listen 2 , 290.Xr recvmsg 2 , 291.Xr sendto 2 , 292.Xr setsockopt 2 , 293.Xr socket 2 , 294.Xr intro 4 295.Rs 296.%T "An Introductory 4.3 BSD Interprocess Communication Tutorial" 297.%B PS1 298.%N 7 299.Re 300.Rs 301.%T "An Advanced 4.3 BSD Interprocess Communication Tutorial" 302.%B PS1 303.%N 8 304.Re 305