1.\" $OpenBSD: unix.4,v 1.6 2003/06/02 23:30:13 millert Exp $ 2.\" $NetBSD: unix.4,v 1.3 1994/11/30 16:22:43 jtc Exp $ 3.\" 4.\" Copyright (c) 1991, 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the University nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" @(#)unix.4 8.1 (Berkeley) 6/9/93 32.\" 33.Dd June 9, 1993 34.Dt UNIX 4 35.Os 36.Sh NAME 37.Nm unix 38.Nd UNIX-domain protocol family 39.Sh SYNOPSIS 40.Fd #include <sys/types.h> 41.Fd #include <sys/un.h> 42.Sh DESCRIPTION 43The 44.Tn UNIX Ns -domain 45protocol family is a collection of protocols 46that provides local (on-machine) interprocess 47communication through the normal 48.Xr socket 2 49mechanisms. 50The 51.Tn UNIX Ns -domain 52family supports the 53.Dv SOCK_STREAM 54and 55.Dv SOCK_DGRAM 56socket types and uses 57filesystem pathnames for addressing. 58.Sh ADDRESSING 59.Tn UNIX Ns -domain 60addresses are variable-length filesystem pathnames of 61at most 104 characters. 62The include file 63.Aq Pa sys/un.h 64defines this address: 65.Bd -literal -offset indent 66struct sockaddr_un { 67 u_char sun_len; 68 u_char sun_family; 69 char sun_path[104]; 70}; 71.Ed 72.Pp 73Binding a name to a 74.Tn UNIX 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\c 81.Xr unlink 2 82must be used to remove the file. 83.Pp 84The 85.Tn UNIX 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.Tn UNIX 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.Tn UNIX Ns -domain 104protocol family is comprised of simple 105transport protocols that support the 106.Dv SOCK_STREAM 107and 108.Dv SOCK_DGRAM 109abstractions. 110.Dv SOCK_STREAM 111sockets also support the communication of 112.Ux 113file descriptors through the use of the 114.Ar msg_control 115field in the 116.Ar msg 117argument to 118.Xr sendmsg 2 119and 120.Xr recvmsg 2 . 121.Pp 122Any valid descriptor may be sent in a message. 123The file descriptor(s) to be passed are described using a 124.Ar struct cmsghdr 125that is defined in the include file 126.Aq Pa sys/socket.h . 127The type of the message is 128.Dv SCM_RIGHTS , 129and the data portion of the messages is an array of integers 130representing the file descriptors to be passed. 131The number of descriptors being passed is defined 132by the length field of the message; 133the length field is the sum of the size of the header 134plus the size of the array of file descriptors. 135.Pp 136The received descriptor is a 137.Em duplicate 138of the sender's descriptor, as if it were created with a call to 139.Xr dup 2 . 140Per-process descriptor flags, set with 141.Xr fcntl 2 , 142are 143.Em not 144passed to a receiver. 145Descriptors that are awaiting delivery, or that are 146purposely not received, are automatically closed by the system 147when the destination socket is closed. 148.Sh SEE ALSO 149.Xr socket 2 , 150.Xr netintro 4 151.Rs 152.%T "An Introductory 4.3 BSD Interprocess Communication Tutorial" 153.%B PS1 154.%N 7 155.Re 156.Rs 157.%T "An Advanced 4.3 BSD Interprocess Communication Tutorial" 158.%B PS1 159.%N 8 160.Re 161