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 February 3, 2017
  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 CONTROL MESSAGES
 127 The
 128 .Ux Ns -domain
 129 sockets support the communication of
 130 .Ux
 131 file descriptors and process credentials 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 The items to be passed are described using a
 140 .Vt "struct cmsghdr"
 141 that is defined in the include file
 142 .In sys/socket.h .
 143 .Pp
 144 To send file descriptors, the type of the message is
 145 .Dv SCM_RIGHTS ,
 146 and the data portion of the messages is an array of integers
 147 representing the file descriptors to be passed.
 148 The number of descriptors being passed is defined
 149 by the length field of the message;
 150 the length field is the sum of the size of the header
 151 plus the size of the array of file descriptors.
 152 .Pp
 153 The received descriptor is a
 154 .Em duplicate
 155 of the sender's descriptor, as if it were created via
 156 .Li dup(fd)
 157 or
 158 .Li fcntl(fd, F_DUPFD_CLOEXEC, 0)
 159 depending on whether
 160 .Dv MSG_CMSG_CLOEXEC
 161 is passed in the
 162 .Xr recvmsg 2
 163 call.
 164 Descriptors that are awaiting delivery, or that are
 165 purposely not received, are automatically closed by the system
 166 when the destination socket is closed.
 167 .Pp
 168 Credentials of the sending process can be transmitted explicitly using a
 169 control message of type
 170 .Dv SCM_CREDS
 171 with a data portion of type
 172 .Vt "struct cmsgcred" ,
 173 defined in
 174 .In sys/socket.h
 175 as follows:
 176 .Bd -literal
 177 struct cmsgcred {
 178   pid_t cmcred_pid;             /* PID of sending process */
 179   uid_t cmcred_uid;             /* real UID of sending process */
 180   uid_t cmcred_euid;            /* effective UID of sending process */
 181   gid_t cmcred_gid;             /* real GID of sending process */
 182   short cmcred_ngroups;         /* number of groups */
 183   gid_t cmcred_groups[CMGROUP_MAX];     /* groups */
 184 };
 185 .Ed
 186 .Pp
 187 The sender should pass a zeroed buffer which will be filled in by the system.
 188 .Pp
 189 The group list is truncated to at most
 190 .Dv CMGROUP_MAX
 191 GIDs.
 192 .Pp
 193 The process ID
 194 .Fa cmcred_pid
 195 should not be looked up (such as via the
 196 .Dv KERN_PROC_PID
 197 sysctl) for making security decisions.
 198 The sending process could have exited and its process ID already been
 199 reused for a new process.
 200 .Sh SOCKET OPTIONS
 201 .Tn UNIX
 202 domain sockets support a number of socket options which can be set with
 203 .Xr setsockopt 2
 204 and tested with
 205 .Xr getsockopt 2 :
 206 .Bl -tag -width ".Dv LOCAL_CONNWAIT"
 207 .It Dv LOCAL_CREDS
 208 This option may be enabled on
 209 .Dv SOCK_DGRAM ,
 210 .Dv SOCK_SEQPACKET ,
 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 calling
 216 .Xr write 2 ,
 217 .Xr send 2 ,
 218 .Xr sendto 2
 219 or
 220 .Xr sendmsg 2
 221 as a
 222 .Xr recvmsg 2
 223 control message.
 224 The
 225 .Va msg_control
 226 field in the
 227 .Vt msghdr
 228 structure points to a buffer that contains a
 229 .Vt cmsghdr
 230 structure followed by a variable length
 231 .Vt sockcred
 232 structure, defined in
 233 .In sys/socket.h
 234 as follows:
 235 .Bd -literal
 236 struct sockcred {
 237   uid_t sc_uid;         /* real user id */
 238   uid_t sc_euid;        /* effective user id */
 239   gid_t sc_gid;         /* real group id */
 240   gid_t sc_egid;        /* effective group id */
 241   int   sc_ngroups;     /* number of supplemental groups */
 242   gid_t sc_groups[1];   /* variable length */
 243 };
 244 .Ed
 245 .Pp
 246 The current implementation truncates the group list to at most
 247 .Dv CMGROUP_MAX
 248 groups.
 249 .Pp
 250 The
 251 .Fn SOCKCREDSIZE
 252 macro computes the size of the
 253 .Vt sockcred
 254 structure for a specified number
 255 of groups.
 256 The
 257 .Vt cmsghdr
 258 fields have the following values:
 259 .Bd -literal
 260 cmsg_len = CMSG_LEN(SOCKCREDSIZE(ngroups))
 261 cmsg_level = SOL_SOCKET
 262 cmsg_type = SCM_CREDS
 263 .Ed
 264 .Pp
 265 On
 266 .Dv SOCK_STREAM
 267 and
 268 .Dv SOCK_SEQPACKET
 269 sockets credentials are passed only on the first read from a socket,
 270 then the system clears the option on the socket.
 271 .Pp
 272 This option and the above explicit
 273 .Vt "struct cmsgcred"
 274 both use the same value
 275 .Dv SCM_CREDS
 276 but incompatible control messages.
 277 If this option is enabled and the sender attached a
 278 .Dv SCM_CREDS
 279 control message with a
 280 .Vt "struct cmsgcred" ,
 281 it will be discarded and a
 282 .Vt "struct sockcred"
 283 will be included.
 284 .Pp
 285 Many setuid programs will
 286 .Xr write 2
 287 data at least partially controlled by the invoker,
 288 such as error messages.
 289 Therefore, a message accompanied by a particular
 290 .Fa sc_euid
 291 value should not be trusted as being from that user.
 292 .It Dv LOCAL_CONNWAIT
 293 Used with
 294 .Dv SOCK_STREAM
 295 sockets, this option causes the
 296 .Xr connect 2
 297 function to block until
 298 .Xr accept 2
 299 has been called on the listening socket.
 300 .It Dv LOCAL_PEERCRED
 301 Requested via
 302 .Xr getsockopt 2
 303 on a
 304 .Dv SOCK_STREAM
 305 socket returns credentials of the remote side.
 306 These will arrive in the form of a filled in
 307 .Vt xucred
 308 structure, defined in
 309 .In sys/ucred.h
 310 as follows:
 311 .Bd -literal
 312 struct xucred {
 313   u_int cr_version;             /* structure layout version */
 314   uid_t cr_uid;                 /* effective user id */
 315   short cr_ngroups;             /* number of groups */
 316   gid_t cr_groups[XU_NGROUPS];  /* groups */
 317 };
 318 .Ed
 319 The
 320 .Vt cr_version
 321 fields should be checked against
 322 .Dv XUCRED_VERSION
 323 define.
 324 .Pp
 325 The credentials presented to the server (the
 326 .Xr listen 2
 327 caller) are those of the client when it called
 328 .Xr connect 2 ;
 329 the credentials presented to the client (the
 330 .Xr connect 2
 331 caller) are those of the server when it called
 332 .Xr listen 2 .
 333 This mechanism is reliable; there is no way for either party to influence
 334 the credentials presented to its peer except by calling the appropriate
 335 system call (e.g.,
 336 .Xr connect 2
 337 or
 338 .Xr listen 2 )
 339 under different effective credentials.
 340 .Pp
 341 To reliably obtain peer credentials on a
 342 .Dv SOCK_DGRAM
 343 socket refer to the
 344 .Dv LOCAL_CREDS
 345 socket option.
 346 .El
 347 .Sh SEE ALSO
 348 .Xr connect 2 ,
 349 .Xr dup 2 ,
 350 .Xr fcntl 2 ,
 351 .Xr getsockopt 2 ,
 352 .Xr listen 2 ,
 353 .Xr recvmsg 2 ,
 354 .Xr sendto 2 ,
 355 .Xr setsockopt 2 ,
 356 .Xr socket 2 ,
 357 .Xr intro 4
 358 .Rs
 359 .%T "An Introductory 4.3 BSD Interprocess Communication Tutorial"
 360 .%B PS1
 361 .%N 7
 362 .Re
 363 .Rs
 364 .%T "An Advanced 4.3 BSD Interprocess Communication Tutorial"
 365 .%B PS1
 366 .%N 8
 367 .Re