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$
  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
  45 The
  46 .Ux Ns -domain
  47 protocol family is a collection of protocols
  48 that provides local (on-machine) interprocess
  49 communication through the normal
  50 .Xr socket 2
  51 mechanisms.
  52 The
  53 .Ux Ns -domain
  54 family supports the
  55 .Dv SOCK_STREAM
  56 and
  57 .Dv SOCK_DGRAM
  58 socket types and uses
  59 file system pathnames for addressing.
  60 .Sh ADDRESSING
  61 .Ux Ns -domain
  62 addresses are variable-length file system pathnames of
  63 at most 104 characters.
  64 The include file
  65 .In sys/un.h
  66 defines this address:
  67 .Bd -literal -offset indent
  68 struct sockaddr_un {
  69         u_char  sun_len;
  70         u_char  sun_family;
  71         char    sun_path[104];
  72 };
  73 .Ed
  74 .Pp
  75 Binding a name to a
  76 .Ux Ns -domain
  77 socket with
  78 .Xr bind 2
  79 causes a socket file to be created in the file system.
  80 This file is
  81 .Em not
  82 removed when the socket is closed \(em
  83 .Xr unlink 2
  84 must be used to remove the file.
  85 .Pp
  86 The length of
  87 .Ux Ns -domain
  88 address, required by
  89 .Xr bind 2
  90 and
  91 .Xr connect 2 ,
  92 can be calculated by the macro
  93 .Fn SUN_LEN
  94 defined in
  95 .In sys/un.h .
  96 The
  97 .Va sun_path
  98 field must be terminated by a
  99 .Dv NUL
 100 character to be used with
 101 .Fn SUN_LEN ,
 102 but the terminating
 103 .Dv NUL
 104 is
 105 .Em not
 106 part of the address.
 107 .Pp
 108 The
 109 .Ux Ns -domain
 110 protocol family does not support broadcast addressing or any form
 111 of
 112 .Dq wildcard
 113 matching on incoming messages.
 114 All addresses are absolute- or relative-pathnames
 115 of other
 116 .Ux Ns -domain
 117 sockets.
 118 Normal file system access-control mechanisms are also
 119 applied when referencing pathnames; e.g., the destination
 120 of a
 121 .Xr connect 2
 122 or
 123 .Xr sendto 2
 124 must be writable.
 125 .Sh PROTOCOLS
 126 The
 127 .Ux Ns -domain
 128 protocol family is comprised of simple
 129 transport protocols that support the
 130 .Dv SOCK_STREAM
 131 and
 132 .Dv SOCK_DGRAM
 133 abstractions.
 134 .Dv SOCK_STREAM
 135 sockets also support the communication of
 136 .Ux
 137 file descriptors through the use of the
 138 .Va msg_control
 139 field in the
 140 .Fa msg
 141 argument to
 142 .Xr sendmsg 2
 143 and
 144 .Xr recvmsg 2 .
 145 .Pp
 146 Any valid descriptor may be sent in a message.
 147 The file descriptor(s) to be passed are described using a
 148 .Vt "struct cmsghdr"
 149 that is defined in the include file
 150 .In sys/socket.h .
 151 The type of the message is
 152 .Dv SCM_RIGHTS ,
 153 and the data portion of the messages is an array of integers
 154 representing the file descriptors to be passed.
 155 The number of descriptors being passed is defined
 156 by the length field of the message;
 157 the length field is the sum of the size of the header
 158 plus the size of the array of file descriptors.
 159 .Pp
 160 The received descriptor is a
 161 .Em duplicate
 162 of the sender's descriptor, as if it were created with a call to
 163 .Xr dup 2 .
 164 Per-process descriptor flags, set with
 165 .Xr fcntl 2 ,
 166 are
 167 .Em not
 168 passed to a receiver.
 169 Descriptors that are awaiting delivery, or that are
 170 purposely not received, are automatically closed by the system
 171 when the destination socket is closed.
 172 .Pp
 173 The effective credentials (i.e., the user ID and group list) of a
 174 peer on a
 175 .Dv SOCK_STREAM
 176 socket may be obtained using the
 177 .Dv LOCAL_PEERCRED
 178 socket option.
 179 This may be used by a server to obtain and verify the credentials of
 180 its client, and vice versa by the client to verify the credentials
 181 of the server.
 182 These will arrive in the form of a filled in
 183 .Vt "struct xucred"
 184 (defined in
 185 .In sys/ucred.h ) .
 186 The credentials presented to the server (the
 187 .Xr listen 2
 188 caller) are those of the client when it called
 189 .Xr connect 2 ;
 190 the credentials presented to the client (the
 191 .Xr connect 2
 192 caller) are those of the server when it called
 193 .Xr listen 2 .
 194 This mechanism is reliable; there is no way for either party to influence
 195 the credentials presented to its peer except by calling the appropriate
 196 system call (e.g.,
 197 .Xr connect 2
 198 or
 199 .Xr listen 2 )
 200 under different effective credentials.
 201 .Pp
 202 .Tn UNIX
 203 domain sockets support a number of socket options which can be set with
 204 .Xr setsockopt 2
 205 and tested with
 206 .Xr getsockopt 2 :
 207 .Bl -tag -width ".Dv LOCAL_CONNWAIT"
 208 .It Dv LOCAL_CREDS
 209 This option may be enabled on a
 210 .Dv SOCK_DGRAM
 211 or a
 212 .Dv SOCK_STREAM
 213 socket.
 214 This option provides a mechanism for the receiver to
 215 receive the credentials of the process as a
 216 .Xr recvmsg 2
 217 control message.
 218 The
 219 .Va msg_control
 220 field in the
 221 .Vt msghdr
 222 structure points to a buffer that contains a
 223 .Vt cmsghdr
 224 structure followed by a variable length
 225 .Vt sockcred
 226 structure, defined in
 227 .In sys/socket.h
 228 as follows:
 229 .Bd -literal
 230 struct sockcred {
 231   uid_t sc_uid;         /* real user id */
 232   uid_t sc_euid;        /* effective user id */
 233   gid_t sc_gid;         /* real group id */
 234   gid_t sc_egid;        /* effective group id */
 235   int   sc_ngroups;     /* number of supplemental groups */
 236   gid_t sc_groups[1];   /* variable length */
 237 };
 238 .Ed
 239 .Pp
 240 The
 241 .Fn SOCKCREDSIZE
 242 macro computes the size of the
 243 .Vt sockcred
 244 structure for a specified number
 245 of groups.
 246 The
 247 .Vt cmsghdr
 248 fields have the following values:
 249 .Bd -literal
 250 cmsg_len = CMSG_LEN(SOCKCREDSIZE(ngroups))
 251 cmsg_level = SOL_SOCKET
 252 cmsg_type = SCM_CREDS
 253 .Ed
 254 .It Dv LOCAL_CONNWAIT
 255 Used with
 256 .Dv SOCK_STREAM
 257 sockets, this option causes the
 258 .Xr connect 2
 259 function to block until
 260 .Xr accept 2
 261 has been called on the listening socket.
 262 .El
 263 .Sh SEE ALSO
 264 .Xr socket 2 ,
 265 .Xr intro 4
 266 .Rs
 267 .%T "An Introductory 4.3 BSD Interprocess Communication Tutorial"
 268 .%B PS1
 269 .%N 7
 270 .Re
 271 .Rs
 272 .%T "An Advanced 4.3 BSD Interprocess Communication Tutorial"
 273 .%B PS1
 274 .%N 8
 275 .Re