share/man/man4/unix.4

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