1.\" $NetBSD: unix.4,v 1.18 2006/10/30 23:53:54 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 October 30, 2006 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 53and 54.Dv SOCK_DGRAM 55socket types and uses 56filesystem pathnames for addressing. 57.Sh ADDRESSING 58.Tn UNIX Ns -domain 59addresses are variable-length filesystem pathnames of 60at most 104 characters. 61The include file 62.Aq Pa 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.Tn UNIX Ns -domain 74socket with 75.Xr bind 2 76causes a socket file to be created in the filesystem. 77This file is 78.Em not 79removed when the socket is closed\(em\c 80.Xr unlink 2 81must be used to remove the file. 82.Pp 83The length of 84.Tn UNIX 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.Aq Pa sys/un.h . 93The 94.Ar sun_path 95field must be terminated by a NUL character to be used with 96.Fn SUN_LEN , 97but the terminating NUL is 98.Em not 99part of the address. 100The 101.Nx 102kernel ignores any user-set value in the 103.Va sun_len 104member of the structure. 105.Pp 106The 107.Tn UNIX Ns -domain 108protocol family does not support broadcast addressing or any form 109of 110.Dq wildcard 111matching on incoming messages. 112All addresses are absolute- or relative-pathnames 113of other 114.Tn UNIX Ns -domain 115sockets. 116Normal filesystem access-control mechanisms are also 117applied when referencing pathnames; e.g., the destination 118of a 119.Xr connect 2 120or 121.Xr sendto 2 122must be writable. 123.Sh PROTOCOLS 124The 125.Tn UNIX Ns -domain 126protocol family comprises simple 127transport protocols that support the 128.Dv SOCK_STREAM 129and 130.Dv SOCK_DGRAM 131abstractions. 132.Dv SOCK_STREAM 133sockets also support the communication of 134.Ux 135file descriptors through the use of the 136.Ar msg_control 137field in the 138.Ar msg 139argument to 140.Xr sendmsg 2 141and 142.Xr recvmsg 2 . 143.Pp 144Any valid descriptor may be sent in a message. 145The file descriptor(s) to be passed are described using a 146.Ar struct cmsghdr 147that is defined in the include file 148.Aq Pa sys/socket.h . 149The type of the message is 150.Dv SCM_RIGHTS , 151and the data portion of the messages is an array of integers 152representing the file descriptors to be passed. 153The number of descriptors being passed is defined 154by the length field of the message; 155the length field is the sum of the size of the header 156plus the size of the array of file descriptors. 157.Pp 158The received descriptor is a 159.Em duplicate 160of the sender's descriptor, as if it were created with a call to 161.Xr dup 2 . 162Per-process descriptor flags, set with 163.Xr fcntl 2 , 164are 165.Em not 166passed to a receiver. 167Descriptors that are awaiting delivery, or that are 168purposely not received, are automatically closed by the system 169when the destination socket is closed. 170.Pp 171There is one 172.Tn socket-level 173.Xr setsockopt 2 / Ns Xr getsockopt 2 174option available in the 175.Nm 176domain. 177The 178.Dv LOCAL_CREDS 179option may be enabled on a 180.Dv SOCK_DGRAM 181or a 182.Dv SOCK_STREAM 183socket. 184This option provides a mechanism for the receiver to 185receive the credentials of the process as a 186.Xr recvmsg 2 187control message. 188The msg_control field in the msghdr structure points 189to a buffer that contains a cmsghdr structure followed by a variable 190length sockcred structure, defined in 191.Aq Pa 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 sockcred structure for a specified number 207of groups. 208The cmsghdr fields have the following values: 209.Bd -literal 210cmsg_len = sizeof(struct cmsghdr) + SOCKCREDSIZE(ngroups) 211cmsg_level = SOL_SOCKET 212cmsg_type = SCM_CREDS 213.Ed 214.Sh EXAMPLES 215The following code fragment shows how to bind a socket to pathname: 216.Bd -literal -offset indent 217const char *pathname = "/path/to/socket"; 218struct sockaddr_un addr; 219int ret; 220 221memset(\*[Am]addr, 0, sizeof(addr)); 222addr.sun_family = AF_LOCAL; 223if (strlen(pathname) \*[Ge] sizeof(addr.sun_path)) 224 goto too_long; 225strncpy(addr.sun_path, pathname, sizeof(addr.sun_path)); 226ret = bind(s, (const struct sockaddr *)\*[Am]addr, SUN_LEN(\*[Am]addr)); 227if (ret != 0) 228 goto bind_failed; 229\&... 230 231.Ed 232.Sh COMPATIBILITY 233The 234.Ar sun_len 235field exists only in system derived from 4.4BSD. 236On systems which don't have the 237.Fn SUN_LEN 238macro, the following definition is recommended: 239.Bd -literal -offset indent 240#ifndef SUN_LEN 241#define SUN_LEN(su) sizeof(struct(sockaddr_un)) 242#endif 243.Ed 244.Sh SEE ALSO 245.Xr socket 2 , 246.Xr intro 4 247.Rs 248.%T "An Introductory 4.4BSD Interprocess Communication Tutorial" 249.%A Stuart Sechrest 250.Re 251.Pq see Pa /usr/share/doc/psd/20.ipctut 252.Rs 253.%T "Advanced 4.4BSD IPC Tutorial" 254.%A Samuel J. Leffler 255.%A Robert S. Fabry 256.%A William N. Joy 257.%A Phil Lapsley 258.%A Steve Miller 259.%A Chris Torek 260.Re 261.Pq see Pa /usr/share/doc/psd/21.ipc 262