1.\" $NetBSD: unix.4,v 1.24 2011/05/29 08:46:42 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 May 29, 2011 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 uid_t sc_uid; /* real user id */ 202 uid_t sc_euid; /* effective user id */ 203 gid_t sc_gid; /* real group id */ 204 gid_t sc_egid; /* effective group id */ 205 int sc_ngroups; /* number of supplemental groups */ 206 gid_t sc_groups[1]; /* variable length */ 207}; 208.Ed 209.Pp 210The 211.Dv LOCAL_PEEREID 212option may be used with 213.Xr getsockopt 2 214to get the PID and effective user and group IDs of a 215.Dv SOCK_STREAM 216or 217.Dv SOCK_SEQPACKET 218peer when it did 219.Xr connect 2 220or 221.Xr bind 2 . 222The returned structure is 223.Bd -literal 224struct unpcbid { 225 pid_t unp_pid; /* process id */ 226 uid_t unp_euid; /* effective user id */ 227 gid_t unp_egid; /* effective group id */ 228}; 229.Ed 230as defined in 231.In sys/un.h . 232.Pp 233The 234.Fn SOCKCREDSIZE 235macro computes the size of the sockcred structure for a specified number 236of groups. 237The cmsghdr fields have the following values: 238.Bd -literal 239cmsg_len = CMSG_LEN(SOCKCREDSIZE(ngroups)) 240cmsg_level = SOL_SOCKET 241cmsg_type = SCM_CREDS 242.Ed 243.Sh EXAMPLES 244The following code fragment shows how to bind a socket to pathname: 245.Bd -literal -offset indent 246const char *pathname = "/path/to/socket"; 247struct sockaddr_un addr; 248int ret; 249 250memset(\*[Am]addr, 0, sizeof(addr)); 251addr.sun_family = AF_LOCAL; 252if (strlen(pathname) \*[Ge] sizeof(addr.sun_path)) 253 goto too_long; 254strncpy(addr.sun_path, pathname, sizeof(addr.sun_path)); 255ret = bind(s, (const struct sockaddr *)\*[Am]addr, SUN_LEN(\*[Am]addr)); 256if (ret != 0) 257 goto bind_failed; 258\&... 259 260.Ed 261.Sh COMPATIBILITY 262The 263.Ar sun_len 264field exists only in system derived from 4.4BSD. 265On systems which don't have the 266.Fn SUN_LEN 267macro, the following definition is recommended: 268.Bd -literal -offset indent 269#ifndef SUN_LEN 270#define SUN_LEN(su) sizeof(struct(sockaddr_un)) 271#endif 272.Ed 273.Sh SEE ALSO 274.Xr socket 2 , 275.Xr CMSG_DATA 3 , 276.Xr intro 4 277.Rs 278.%T "An Introductory 4.4BSD Interprocess Communication Tutorial" 279.%A Stuart Sechrest 280.Re 281.Pq see Pa /usr/share/doc/psd/20.ipctut 282.Rs 283.%T "Advanced 4.4BSD IPC Tutorial" 284.%A Samuel J. Leffler 285.%A Robert S. Fabry 286.%A William N. Joy 287.%A Phil Lapsley 288.%A Steve Miller 289.%A Chris Torek 290.Re 291.Pq see Pa /usr/share/doc/psd/21.ipc 292