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. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" @(#)unix.4 8.1 (Berkeley) 6/9/93 29.\" $FreeBSD$ 30.\" 31.Dd February 3, 2017 32.Dt UNIX 4 33.Os 34.Sh NAME 35.Nm unix 36.Nd UNIX-domain protocol family 37.Sh SYNOPSIS 38.In sys/types.h 39.In sys/un.h 40.Sh DESCRIPTION 41The 42.Ux Ns -domain 43protocol family is a collection of protocols 44that provides local (on-machine) interprocess 45communication through the normal 46.Xr socket 2 47mechanisms. 48The 49.Ux Ns -domain 50family supports the 51.Dv SOCK_STREAM , 52.Dv SOCK_SEQPACKET , 53and 54.Dv SOCK_DGRAM 55socket types and uses 56file system pathnames for addressing. 57.Sh ADDRESSING 58.Ux Ns -domain 59addresses are variable-length file system pathnames of 60at most 104 characters. 61The include file 62.In sys/un.h 63defines this address: 64.Bd -literal -offset indent 65struct sockaddr_un { 66 u_char sun_len; 67 u_char sun_family; 68 char sun_path[104]; 69}; 70.Ed 71.Pp 72Binding a name to a 73.Ux Ns -domain 74socket with 75.Xr bind 2 76causes a socket file to be created in the file system. 77This file is 78.Em not 79removed when the socket is closed \(em 80.Xr unlink 2 81must be used to remove the file. 82.Pp 83The length of 84.Ux Ns -domain 85address, required by 86.Xr bind 2 87and 88.Xr connect 2 , 89can be calculated by the macro 90.Fn SUN_LEN 91defined in 92.In sys/un.h . 93The 94.Va sun_path 95field must be terminated by a 96.Dv NUL 97character to be used with 98.Fn SUN_LEN , 99but the terminating 100.Dv NUL 101is 102.Em not 103part of the address. 104.Pp 105The 106.Ux Ns -domain 107protocol family does not support broadcast addressing or any form 108of 109.Dq wildcard 110matching on incoming messages. 111All addresses are absolute- or relative-pathnames 112of other 113.Ux Ns -domain 114sockets. 115Normal file system access-control mechanisms are also 116applied when referencing pathnames; e.g., the destination 117of a 118.Xr connect 2 119or 120.Xr sendto 2 121must be writable. 122.Sh CONTROL MESSAGES 123The 124.Ux Ns -domain 125sockets support the communication of 126.Ux 127file descriptors and process credentials through the use of the 128.Va msg_control 129field in the 130.Fa msg 131argument to 132.Xr sendmsg 2 133and 134.Xr recvmsg 2 . 135The items to be passed are described using a 136.Vt "struct cmsghdr" 137that is defined in the include file 138.In sys/socket.h . 139.Pp 140To send file descriptors, the type of the message is 141.Dv SCM_RIGHTS , 142and the data portion of the messages is an array of integers 143representing the file descriptors to be passed. 144The number of descriptors being passed is defined 145by the length field of the message; 146the length field is the sum of the size of the header 147plus the size of the array of file descriptors. 148.Pp 149The received descriptor is a 150.Em duplicate 151of the sender's descriptor, as if it were created via 152.Li dup(fd) 153or 154.Li fcntl(fd, F_DUPFD_CLOEXEC, 0) 155depending on whether 156.Dv MSG_CMSG_CLOEXEC 157is passed in the 158.Xr recvmsg 2 159call. 160Descriptors that are awaiting delivery, or that are 161purposely not received, are automatically closed by the system 162when the destination socket is closed. 163.Pp 164Credentials of the sending process can be transmitted explicitly using a 165control message of type 166.Dv SCM_CREDS 167with a data portion of type 168.Vt "struct cmsgcred" , 169defined in 170.In sys/socket.h 171as follows: 172.Bd -literal 173struct cmsgcred { 174 pid_t cmcred_pid; /* PID of sending process */ 175 uid_t cmcred_uid; /* real UID of sending process */ 176 uid_t cmcred_euid; /* effective UID of sending process */ 177 gid_t cmcred_gid; /* real GID of sending process */ 178 short cmcred_ngroups; /* number of groups */ 179 gid_t cmcred_groups[CMGROUP_MAX]; /* groups */ 180}; 181.Ed 182.Pp 183The sender should pass a zeroed buffer which will be filled in by the system. 184.Pp 185The group list is truncated to at most 186.Dv CMGROUP_MAX 187GIDs. 188.Pp 189The process ID 190.Fa cmcred_pid 191should not be looked up (such as via the 192.Dv KERN_PROC_PID 193sysctl) for making security decisions. 194The sending process could have exited and its process ID already been 195reused for a new process. 196.Sh SOCKET OPTIONS 197.Tn UNIX 198domain sockets support a number of socket options which can be set with 199.Xr setsockopt 2 200and tested with 201.Xr getsockopt 2 : 202.Bl -tag -width ".Dv LOCAL_CONNWAIT" 203.It Dv LOCAL_CREDS 204This option may be enabled on 205.Dv SOCK_DGRAM , 206.Dv SOCK_SEQPACKET , 207or a 208.Dv SOCK_STREAM 209socket. 210This option provides a mechanism for the receiver to 211receive the credentials of the process calling 212.Xr write 2 , 213.Xr send 2 , 214.Xr sendto 2 215or 216.Xr sendmsg 2 217as a 218.Xr recvmsg 2 219control message. 220The 221.Va msg_control 222field in the 223.Vt msghdr 224structure points to a buffer that contains a 225.Vt cmsghdr 226structure followed by a variable length 227.Vt sockcred 228structure, defined in 229.In sys/socket.h 230as follows: 231.Bd -literal 232struct sockcred { 233 uid_t sc_uid; /* real user id */ 234 uid_t sc_euid; /* effective user id */ 235 gid_t sc_gid; /* real group id */ 236 gid_t sc_egid; /* effective group id */ 237 int sc_ngroups; /* number of supplemental groups */ 238 gid_t sc_groups[1]; /* variable length */ 239}; 240.Ed 241.Pp 242The current implementation truncates the group list to at most 243.Dv CMGROUP_MAX 244groups. 245.Pp 246The 247.Fn SOCKCREDSIZE 248macro computes the size of the 249.Vt sockcred 250structure for a specified number 251of groups. 252The 253.Vt cmsghdr 254fields have the following values: 255.Bd -literal 256cmsg_len = CMSG_LEN(SOCKCREDSIZE(ngroups)) 257cmsg_level = SOL_SOCKET 258cmsg_type = SCM_CREDS 259.Ed 260.Pp 261On 262.Dv SOCK_STREAM 263and 264.Dv SOCK_SEQPACKET 265sockets credentials are passed only on the first read from a socket, 266then the system clears the option on the socket. 267.Pp 268This option and the above explicit 269.Vt "struct cmsgcred" 270both use the same value 271.Dv SCM_CREDS 272but incompatible control messages. 273If this option is enabled and the sender attached a 274.Dv SCM_CREDS 275control message with a 276.Vt "struct cmsgcred" , 277it will be discarded and a 278.Vt "struct sockcred" 279will be included. 280.Pp 281Many setuid programs will 282.Xr write 2 283data at least partially controlled by the invoker, 284such as error messages. 285Therefore, a message accompanied by a particular 286.Fa sc_euid 287value should not be trusted as being from that user. 288.It Dv LOCAL_CONNWAIT 289Used with 290.Dv SOCK_STREAM 291sockets, this option causes the 292.Xr connect 2 293function to block until 294.Xr accept 2 295has been called on the listening socket. 296.It Dv LOCAL_PEERCRED 297Requested via 298.Xr getsockopt 2 299on a 300.Dv SOCK_STREAM 301socket returns credentials of the remote side. 302These will arrive in the form of a filled in 303.Vt xucred 304structure, defined in 305.In sys/ucred.h 306as follows: 307.Bd -literal 308struct xucred { 309 u_int cr_version; /* structure layout version */ 310 uid_t cr_uid; /* effective user id */ 311 short cr_ngroups; /* number of groups */ 312 gid_t cr_groups[XU_NGROUPS]; /* groups */ 313}; 314.Ed 315The 316.Vt cr_version 317fields should be checked against 318.Dv XUCRED_VERSION 319define. 320.Pp 321The credentials presented to the server (the 322.Xr listen 2 323caller) are those of the client when it called 324.Xr connect 2 ; 325the credentials presented to the client (the 326.Xr connect 2 327caller) are those of the server when it called 328.Xr listen 2 . 329This mechanism is reliable; there is no way for either party to influence 330the credentials presented to its peer except by calling the appropriate 331system call (e.g., 332.Xr connect 2 333or 334.Xr listen 2 ) 335under different effective credentials. 336.Pp 337To reliably obtain peer credentials on a 338.Dv SOCK_DGRAM 339socket refer to the 340.Dv LOCAL_CREDS 341socket option. 342.El 343.Sh SEE ALSO 344.Xr connect 2 , 345.Xr dup 2 , 346.Xr fcntl 2 , 347.Xr getsockopt 2 , 348.Xr listen 2 , 349.Xr recvmsg 2 , 350.Xr sendto 2 , 351.Xr setsockopt 2 , 352.Xr socket 2 , 353.Xr intro 4 354.Rs 355.%T "An Introductory 4.3 BSD Interprocess Communication Tutorial" 356.%B PS1 357.%N 7 358.Re 359.Rs 360.%T "An Advanced 4.3 BSD Interprocess Communication Tutorial" 361.%B PS1 362.%N 8 363.Re 364