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. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)unix.4      8.1 (Berkeley) 6/9/93
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd March 19, 2013
  32 .Dt UNIX 4
  33 .Os
  34 .Sh NAME
  35 .Nm unix
  36 .Nd UNIX-domain protocol family
  37 .Sh SYNOPSIS
  38 .In sys/types.h
  39 .In sys/un.h
  40 .Sh DESCRIPTION
  41 The
  42 .Ux Ns -domain
  43 protocol family is a collection of protocols
  44 that provides local (on-machine) interprocess
  45 communication through the normal
  46 .Xr socket 2
  47 mechanisms.
  48 The
  49 .Ux Ns -domain
  50 family supports the
  51 .Dv SOCK_STREAM ,
  52 .Dv SOCK_SEQPACKET ,
  53 and
  54 .Dv SOCK_DGRAM
  55 socket types and uses
  56 file system pathnames for addressing.
  57 .Sh ADDRESSING
  58 .Ux Ns -domain
  59 addresses are variable-length file system pathnames of
  60 at most 104 characters.
  61 The include file
  62 .In sys/un.h
  63 defines this address:
  64 .Bd -literal -offset indent
  65 struct sockaddr_un {
  66         u_char  sun_len;
  67         u_char  sun_family;
  68         char    sun_path[104];
  69 };
  70 .Ed
  71 .Pp
  72 Binding a name to a
  73 .Ux Ns -domain
  74 socket with
  75 .Xr bind 2
  76 causes a socket file to be created in the file system.
  77 This file is
  78 .Em not
  79 removed when the socket is closed \(em
  80 .Xr unlink 2
  81 must be used to remove the file.
  82 .Pp
  83 The length of
  84 .Ux Ns -domain
  85 address, required by
  86 .Xr bind 2
  87 and
  88 .Xr connect 2 ,
  89 can be calculated by the macro
  90 .Fn SUN_LEN
  91 defined in
  92 .In sys/un.h .
  93 The
  94 .Va sun_path
  95 field must be terminated by a
  96 .Dv NUL
  97 character to be used with
  98 .Fn SUN_LEN ,
  99 but the terminating
 100 .Dv NUL
 101 is
 102 .Em not
 103 part of the address.
 104 .Pp
 105 The
 106 .Ux Ns -domain
 107 protocol family does not support broadcast addressing or any form
 108 of
 109 .Dq wildcard
 110 matching on incoming messages.
 111 All addresses are absolute- or relative-pathnames
 112 of other
 113 .Ux Ns -domain
 114 sockets.
 115 Normal file system access-control mechanisms are also
 116 applied when referencing pathnames; e.g., the destination
 117 of a
 118 .Xr connect 2
 119 or
 120 .Xr sendto 2
 121 must be writable.
 122 .Sh PASSING FILE DESCRIPTORS
 123 The
 124 .Ux Ns -domain
 125 sockets support the communication of
 126 .Ux
 127 file descriptors through the use of the
 128 .Va msg_control
 129 field in the
 130 .Fa msg
 131 argument to
 132 .Xr sendmsg 2
 133 and
 134 .Xr recvmsg 2 .
 135 .Pp
 136 Any valid descriptor may be sent in a message.
 137 The file descriptor(s) to be passed are described using a
 138 .Vt "struct cmsghdr"
 139 that is defined in the include file
 140 .In sys/socket.h .
 141 The type of the message is
 142 .Dv SCM_RIGHTS ,
 143 and the data portion of the messages is an array of integers
 144 representing the file descriptors to be passed.
 145 The number of descriptors being passed is defined
 146 by the length field of the message;
 147 the length field is the sum of the size of the header
 148 plus the size of the array of file descriptors.
 149 .Pp
 150 The received descriptor is a
 151 .Em duplicate
 152 of the sender's descriptor, as if it were created via
 153 .Li dup(fd)
 154 or
 155 .Li fcntl(fd, F_DUPFD_CLOEXEC, 0)
 156 depending on whether
 157 .Dv MSG_CMSG_CLOEXEC
 158 is passed in the
 159 .Xr recvmsg 2
 160 call.
 161 Descriptors that are awaiting delivery, or that are
 162 purposely not received, are automatically closed by the system
 163 when the destination socket is closed.
 164 .Sh SOCKET OPTIONS
 165 .Tn UNIX
 166 domain sockets support a number of socket options which can be set with
 167 .Xr setsockopt 2
 168 and tested with
 169 .Xr getsockopt 2 :
 170 .Bl -tag -width ".Dv LOCAL_CONNWAIT"
 171 .It Dv LOCAL_CREDS
 172 This option may be enabled on
 173 .Dv SOCK_DGRAM ,
 174 .Dv SOCK_SEQPACKET ,
 175 or a
 176 .Dv SOCK_STREAM
 177 socket.
 178 This option provides a mechanism for the receiver to
 179 receive the credentials of the process as a
 180 .Xr recvmsg 2
 181 control message.
 182 The
 183 .Va msg_control
 184 field in the
 185 .Vt msghdr
 186 structure points to a buffer that contains a
 187 .Vt cmsghdr
 188 structure followed by a variable length
 189 .Vt sockcred
 190 structure, defined in
 191 .In sys/socket.h
 192 as follows:
 193 .Bd -literal
 194 struct sockcred {
 195   uid_t sc_uid;         /* real user id */
 196   uid_t sc_euid;        /* effective user id */
 197   gid_t sc_gid;         /* real group id */
 198   gid_t sc_egid;        /* effective group id */
 199   int   sc_ngroups;     /* number of supplemental groups */
 200   gid_t sc_groups[1];   /* variable length */
 201 };
 202 .Ed
 203 .Pp
 204 The
 205 .Fn SOCKCREDSIZE
 206 macro computes the size of the
 207 .Vt sockcred
 208 structure for a specified number
 209 of groups.
 210 The
 211 .Vt cmsghdr
 212 fields have the following values:
 213 .Bd -literal
 214 cmsg_len = CMSG_LEN(SOCKCREDSIZE(ngroups))
 215 cmsg_level = SOL_SOCKET
 216 cmsg_type = SCM_CREDS
 217 .Ed
 218 .Pp
 219 On
 220 .Dv SOCK_STREAM
 221 and
 222 .Dv SOCK_SEQPACKET
 223 sockets credentials are passed only on the first read from a socket,
 224 then system clears the option on socket.
 225 .It Dv LOCAL_CONNWAIT
 226 Used with
 227 .Dv SOCK_STREAM
 228 sockets, this option causes the
 229 .Xr connect 2
 230 function to block until
 231 .Xr accept 2
 232 has been called on the listening socket.
 233 .It Dv LOCAL_PEERCRED
 234 Requested via
 235 .Xr getsockopt 2
 236 on a
 237 .Dv SOCK_STREAM
 238 socket returns credentials of the remote side.
 239 These will arrive in the form of a filled in
 240 .Vt xucred
 241 structure, defined in
 242 .In sys/ucred.h
 243 as follows:
 244 .Bd -literal
 245 struct xucred {
 246   u_int cr_version;             /* structure layout version */
 247   uid_t cr_uid;                 /* effective user id */
 248   short cr_ngroups;             /* number of groups */
 249   gid_t cr_groups[XU_NGROUPS];  /* groups */
 250 };
 251 .Ed
 252 The
 253 .Vt cr_version
 254 fields should be checked against
 255 .Dv XUCRED_VERSION
 256 define.
 257 .Pp
 258 The credentials presented to the server (the
 259 .Xr listen 2
 260 caller) are those of the client when it called
 261 .Xr connect 2 ;
 262 the credentials presented to the client (the
 263 .Xr connect 2
 264 caller) are those of the server when it called
 265 .Xr listen 2 .
 266 This mechanism is reliable; there is no way for either party to influence
 267 the credentials presented to its peer except by calling the appropriate
 268 system call (e.g.,
 269 .Xr connect 2
 270 or
 271 .Xr listen 2 )
 272 under different effective credentials.
 273 .Pp
 274 To reliably obtain peer credentials on a
 275 .Dv SOCK_DGRAM
 276 socket refer to the
 277 .Dv LOCAL_CREDS
 278 socket option.
 279 .El
 280 .Sh SEE ALSO
 281 .Xr connect 2 ,
 282 .Xr dup 2 ,
 283 .Xr fcntl 2 ,
 284 .Xr getsockopt 2 ,
 285 .Xr listen 2 ,
 286 .Xr recvmsg 2 ,
 287 .Xr sendto 2 ,
 288 .Xr setsockopt 2 ,
 289 .Xr socket 2 ,
 290 .Xr intro 4
 291 .Rs
 292 .%T "An Introductory 4.3 BSD Interprocess Communication Tutorial"
 293 .%B PS1
 294 .%N 7
 295 .Re
 296 .Rs
 297 .%T "An Advanced 4.3 BSD Interprocess Communication Tutorial"
 298 .%B PS1
 299 .%N 8
 300 .Re