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