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