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$ 34.\" 35.Dd July 15, 2001 36.Dt UNIX 4 37.Os 38.Sh NAME 39.Nm unix 40.Nd UNIX-domain protocol family 41.Sh SYNOPSIS 42.In sys/types.h 43.In sys/un.h 44.Sh DESCRIPTION 45The 46.Ux Ns -domain 47protocol family is a collection of protocols 48that provides local (on-machine) interprocess 49communication through the normal 50.Xr socket 2 51mechanisms. 52The 53.Ux Ns -domain 54family supports the 55.Dv SOCK_STREAM 56and 57.Dv SOCK_DGRAM 58socket types and uses 59filesystem pathnames for addressing. 60.Sh ADDRESSING 61.Ux Ns -domain 62addresses are variable-length filesystem pathnames of 63at most 104 characters. 64The include file 65.Aq Pa sys/un.h 66defines this address: 67.Bd -literal -offset indent 68struct sockaddr_un { 69u_char sun_len; 70u_char sun_family; 71char sun_path[104]; 72}; 73.Ed 74.Pp 75Binding a name to a 76.Ux Ns -domain 77socket with 78.Xr bind 2 79causes a socket file to be created in the filesystem. 80This file is 81.Em not 82removed when the socket is closed \(em 83.Xr unlink 2 84must be used to remove the file. 85.Pp 86The 87.Ux Ns -domain 88protocol family does not support broadcast addressing or any form 89of 90.Dq wildcard 91matching on incoming messages. 92All addresses are absolute- or relative-pathnames 93of other 94.Ux Ns -domain 95sockets. 96Normal filesystem access-control mechanisms are also 97applied when referencing pathnames; e.g., the destination 98of a 99.Xr connect 2 100or 101.Xr sendto 2 102must be writable. 103.Sh PROTOCOLS 104The 105.Ux Ns -domain 106protocol family is comprised of simple 107transport protocols that support the 108.Dv SOCK_STREAM 109and 110.Dv SOCK_DGRAM 111abstractions. 112.Dv SOCK_STREAM 113sockets also support the communication of 114.Ux 115file descriptors through the use of the 116.Va msg_control 117field in the 118.Fa msg 119argument to 120.Xr sendmsg 2 121and 122.Xr recvmsg 2 . 123.Pp 124Any valid descriptor may be sent in a message. 125The file descriptor(s) to be passed are described using a 126.Vt "struct cmsghdr" 127that is defined in the include file 128.Aq Pa sys/socket.h . 129The type of the message is 130.Dv SCM_RIGHTS , 131and the data portion of the messages is an array of integers 132representing the file descriptors to be passed. 133The number of descriptors being passed is defined 134by the length field of the message; 135the length field is the sum of the size of the header 136plus the size of the array of file descriptors. 137.Pp 138The received descriptor is a 139.Em duplicate 140of the sender's descriptor, as if it were created with a call to 141.Xr dup 2 . 142Per-process descriptor flags, set with 143.Xr fcntl 2 , 144are 145.Em not 146passed to a receiver. 147Descriptors that are awaiting delivery, or that are 148purposely not received, are automatically closed by the system 149when the destination socket is closed. 150.Pp 151The effective credentials (i.e., the user ID and group list) of a 152peer on a 153.Dv SOCK_STREAM 154socket may be obtained using the 155.Dv LOCAL_PEERCRED 156socket option. 157This may be used by a server to obtain and verify the credentials of 158its client, and vice versa by the client to verify the credentials 159of the server. 160These will arrive in the form of a filled in 161.Vt "struct xucred" 162(defined in 163.Aq Pa sys/ucred.h ) . 164The credentials presented to the server (the 165.Xr listen 2 166caller) are those of the client when it called 167.Xr connect 2 ; 168the credentials presented to the client (the 169.Xr connect 2 170caller) are those of the server when it called 171.Xr listen 2 . 172This mechanism is reliable; there is no way for either party to influence 173the credentials presented to its peer except by calling the appropriate 174system call (e.g., 175.Xr connect 2 176or 177.Xr listen 2 ) 178under different effective credentials. 179.Sh SEE ALSO 180.Xr socket 2 , 181.Xr intro 4 182.Rs 183.%T "An Introductory 4.3 BSD Interprocess Communication Tutorial" 184.%B PS1 185.%N 7 186.Re 187.Rs 188.%T "An Advanced 4.3 BSD Interprocess Communication Tutorial" 189.%B PS1 190.%N 8 191.Re 192