1.\" $NetBSD: unix.4,v 1.26 2017/07/03 21:30:58 wiz Exp $ 2.\" 3.\" Copyright (c) 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" @(#)unix.4 8.1 (Berkeley) 6/9/93 31.\" 32.Dd March 31, 2016 33.Dt UNIX 4 34.Os 35.Sh NAME 36.Nm unix 37.Nd UNIX-domain protocol family 38.Sh SYNOPSIS 39.In sys/types.h 40.In sys/un.h 41.Sh DESCRIPTION 42The 43.Tn UNIX Ns -domain 44protocol family is a collection of protocols 45that provides local (on-machine) interprocess 46communication through the normal 47.Xr socket 2 48mechanisms. 49The 50.Tn UNIX Ns -domain 51family supports the 52.Dv SOCK_STREAM , 53.Dv SOCK_SEQPACKET , 54and 55.Dv SOCK_DGRAM 56socket types and uses 57filesystem pathnames for addressing. 58.Sh ADDRESSING 59.Tn UNIX Ns -domain 60addresses are variable-length filesystem pathnames of 61at most 104 characters. 62The include file 63.In sys/un.h 64defines this address: 65.Bd -literal -offset indent 66struct sockaddr_un { 67 u_char sun_len; 68 u_char sun_family; 69 char sun_path[104]; 70}; 71.Ed 72.Pp 73Binding a name to a 74.Tn UNIX Ns -domain 75socket with 76.Xr bind 2 77causes a socket file to be created in the filesystem. 78This file is 79.Em not 80removed when the socket is closed\(em\c 81.Xr unlink 2 82must be used to remove the file. 83.Pp 84The length of 85.Tn UNIX Ns -domain 86address, required by 87.Xr bind 2 88and 89.Xr connect 2 , 90can be calculated by the macro 91.Fn SUN_LEN 92defined in 93.In sys/un.h . 94The 95.Ar sun_path 96field must be terminated by a NUL character to be used with 97.Fn SUN_LEN , 98but the terminating NUL is 99.Em not 100part of the address. 101The 102.Nx 103kernel ignores any user-set value in the 104.Va sun_len 105member of the structure. 106.Pp 107The 108.Tn UNIX Ns -domain 109protocol family does not support broadcast addressing or any form 110of 111.Dq wildcard 112matching on incoming messages. 113All addresses are absolute- or relative-pathnames 114of other 115.Tn UNIX Ns -domain 116sockets. 117Normal filesystem access-control mechanisms are also 118applied when referencing pathnames; e.g., the destination 119of a 120.Xr connect 2 121or 122.Xr sendto 2 123must be writable. 124.Sh PROTOCOLS 125The 126.Tn UNIX Ns -domain 127protocol family comprises simple 128transport protocols that support the 129.Dv SOCK_STREAM , 130.Dv SOCK_SEQPACKET , 131and 132.Dv SOCK_DGRAM 133abstractions. 134.Dv SOCK_STREAM 135and 136.Dv SOCK_SEQPACKET 137sockets also support the communication of 138.Ux 139file descriptors through the use of the 140.Ar msg_control 141field in the 142.Ar msg 143argument to 144.Xr sendmsg 2 145and 146.Xr recvmsg 2 . 147.Pp 148Any valid descriptor may be sent in a message. 149The file descriptor(s) to be passed are described using a 150.Ar struct cmsghdr 151that is defined in the include file 152.In sys/socket.h . 153The type of the message is 154.Dv SCM_RIGHTS , 155and the data portion of the messages is an array of integers 156representing the file descriptors to be passed. 157The number of descriptors being passed is defined 158by the length field of the message; 159the length field is the sum of the size of the header 160plus the size of the array of file descriptors. 161.Pp 162The received descriptor is a 163.Em duplicate 164of the sender's descriptor, as if it were created with a call to 165.Xr dup 2 . 166Per-process descriptor flags, set with 167.Xr fcntl 2 , 168are 169.Em not 170passed to a receiver. 171Descriptors that are awaiting delivery, or that are 172purposely not received, are automatically closed by the system 173when the destination socket is closed. 174.Pp 175A UNIX-domain socket supports two 176.Tn socket-level 177options for use with 178.Xr setsockopt 2 179and 180.Xr getsockopt 2 : 181.Pp 182The 183.Dv LOCAL_CREDS 184option may be enabled on a 185.Dv SOCK_DGRAM , 186.Dv SOCK_SEQPACKET , 187or a 188.Dv SOCK_STREAM 189socket. 190This option provides a mechanism for the receiver to 191receive the credentials of the process as a 192.Xr recvmsg 2 193control message. 194The msg_control field in the msghdr structure points 195to a buffer that contains a cmsghdr structure followed by a variable 196length sockcred structure, defined in 197.In sys/socket.h 198as follows: 199.Bd -literal 200struct sockcred { 201 pid_t sc_pid; /* process id */ 202 uid_t sc_uid; /* real user id */ 203 uid_t sc_euid; /* effective user id */ 204 gid_t sc_gid; /* real group id */ 205 gid_t sc_egid; /* effective group id */ 206 int sc_ngroups; /* number of supplemental groups */ 207 gid_t sc_groups[1]; /* variable length */ 208}; 209.Ed 210.Pp 211The 212.Dv LOCAL_PEEREID 213option may be used with 214.Xr getsockopt 2 215to get the PID and effective user and group IDs of a 216.Dv SOCK_STREAM 217or 218.Dv SOCK_SEQPACKET 219peer when it did 220.Xr connect 2 221or 222.Xr bind 2 . 223The returned structure is 224.Bd -literal 225struct unpcbid { 226 pid_t unp_pid; /* process id */ 227 uid_t unp_euid; /* effective user id */ 228 gid_t unp_egid; /* effective group id */ 229}; 230.Ed 231as defined in 232.In sys/un.h . 233.Pp 234The 235.Fn SOCKCREDSIZE 236macro computes the size of the sockcred structure for a specified number 237of groups. 238The cmsghdr fields have the following values: 239.Bd -literal 240cmsg_len = CMSG_LEN(SOCKCREDSIZE(ngroups)) 241cmsg_level = SOL_SOCKET 242cmsg_type = SCM_CREDS 243.Ed 244.Sh EXAMPLES 245The following code fragment shows how to bind a socket to pathname: 246.Bd -literal -offset indent 247const char *pathname = "/path/to/socket"; 248struct sockaddr_un addr; 249int ret; 250 251memset(&addr, 0, sizeof(addr)); 252addr.sun_family = AF_LOCAL; 253if (strlen(pathname) \*[Ge] sizeof(addr.sun_path)) 254 goto too_long; 255strncpy(addr.sun_path, pathname, sizeof(addr.sun_path)); 256ret = bind(s, (const struct sockaddr *)&addr, SUN_LEN(&addr)); 257if (ret != 0) 258 goto bind_failed; 259\&... 260 261.Ed 262.Sh COMPATIBILITY 263The 264.Ar sun_len 265field exists only in system derived from 4.4BSD. 266On systems which don't have the 267.Fn SUN_LEN 268macro, the following definition is recommended: 269.Bd -literal -offset indent 270#ifndef SUN_LEN 271#define SUN_LEN(su) sizeof(struct(sockaddr_un)) 272#endif 273.Ed 274.Sh SEE ALSO 275.Xr socket 2 , 276.Xr CMSG_DATA 3 , 277.Xr intro 4 278.Rs 279.%T "An Introductory 4.4BSD Interprocess Communication Tutorial" 280.%A Stuart Sechrest 281.Re 282.Pq see Pa /usr/share/doc/psd/20.ipctut 283.Rs 284.%T "Advanced 4.4BSD IPC Tutorial" 285.%A Samuel J. Leffler 286.%A Robert S. Fabry 287.%A William N. Joy 288.%A Phil Lapsley 289.%A Steve Miller 290.%A Chris Torek 291.Re 292.Pq see Pa /usr/share/doc/psd/21.ipc 293.Sh HISTORY 294The 295.Ar sc_pid 296field was introduced in 297.Nx 8.0 . 298