1.\" Copyright (c) 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" @(#)unix.4 8.1 (Berkeley) 6/9/93 29.\" $FreeBSD: src/share/man/man4/unix.4,v 1.3.2.4 2002/04/22 08:59:53 dd Exp $ 30.\" $DragonFly: src/share/man/man4/unix.4,v 1.3 2006/05/26 19:39:39 swildner Exp $ 31.\" 32.Dd July 15, 2001 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.Ux 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.Ux Ns -domain 51family supports the 52.Dv SOCK_STREAM , 53.Dv SOCK_DGRAM 54and 55.Dv SOCK_SEQPACKET 56socket types and uses 57filesystem pathnames for addressing. 58.Sh ADDRESSING 59.Ux 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 { 67u_char sun_len; 68u_char sun_family; 69char sun_path[104]; 70}; 71.Ed 72.Pp 73Binding a name to a 74.Ux 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 81.Xr unlink 2 82must be used to remove the file. 83.Pp 84The 85.Ux Ns -domain 86protocol family does not support broadcast addressing or any form 87of 88.Dq wildcard 89matching on incoming messages. 90All addresses are absolute- or relative-pathnames 91of other 92.Ux Ns -domain 93sockets. 94Normal filesystem access-control mechanisms are also 95applied when referencing pathnames; e.g., the destination 96of a 97.Xr connect 2 98or 99.Xr sendto 2 100must be writable. 101.Sh PROTOCOLS 102The 103.Ux Ns -domain 104protocol family is comprised of simple 105transport protocols that support the 106.Dv SOCK_STREAM , 107.Dv SOCK_DGRAM 108and 109.Dv SOCK_SEQPACKET 110abstractions. 111.Dv SOCK_STREAM , 112.Dv SOCK_DGRAM 113and 114.Dv SOCK_SEQPACKET 115sockets also support the communication of 116.Ux 117file descriptors through the use of the 118.Va msg_control 119field in the 120.Fa msg 121argument to 122.Xr sendmsg 2 123and 124.Xr recvmsg 2 . 125.Pp 126Any valid descriptor may be sent in a message. 127The file descriptor(s) to be passed are described using a 128.Vt "struct cmsghdr" 129that is defined in the include file 130.In sys/socket.h . 131The type of the message is 132.Dv SCM_RIGHTS , 133and the data portion of the messages is an array of integers 134representing the file descriptors to be passed. 135The number of descriptors being passed is defined 136by the length field of the message; 137the length field is the sum of the size of the header 138plus the size of the array of file descriptors. 139.Pp 140The received descriptor is a 141.Em duplicate 142of the sender's descriptor, as if it were created with a call to 143.Xr dup 2 . 144Per-process descriptor flags, set with 145.Xr fcntl 2 , 146are 147.Em not 148passed to a receiver. 149Descriptors that are awaiting delivery, or that are 150purposely not received, are automatically closed by the system 151when the destination socket is closed. 152.Pp 153The effective credentials (i.e., the user ID and group list) of a 154peer on a 155.Dv SOCK_STREAM 156socket may be obtained using the 157.Dv LOCAL_PEERCRED 158socket option. 159This may be used by a server to obtain and verify the credentials of 160its client, and vice versa by the client to verify the credentials 161of the server. 162These will arrive in the form of a filled in 163.Vt "struct xucred" 164(defined in 165.In sys/ucred.h ) . 166The credentials presented to the server (the 167.Xr listen 2 168caller) are those of the client when it called 169.Xr connect 2 ; 170the credentials presented to the client (the 171.Xr connect 2 172caller) are those of the server when it called 173.Xr listen 2 . 174This mechanism is reliable; there is no way for either party to influence 175the credentials presented to its peer except by calling the appropriate 176system call (e.g., 177.Xr connect 2 178or 179.Xr listen 2 ) 180under different effective credentials. 181.Sh SEE ALSO 182.Xr socket 2 , 183.Xr intro 4 184.Rs 185.%T "An Introductory 4.3 BSD Interprocess Communication Tutorial" 186.%B PS1 187.%N 7 188.Re 189.Rs 190.%T "An Advanced 4.3 BSD Interprocess Communication Tutorial" 191.%B PS1 192.%N 8 193.Re 194