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.\" 30.Dd June 24, 2022 31.Dt UNIX 4 32.Os 33.Sh NAME 34.Nm unix 35.Nd UNIX-domain protocol family 36.Sh SYNOPSIS 37.In sys/types.h 38.In sys/un.h 39.Sh DESCRIPTION 40The 41.Ux Ns -domain 42protocol family is a collection of protocols 43that provides local (on-machine) interprocess 44communication through the normal 45.Xr socket 2 46mechanisms. 47The 48.Ux Ns -domain 49family supports the 50.Dv SOCK_STREAM , 51.Dv SOCK_SEQPACKET , 52and 53.Dv SOCK_DGRAM 54socket types and uses 55file system pathnames for addressing. 56.Sh ADDRESSING 57.Ux Ns -domain 58addresses are variable-length file system pathnames of 59at most 104 characters. 60The include file 61.In sys/un.h 62defines this address: 63.Bd -literal -offset indent 64struct sockaddr_un { 65 u_char sun_len; 66 u_char sun_family; 67 char sun_path[104]; 68}; 69.Ed 70.Pp 71Binding a name to a 72.Ux Ns -domain 73socket with 74.Xr bind 2 75causes a socket file to be created in the file system. 76This file is 77.Em not 78removed when the socket is closed \(em 79.Xr unlink 2 80must be used to remove the file. 81.Pp 82The length of 83.Ux Ns -domain 84address, required by 85.Xr bind 2 86and 87.Xr connect 2 , 88can be calculated by the macro 89.Fn SUN_LEN 90defined in 91.In sys/un.h . 92The 93.Va sun_path 94field must be terminated by a 95.Dv NUL 96character to be used with 97.Fn SUN_LEN , 98but the terminating 99.Dv NUL 100is 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 CONTROL MESSAGES 122The 123.Ux Ns -domain 124sockets support the communication of 125.Ux 126file descriptors and process credentials through the use of the 127.Va msg_control 128field in the 129.Fa msg 130argument to 131.Xr sendmsg 2 132and 133.Xr recvmsg 2 . 134The items to be passed are described using a 135.Vt "struct cmsghdr" 136that is defined in the include file 137.In sys/socket.h . 138.Pp 139To send file descriptors, the type of the message is 140.Dv SCM_RIGHTS , 141and the data portion of the messages is an array of integers 142representing the file descriptors to be passed. 143The number of descriptors being passed is defined 144by the length field of the message; 145the length field is the sum of the size of the header 146plus the size of the array of file descriptors. 147.Pp 148The received descriptor is a 149.Em duplicate 150of the sender's descriptor, as if it were created via 151.Li dup(fd) 152or 153.Li fcntl(fd, F_DUPFD_CLOEXEC, 0) 154depending on whether 155.Dv MSG_CMSG_CLOEXEC 156is passed in the 157.Xr recvmsg 2 158call. 159Descriptors that are awaiting delivery, or that are 160purposely not received, are automatically closed by the system 161when the destination socket is closed. 162.Pp 163Credentials of the sending process can be transmitted explicitly using a 164control message of type 165.Dv SCM_CREDS 166with a data portion of type 167.Vt "struct cmsgcred" , 168defined in 169.In sys/socket.h 170as follows: 171.Bd -literal 172struct cmsgcred { 173 pid_t cmcred_pid; /* PID of sending process */ 174 uid_t cmcred_uid; /* real UID of sending process */ 175 uid_t cmcred_euid; /* effective UID of sending process */ 176 gid_t cmcred_gid; /* real GID of sending process */ 177 short cmcred_ngroups; /* number of groups */ 178 gid_t cmcred_groups[CMGROUP_MAX]; /* groups */ 179}; 180.Ed 181.Pp 182The sender should pass a zeroed buffer which will be filled in by the system. 183.Pp 184The group list is truncated to at most 185.Dv CMGROUP_MAX 186GIDs. 187.Pp 188The process ID 189.Fa cmcred_pid 190should not be looked up (such as via the 191.Dv KERN_PROC_PID 192sysctl) for making security decisions. 193The sending process could have exited and its process ID already been 194reused for a new process. 195.Sh SOCKET OPTIONS 196.Tn UNIX 197domain sockets support a number of socket options for the options level 198.Dv SOL_LOCAL , 199which can be set with 200.Xr setsockopt 2 201and tested with 202.Xr getsockopt 2 : 203.Bl -tag -width ".Dv LOCAL_CREDS_PERSISTENT" 204.It Dv LOCAL_CREDS 205This option may be enabled on 206.Dv SOCK_DGRAM , 207.Dv SOCK_SEQPACKET , 208or a 209.Dv SOCK_STREAM 210socket. 211This option provides a mechanism for the receiver to 212receive the credentials of the process calling 213.Xr write 2 , 214.Xr send 2 , 215.Xr sendto 2 216or 217.Xr sendmsg 2 218as a 219.Xr recvmsg 2 220control message. 221The 222.Va msg_control 223field in the 224.Vt msghdr 225structure points to a buffer that contains a 226.Vt cmsghdr 227structure followed by a variable length 228.Vt sockcred 229structure, defined in 230.In sys/socket.h 231as follows: 232.Bd -literal 233struct sockcred { 234 uid_t sc_uid; /* real user id */ 235 uid_t sc_euid; /* effective user id */ 236 gid_t sc_gid; /* real group id */ 237 gid_t sc_egid; /* effective group id */ 238 int sc_ngroups; /* number of supplemental groups */ 239 gid_t sc_groups[1]; /* variable length */ 240}; 241.Ed 242.Pp 243The current implementation truncates the group list to at most 244.Dv CMGROUP_MAX 245groups. 246.Pp 247The 248.Fn SOCKCREDSIZE 249macro computes the size of the 250.Vt sockcred 251structure for a specified number 252of groups. 253The 254.Vt cmsghdr 255fields have the following values: 256.Bd -literal 257cmsg_len = CMSG_LEN(SOCKCREDSIZE(ngroups)) 258cmsg_level = SOL_SOCKET 259cmsg_type = SCM_CREDS 260.Ed 261.Pp 262On 263.Dv SOCK_STREAM 264and 265.Dv SOCK_SEQPACKET 266sockets credentials are passed only on the first read from a socket, 267then the system clears the option on the socket. 268.Pp 269This option and the above explicit 270.Vt "struct cmsgcred" 271both use the same value 272.Dv SCM_CREDS 273but incompatible control messages. 274If this option is enabled and the sender attached a 275.Dv SCM_CREDS 276control message with a 277.Vt "struct cmsgcred" , 278it will be discarded and a 279.Vt "struct sockcred" 280will be included. 281.Pp 282Many setuid programs will 283.Xr write 2 284data at least partially controlled by the invoker, 285such as error messages. 286Therefore, a message accompanied by a particular 287.Fa sc_euid 288value should not be trusted as being from that user. 289.It Dv LOCAL_CREDS_PERSISTENT 290This option is similar to 291.Dv LOCAL_CREDS , 292except that socket credentials are passed on every read from a 293.Dv SOCK_STREAM 294or 295.Dv SOCK_SEQPACKET 296socket, instead of just the first read. 297Additionally, the 298.Va msg_control 299field in the 300.Vt msghdr 301structure points to a buffer that contains a 302.Vt cmsghdr 303structure followed by a variable length 304.Vt sockcred2 305structure, defined in 306.In sys/socket.h 307as follows: 308.Bd -literal 309struct sockcred2 { 310 int sc_version; /* version of this structure */ 311 pid_t sc_pid; /* PID of sending process */ 312 uid_t sc_uid; /* real user id */ 313 uid_t sc_euid; /* effective user id */ 314 gid_t sc_gid; /* real group id */ 315 gid_t sc_egid; /* effective group id */ 316 int sc_ngroups; /* number of supplemental groups */ 317 gid_t sc_groups[1]; /* variable length */ 318}; 319.Ed 320.Pp 321The current version is zero. 322.Pp 323The 324.Vt cmsghdr 325fields have the following values: 326.Bd -literal 327cmsg_len = CMSG_LEN(SOCKCRED2SIZE(ngroups)) 328cmsg_level = SOL_SOCKET 329cmsg_type = SCM_CREDS2 330.Ed 331.Pp 332The 333.Dv LOCAL_CREDS 334and 335.Dv LOCAL_CREDS_PERSISTENT 336options are mutually exclusive. 337.It Dv LOCAL_CONNWAIT 338Used with 339.Dv SOCK_STREAM 340sockets, this option causes the 341.Xr connect 2 342function to block until 343.Xr accept 2 344has been called on the listening socket. 345.It Dv LOCAL_PEERCRED 346Requested via 347.Xr getsockopt 2 348on a 349.Dv SOCK_STREAM 350or 351.Dv SOCK_SEQPACKET 352socket returns credentials of the remote side. 353These will arrive in the form of a filled in 354.Vt xucred 355structure, defined in 356.In sys/ucred.h 357as follows: 358.Bd -literal 359struct xucred { 360 u_int cr_version; /* structure layout version */ 361 uid_t cr_uid; /* effective user id */ 362 short cr_ngroups; /* number of groups */ 363 gid_t cr_groups[XU_NGROUPS]; /* groups */ 364 pid_t cr_pid; /* process id of the sending process */ 365}; 366.Ed 367The 368.Vt cr_version 369fields should be checked against 370.Dv XUCRED_VERSION 371define. 372.Pp 373The credentials presented to the server (the 374.Xr listen 2 375caller) are those of the client when it called 376.Xr connect 2 ; 377the credentials presented to the client (the 378.Xr connect 2 379caller) are those of the server when it called 380.Xr listen 2 . 381This mechanism is reliable; there is no way for either party to influence 382the credentials presented to its peer except by calling the appropriate 383system call (e.g., 384.Xr connect 2 385or 386.Xr listen 2 ) 387under different effective credentials. 388.Pp 389To reliably obtain peer credentials on a 390.Dv SOCK_DGRAM 391socket refer to the 392.Dv LOCAL_CREDS 393socket option. 394.El 395.Sh BUFFERING 396Due to the local nature of the 397.Ux Ns -domain 398sockets, they do not implement send buffers. 399The 400.Xr send 2 401and 402.Xr write 2 403families of system calls attempt to write data to the receive buffer of the 404destination socket. 405.Pp 406The default buffer sizes for 407.Dv SOCK_STREAM 408and 409.Dv SOCK_SEQPACKET 410.Ux Ns -domain 411sockets can be configured with 412.Va net.local.stream 413and 414.Va net.local.seqpacket 415branches of 416.Xr sysctl 3 417MIB respectively. 418Note that setting the send buffer size (sendspace) affects only the maximum 419write size. 420.Pp 421The 422.Ux Ns -domain 423sockets of type 424.Dv SOCK_DGRAM 425are unreliable and always non-blocking for write operations. 426The default receive buffer can be configured with 427.Va net.local.dgram.recvspace . 428The maximum allowed datagram size is limited by 429.Va net.local.dgram.maxdgram . 430A 431.Dv SOCK_DGRAM 432socket that has been bound with 433.Xr bind 2 434can have multiple peers connected 435at the same time. 436The modern 437.Fx 438implementation will allocate 439.Va net.local.dgram.recvspace 440sized private buffers in the receive buffer of the bound socket for every 441connected socket, preventing a situation when a single writer can exhaust 442all of buffer space. 443Messages coming from unconnected sends using 444.Xr sendto 2 445land on the shared buffer of the receiving socket, which has the same 446size limit. 447A side effect of the implementation is that it doesn't guarantee 448that writes from different senders will arrive at the receiver in the same 449chronological order they were sent. 450The order is preserved for writes coming through a particular connection. 451.Sh SEE ALSO 452.Xr connect 2 , 453.Xr dup 2 , 454.Xr fcntl 2 , 455.Xr getsockopt 2 , 456.Xr listen 2 , 457.Xr recvmsg 2 , 458.Xr sendto 2 , 459.Xr setsockopt 2 , 460.Xr socket 2 , 461.Xr CMSG_DATA 3 , 462.Xr intro 4 , 463.Xr sysctl 8 464.Rs 465.%T "An Introductory 4.3 BSD Interprocess Communication Tutorial" 466.%B PS1 467.%N 7 468.Re 469.Rs 470.%T "An Advanced 4.3 BSD Interprocess Communication Tutorial" 471.%B PS1 472.%N 8 473.Re 474