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 March 19, 2013
  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 via
 157 .Li dup(fd)
 158 or
 159 .Li fcntl(fd, F_DUPFD_CLOEXEC, 0)
 160 depending on whether
 161 .Dv MSG_CMSG_CLOEXEC
 162 is passed in the
 163 .Xr recvmsg 2
 164 call.
 165 Descriptors that are awaiting delivery, or that are
 166 purposely not received, are automatically closed by the system
 167 when the destination socket is closed.
 168 .Sh SOCKET OPTIONS
 169 .Tn UNIX
 170 domain sockets support a number of socket options which can be set with
 171 .Xr setsockopt 2
 172 and tested with
 173 .Xr getsockopt 2 :
 174 .Bl -tag -width ".Dv LOCAL_CONNWAIT"
 175 .It Dv LOCAL_CREDS
 176 This option may be enabled on
 177 .Dv SOCK_DGRAM ,
 178 .Dv SOCK_SEQPACKET ,
 179 or a
 180 .Dv SOCK_STREAM
 181 socket.
 182 This option provides a mechanism for the receiver to
 183 receive the credentials of the process as a
 184 .Xr recvmsg 2
 185 control message.
 186 The
 187 .Va msg_control
 188 field in the
 189 .Vt msghdr
 190 structure points to a buffer that contains a
 191 .Vt cmsghdr
 192 structure followed by a variable length
 193 .Vt sockcred
 194 structure, defined in
 195 .In sys/socket.h
 196 as follows:
 197 .Bd -literal
 198 struct sockcred {
 199   uid_t sc_uid;         /* real user id */
 200   uid_t sc_euid;        /* effective user id */
 201   gid_t sc_gid;         /* real group id */
 202   gid_t sc_egid;        /* effective group id */
 203   int   sc_ngroups;     /* number of supplemental groups */
 204   gid_t sc_groups[1];   /* variable length */
 205 };
 206 .Ed
 207 .Pp
 208 The
 209 .Fn SOCKCREDSIZE
 210 macro computes the size of the
 211 .Vt sockcred
 212 structure for a specified number
 213 of groups.
 214 The
 215 .Vt cmsghdr
 216 fields have the following values:
 217 .Bd -literal
 218 cmsg_len = CMSG_LEN(SOCKCREDSIZE(ngroups))
 219 cmsg_level = SOL_SOCKET
 220 cmsg_type = SCM_CREDS
 221 .Ed
 222 .Pp
 223 On
 224 .Dv SOCK_STREAM
 225 and
 226 .Dv SOCK_SEQPACKET
 227 sockets credentials are passed only on the first read from a socket,
 228 then system clears the option on socket.
 229 .It Dv LOCAL_CONNWAIT
 230 Used with
 231 .Dv SOCK_STREAM
 232 sockets, this option causes the
 233 .Xr connect 2
 234 function to block until
 235 .Xr accept 2
 236 has been called on the listening socket.
 237 .It Dv LOCAL_PEERCRED
 238 Requested via
 239 .Xr getsockopt 2
 240 on a
 241 .Dv SOCK_STREAM
 242 socket returns credentials of the remote side.
 243 These will arrive in the form of a filled in
 244 .Vt xucred
 245 structure, defined in
 246 .In sys/ucred.h
 247 as follows:
 248 .Bd -literal
 249 struct xucred {
 250   u_int cr_version;             /* structure layout version */
 251   uid_t cr_uid;                 /* effective user id */
 252   short cr_ngroups;             /* number of groups */
 253   gid_t cr_groups[XU_NGROUPS];  /* groups */
 254 };
 255 .Ed
 256 The
 257 .Vt cr_version
 258 fields should be checked against
 259 .Dv XUCRED_VERSION
 260 define.
 261 .Pp
 262 The credentials presented to the server (the
 263 .Xr listen 2
 264 caller) are those of the client when it called
 265 .Xr connect 2 ;
 266 the credentials presented to the client (the
 267 .Xr connect 2
 268 caller) are those of the server when it called
 269 .Xr listen 2 .
 270 This mechanism is reliable; there is no way for either party to influence
 271 the credentials presented to its peer except by calling the appropriate
 272 system call (e.g.,
 273 .Xr connect 2
 274 or
 275 .Xr listen 2 )
 276 under different effective credentials.
 277 .Pp
 278 To reliably obtain peer credentials on a
 279 .Dv SOCK_DGRAM
 280 socket refer to the
 281 .Dv LOCAL_CREDS
 282 socket option.
 283 .El
 284 .Sh SEE ALSO
 285 .Xr connect 2 ,
 286 .Xr dup 2 ,
 287 .Xr fcntl 2 ,
 288 .Xr getsockopt 2 ,
 289 .Xr listen 2 ,
 290 .Xr recvmsg 2 ,
 291 .Xr sendto 2 ,
 292 .Xr setsockopt 2 ,
 293 .Xr socket 2 ,
 294 .Xr intro 4
 295 .Rs
 296 .%T "An Introductory 4.3 BSD Interprocess Communication Tutorial"
 297 .%B PS1
 298 .%N 7
 299 .Re
 300 .Rs
 301 .%T "An Advanced 4.3 BSD Interprocess Communication Tutorial"
 302 .%B PS1
 303 .%N 8
 304 .Re