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 August 7, 2021 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 for the options level 199.Dv SOL_LOCAL , 200which can be set with 201.Xr setsockopt 2 202and tested with 203.Xr getsockopt 2 : 204.Bl -tag -width ".Dv LOCAL_CREDS_PERSISTENT" 205.It Dv LOCAL_CREDS 206This option may be enabled on 207.Dv SOCK_DGRAM , 208.Dv SOCK_SEQPACKET , 209or a 210.Dv SOCK_STREAM 211socket. 212This option provides a mechanism for the receiver to 213receive the credentials of the process calling 214.Xr write 2 , 215.Xr send 2 , 216.Xr sendto 2 217or 218.Xr sendmsg 2 219as a 220.Xr recvmsg 2 221control message. 222The 223.Va msg_control 224field in the 225.Vt msghdr 226structure points to a buffer that contains a 227.Vt cmsghdr 228structure followed by a variable length 229.Vt sockcred 230structure, defined in 231.In sys/socket.h 232as follows: 233.Bd -literal 234struct sockcred { 235 uid_t sc_uid; /* real user id */ 236 uid_t sc_euid; /* effective user id */ 237 gid_t sc_gid; /* real group id */ 238 gid_t sc_egid; /* effective group id */ 239 int sc_ngroups; /* number of supplemental groups */ 240 gid_t sc_groups[1]; /* variable length */ 241}; 242.Ed 243.Pp 244The current implementation truncates the group list to at most 245.Dv CMGROUP_MAX 246groups. 247.Pp 248The 249.Fn SOCKCREDSIZE 250macro computes the size of the 251.Vt sockcred 252structure for a specified number 253of groups. 254The 255.Vt cmsghdr 256fields have the following values: 257.Bd -literal 258cmsg_len = CMSG_LEN(SOCKCREDSIZE(ngroups)) 259cmsg_level = SOL_SOCKET 260cmsg_type = SCM_CREDS 261.Ed 262.Pp 263On 264.Dv SOCK_STREAM 265and 266.Dv SOCK_SEQPACKET 267sockets credentials are passed only on the first read from a socket, 268then the system clears the option on the socket. 269.Pp 270This option and the above explicit 271.Vt "struct cmsgcred" 272both use the same value 273.Dv SCM_CREDS 274but incompatible control messages. 275If this option is enabled and the sender attached a 276.Dv SCM_CREDS 277control message with a 278.Vt "struct cmsgcred" , 279it will be discarded and a 280.Vt "struct sockcred" 281will be included. 282.Pp 283Many setuid programs will 284.Xr write 2 285data at least partially controlled by the invoker, 286such as error messages. 287Therefore, a message accompanied by a particular 288.Fa sc_euid 289value should not be trusted as being from that user. 290.It Dv LOCAL_CREDS_PERSISTENT 291This option is similar to 292.Dv LOCAL_CREDS , 293except that socket credentials are passed on every read from a 294.Dv SOCK_STREAM 295or 296.Dv SOCK_SEQPACKET 297socket, instead of just the first read. 298Additionally, the 299.Va msg_control 300field in the 301.Vt msghdr 302structure points to a buffer that contains a 303.Vt cmsghdr 304structure followed by a variable length 305.Vt sockcred2 306structure, defined in 307.In sys/socket.h 308as follows: 309.Bd -literal 310struct sockcred2 { 311 int sc_version; /* version of this structure */ 312 pid_t sc_pid; /* PID of sending process */ 313 uid_t sc_uid; /* real user id */ 314 uid_t sc_euid; /* effective user id */ 315 gid_t sc_gid; /* real group id */ 316 gid_t sc_egid; /* effective group id */ 317 int sc_ngroups; /* number of supplemental groups */ 318 gid_t sc_groups[1]; /* variable length */ 319}; 320.Ed 321.Pp 322The current version is zero. 323.Pp 324The 325.Vt cmsghdr 326fields have the following values: 327.Bd -literal 328cmsg_len = CMSG_LEN(SOCKCRED2SIZE(ngroups)) 329cmsg_level = SOL_SOCKET 330cmsg_type = SCM_CREDS2 331.Ed 332.Pp 333The 334.Dv LOCAL_CREDS 335and 336.Dv LOCAL_CREDS_PERSISTENT 337options are mutually exclusive. 338.It Dv LOCAL_CONNWAIT 339Used with 340.Dv SOCK_STREAM 341sockets, this option causes the 342.Xr connect 2 343function to block until 344.Xr accept 2 345has been called on the listening socket. 346.It Dv LOCAL_PEERCRED 347Requested via 348.Xr getsockopt 2 349on a 350.Dv SOCK_STREAM 351or 352.Dv SOCK_SEQPACKET 353socket returns credentials of the remote side. 354These will arrive in the form of a filled in 355.Vt xucred 356structure, defined in 357.In sys/ucred.h 358as follows: 359.Bd -literal 360struct xucred { 361 u_int cr_version; /* structure layout version */ 362 uid_t cr_uid; /* effective user id */ 363 short cr_ngroups; /* number of groups */ 364 gid_t cr_groups[XU_NGROUPS]; /* groups */ 365 pid_t cr_pid; /* process id of the sending process */ 366}; 367.Ed 368The 369.Vt cr_version 370fields should be checked against 371.Dv XUCRED_VERSION 372define. 373.Pp 374The credentials presented to the server (the 375.Xr listen 2 376caller) are those of the client when it called 377.Xr connect 2 ; 378the credentials presented to the client (the 379.Xr connect 2 380caller) are those of the server when it called 381.Xr listen 2 . 382This mechanism is reliable; there is no way for either party to influence 383the credentials presented to its peer except by calling the appropriate 384system call (e.g., 385.Xr connect 2 386or 387.Xr listen 2 ) 388under different effective credentials. 389.Pp 390To reliably obtain peer credentials on a 391.Dv SOCK_DGRAM 392socket refer to the 393.Dv LOCAL_CREDS 394socket option. 395.El 396.Sh SEE ALSO 397.Xr connect 2 , 398.Xr dup 2 , 399.Xr fcntl 2 , 400.Xr getsockopt 2 , 401.Xr listen 2 , 402.Xr recvmsg 2 , 403.Xr sendto 2 , 404.Xr setsockopt 2 , 405.Xr socket 2 , 406.Xr CMSG_DATA 3 , 407.Xr intro 4 408.Rs 409.%T "An Introductory 4.3 BSD Interprocess Communication Tutorial" 410.%B PS1 411.%N 7 412.Re 413.Rs 414.%T "An Advanced 4.3 BSD Interprocess Communication Tutorial" 415.%B PS1 416.%N 8 417.Re 418