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