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 March 19, 2013 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 PASSING FILE DESCRIPTORS 123The 124.Ux Ns -domain 125sockets support the communication of 126.Ux 127file descriptors 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 . 135.Pp 136Any valid descriptor may be sent in a message. 137The file descriptor(s) to be passed are described using a 138.Vt "struct cmsghdr" 139that is defined in the include file 140.In sys/socket.h . 141The type of the message is 142.Dv SCM_RIGHTS , 143and the data portion of the messages is an array of integers 144representing the file descriptors to be passed. 145The number of descriptors being passed is defined 146by the length field of the message; 147the length field is the sum of the size of the header 148plus the size of the array of file descriptors. 149.Pp 150The received descriptor is a 151.Em duplicate 152of the sender's descriptor, as if it were created via 153.Li dup(fd) 154or 155.Li fcntl(fd, F_DUPFD_CLOEXEC, 0) 156depending on whether 157.Dv MSG_CMSG_CLOEXEC 158is passed in the 159.Xr recvmsg 2 160call. 161Descriptors that are awaiting delivery, or that are 162purposely not received, are automatically closed by the system 163when the destination socket is closed. 164.Sh SOCKET OPTIONS 165.Tn UNIX 166domain sockets support a number of socket options which can be set with 167.Xr setsockopt 2 168and tested with 169.Xr getsockopt 2 : 170.Bl -tag -width ".Dv LOCAL_CONNWAIT" 171.It Dv LOCAL_CREDS 172This option may be enabled on 173.Dv SOCK_DGRAM , 174.Dv SOCK_SEQPACKET , 175or a 176.Dv SOCK_STREAM 177socket. 178This option provides a mechanism for the receiver to 179receive the credentials of the process as a 180.Xr recvmsg 2 181control message. 182The 183.Va msg_control 184field in the 185.Vt msghdr 186structure points to a buffer that contains a 187.Vt cmsghdr 188structure followed by a variable length 189.Vt sockcred 190structure, defined in 191.In sys/socket.h 192as follows: 193.Bd -literal 194struct sockcred { 195 uid_t sc_uid; /* real user id */ 196 uid_t sc_euid; /* effective user id */ 197 gid_t sc_gid; /* real group id */ 198 gid_t sc_egid; /* effective group id */ 199 int sc_ngroups; /* number of supplemental groups */ 200 gid_t sc_groups[1]; /* variable length */ 201}; 202.Ed 203.Pp 204The 205.Fn SOCKCREDSIZE 206macro computes the size of the 207.Vt sockcred 208structure for a specified number 209of groups. 210The 211.Vt cmsghdr 212fields have the following values: 213.Bd -literal 214cmsg_len = CMSG_LEN(SOCKCREDSIZE(ngroups)) 215cmsg_level = SOL_SOCKET 216cmsg_type = SCM_CREDS 217.Ed 218.Pp 219On 220.Dv SOCK_STREAM 221and 222.Dv SOCK_SEQPACKET 223sockets credentials are passed only on the first read from a socket, 224then system clears the option on socket. 225.It Dv LOCAL_CONNWAIT 226Used with 227.Dv SOCK_STREAM 228sockets, this option causes the 229.Xr connect 2 230function to block until 231.Xr accept 2 232has been called on the listening socket. 233.It Dv LOCAL_PEERCRED 234Requested via 235.Xr getsockopt 2 236on a 237.Dv SOCK_STREAM 238socket returns credentials of the remote side. 239These will arrive in the form of a filled in 240.Vt xucred 241structure, defined in 242.In sys/ucred.h 243as follows: 244.Bd -literal 245struct xucred { 246 u_int cr_version; /* structure layout version */ 247 uid_t cr_uid; /* effective user id */ 248 short cr_ngroups; /* number of groups */ 249 gid_t cr_groups[XU_NGROUPS]; /* groups */ 250}; 251.Ed 252The 253.Vt cr_version 254fields should be checked against 255.Dv XUCRED_VERSION 256define. 257.Pp 258The credentials presented to the server (the 259.Xr listen 2 260caller) are those of the client when it called 261.Xr connect 2 ; 262the credentials presented to the client (the 263.Xr connect 2 264caller) are those of the server when it called 265.Xr listen 2 . 266This mechanism is reliable; there is no way for either party to influence 267the credentials presented to its peer except by calling the appropriate 268system call (e.g., 269.Xr connect 2 270or 271.Xr listen 2 ) 272under different effective credentials. 273.Pp 274To reliably obtain peer credentials on a 275.Dv SOCK_DGRAM 276socket refer to the 277.Dv LOCAL_CREDS 278socket option. 279.El 280.Sh SEE ALSO 281.Xr connect 2 , 282.Xr dup 2 , 283.Xr fcntl 2 , 284.Xr getsockopt 2 , 285.Xr listen 2 , 286.Xr recvmsg 2 , 287.Xr sendto 2 , 288.Xr setsockopt 2 , 289.Xr socket 2 , 290.Xr intro 4 291.Rs 292.%T "An Introductory 4.3 BSD Interprocess Communication Tutorial" 293.%B PS1 294.%N 7 295.Re 296.Rs 297.%T "An Advanced 4.3 BSD Interprocess Communication Tutorial" 298.%B PS1 299.%N 8 300.Re 301