1.\" $NetBSD: unix.4,v 1.16 2006/10/13 21:03:22 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 11, 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. 105Usage example: 106.Bd -literal -offset indent 107memset(\*[Am]sunx, 0, sizeof(sunx)); 108sunx.sun_family = AF_LOCAL; 109strlcpy(sunx.sun_path, THE_PATH, sizeof(sunx.sun_path)); 110rv = bind(s, (struct sockaddr *)\*[Am]sunx, SUN_LEN(\*[Am]sunx)); 111.Ed 112.Pp 113The 114.Tn UNIX Ns -domain 115protocol family does not support broadcast addressing or any form 116of 117.Dq wildcard 118matching on incoming messages. 119All addresses are absolute- or relative-pathnames 120of other 121.Tn UNIX Ns -domain 122sockets. 123Normal filesystem access-control mechanisms are also 124applied when referencing pathnames; e.g., the destination 125of a 126.Xr connect 2 127or 128.Xr sendto 2 129must be writable. 130.Sh PROTOCOLS 131The 132.Tn UNIX Ns -domain 133protocol family comprises simple 134transport protocols that support the 135.Dv SOCK_STREAM 136and 137.Dv SOCK_DGRAM 138abstractions. 139.Dv SOCK_STREAM 140sockets also support the communication of 141.Ux 142file descriptors through the use of the 143.Ar msg_control 144field in the 145.Ar msg 146argument to 147.Xr sendmsg 2 148and 149.Xr recvmsg 2 . 150.Pp 151Any valid descriptor may be sent in a message. 152The file descriptor(s) to be passed are described using a 153.Ar struct cmsghdr 154that is defined in the include file 155.Aq Pa sys/socket.h . 156The type of the message is 157.Dv SCM_RIGHTS , 158and the data portion of the messages is an array of integers 159representing the file descriptors to be passed. 160The number of descriptors being passed is defined 161by the length field of the message; 162the length field is the sum of the size of the header 163plus the size of the array of file descriptors. 164.Pp 165The received descriptor is a 166.Em duplicate 167of the sender's descriptor, as if it were created with a call to 168.Xr dup 2 . 169Per-process descriptor flags, set with 170.Xr fcntl 2 , 171are 172.Em not 173passed to a receiver. 174Descriptors that are awaiting delivery, or that are 175purposely not received, are automatically closed by the system 176when the destination socket is closed. 177.Pp 178There is one 179.Tn socket-level 180.Xr setsockopt 2 / Ns Xr getsockopt 2 181option available in the 182.Nm 183domain. 184The 185.Dv LOCAL_CREDS 186option may be enabled on a 187.Dv SOCK_DGRAM 188or a 189.Dv SOCK_STREAM 190socket. This option provides a mechanism for the receiver to 191receive the credentials of the process as a 192.Xr recvmsg 2 193control message. The msg_control field in the msghdr structure points 194to a buffer that contains a cmsghdr structure followed by a variable 195length sockcred structure, defined in 196.Aq Pa sys/socket.h 197as follows: 198.Bd -literal 199struct sockcred { 200 uid_t sc_uid; /* real user id */ 201 uid_t sc_euid; /* effective user id */ 202 gid_t sc_gid; /* real group id */ 203 gid_t sc_egid; /* effective group id */ 204 int sc_ngroups; /* number of supplemental groups */ 205 gid_t sc_groups[1]; /* variable length */ 206}; 207.Ed 208.Pp 209The 210.Fn SOCKCREDSIZE 211macro computes the size of the sockcred structure for a specified number 212of groups. 213The cmsghdr fields have the following values: 214.Bd -literal 215cmsg_len = sizeof(struct cmsghdr) + SOCKCREDSIZE(ngroups) 216cmsg_level = SOL_SOCKET 217cmsg_type = SCM_CREDS 218.Ed 219.Sh SEE ALSO 220.Xr socket 2 , 221.Xr intro 4 222.Rs 223.%T "An Introductory 4.4BSD Interprocess Communication Tutorial" 224.%A Stuart Sechrest 225.Re 226.Pq see Pa /usr/share/doc/psd/20.ipctut 227.Rs 228.%T "Advanced 4.4BSD IPC Tutorial" 229.%A Samuel J. Leffler 230.%A Robert S. Fabry 231.%A William N. Joy 232.%A Phil Lapsley 233.%A Steve Miller 234.%A Chris Torek 235.Re 236.Pq see Pa /usr/share/doc/psd/21.ipc 237