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