1.\" $NetBSD: unix.4,v 1.19 2007/08/09 15:23:03 he 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 are two 172.Tn socket-level 173.Xr setsockopt 2 / Ns Xr getsockopt 2 174option available in the 175.Nm 176domain: 177.Pp 178The 179.Dv LOCAL_CREDS 180option may be enabled on a 181.Dv SOCK_DGRAM 182or a 183.Dv SOCK_STREAM 184socket. 185This option provides a mechanism for the receiver to 186receive the credentials of the process as a 187.Xr recvmsg 2 188control message. 189The msg_control field in the msghdr structure points 190to a buffer that contains a cmsghdr structure followed by a variable 191length sockcred structure, defined in 192.Aq Pa sys/socket.h 193as follows: 194.Bd -literal 195struct sockcred { 196 uid_t sc_uid; /* real user id */ 197 uid_t sc_euid; /* effective user id */ 198 gid_t sc_gid; /* real group id */ 199 gid_t sc_egid; /* effective group id */ 200 int sc_ngroups; /* number of supplemental groups */ 201 gid_t sc_groups[1]; /* variable length */ 202}; 203.Ed 204.Pp 205The 206.Dv LOCAL_PEEREID 207option may be used with 208.Xr getsockopt 2 209to get the PID and effective user and group IDs of a 210.Dv SOCK_STREAM 211peer when it did 212.Xr connect 2 213or 214.Xr bind 2 . 215The returned structure is 216.Bd -literal 217struct unpcbid { 218 pid_t unp_pid; /* process id */ 219 uid_t unp_euid; /* effective user id */ 220 gid_t unp_egid; /* effective group id */ 221}; 222.Ed 223as defined in 224.Aq Pa sys/un.h . 225.Pp 226The 227.Fn SOCKCREDSIZE 228macro computes the size of the sockcred structure for a specified number 229of groups. 230The cmsghdr fields have the following values: 231.Bd -literal 232cmsg_len = sizeof(struct cmsghdr) + SOCKCREDSIZE(ngroups) 233cmsg_level = SOL_SOCKET 234cmsg_type = SCM_CREDS 235.Ed 236.Sh EXAMPLES 237The following code fragment shows how to bind a socket to pathname: 238.Bd -literal -offset indent 239const char *pathname = "/path/to/socket"; 240struct sockaddr_un addr; 241int ret; 242 243memset(\*[Am]addr, 0, sizeof(addr)); 244addr.sun_family = AF_LOCAL; 245if (strlen(pathname) \*[Ge] sizeof(addr.sun_path)) 246 goto too_long; 247strncpy(addr.sun_path, pathname, sizeof(addr.sun_path)); 248ret = bind(s, (const struct sockaddr *)\*[Am]addr, SUN_LEN(\*[Am]addr)); 249if (ret != 0) 250 goto bind_failed; 251\&... 252 253.Ed 254.Sh COMPATIBILITY 255The 256.Ar sun_len 257field exists only in system derived from 4.4BSD. 258On systems which don't have the 259.Fn SUN_LEN 260macro, the following definition is recommended: 261.Bd -literal -offset indent 262#ifndef SUN_LEN 263#define SUN_LEN(su) sizeof(struct(sockaddr_un)) 264#endif 265.Ed 266.Sh SEE ALSO 267.Xr socket 2 , 268.Xr intro 4 269.Rs 270.%T "An Introductory 4.4BSD Interprocess Communication Tutorial" 271.%A Stuart Sechrest 272.Re 273.Pq see Pa /usr/share/doc/psd/20.ipctut 274.Rs 275.%T "Advanced 4.4BSD IPC Tutorial" 276.%A Samuel J. Leffler 277.%A Robert S. Fabry 278.%A William N. Joy 279.%A Phil Lapsley 280.%A Steve Miller 281.%A Chris Torek 282.Re 283.Pq see Pa /usr/share/doc/psd/21.ipc 284