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 October 5, 2009
  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 PROTOCOLS
 127 The
 128 .Ux Ns -domain
 129 protocol family is comprised of simple
 130 transport protocols that support the
 131 .Dv SOCK_STREAM ,
 132 .Dv SOCK_SEQPACKET ,
 133 and
 134 .Dv SOCK_DGRAM
 135 abstractions.
 136 .Dv SOCK_STREAM
 137 and
 138 .Dv SOCK_SEQPACKET
 139 sockets also support the communication of
 140 .Ux
 141 file descriptors through the use of the
 142 .Va msg_control
 143 field in the
 144 .Fa msg
 145 argument to
 146 .Xr sendmsg 2
 147 and
 148 .Xr recvmsg 2 .
 149 .Pp
 150 Any valid descriptor may be sent in a message.
 151 The file descriptor(s) to be passed are described using a
 152 .Vt "struct cmsghdr"
 153 that is defined in the include file
 154 .In sys/socket.h .
 155 The type of the message is
 156 .Dv SCM_RIGHTS ,
 157 and the data portion of the messages is an array of integers
 158 representing the file descriptors to be passed.
 159 The number of descriptors being passed is defined
 160 by the length field of the message;
 161 the length field is the sum of the size of the header
 162 plus the size of the array of file descriptors.
 163 .Pp
 164 The received descriptor is a
 165 .Em duplicate
 166 of the sender's descriptor, as if it were created with a call to
 167 .Xr dup 2 .
 168 Per-process descriptor flags, set with
 169 .Xr fcntl 2 ,
 170 are
 171 .Em not
 172 passed to a receiver.
 173 Descriptors that are awaiting delivery, or that are
 174 purposely not received, are automatically closed by the system
 175 when the destination socket is closed.
 176 .Pp
 177 The effective credentials (i.e., the user ID and group list) of a
 178 peer on a
 179 .Dv SOCK_STREAM
 180 socket may be obtained using the
 181 .Dv LOCAL_PEERCRED
 182 socket option.
 183 This may be used by a server to obtain and verify the credentials of
 184 its client, and vice versa by the client to verify the credentials
 185 of the server.
 186 These will arrive in the form of a filled in
 187 .Vt "struct xucred"
 188 (defined in
 189 .In sys/ucred.h ) .
 190 The credentials presented to the server (the
 191 .Xr listen 2
 192 caller) are those of the client when it called
 193 .Xr connect 2 ;
 194 the credentials presented to the client (the
 195 .Xr connect 2
 196 caller) are those of the server when it called
 197 .Xr listen 2 .
 198 This mechanism is reliable; there is no way for either party to influence
 199 the credentials presented to its peer except by calling the appropriate
 200 system call (e.g.,
 201 .Xr connect 2
 202 or
 203 .Xr listen 2 )
 204 under different effective credentials.
 205 .Pp
 206 .Tn UNIX
 207 domain sockets support a number of socket options which can be set with
 208 .Xr setsockopt 2
 209 and tested with
 210 .Xr getsockopt 2 :
 211 .Bl -tag -width ".Dv LOCAL_CONNWAIT"
 212 .It Dv LOCAL_CREDS
 213 This option may be enabled on
 214 .Dv SOCK_DGRAM ,
 215 .Dv SOCK_SEQPACKET ,
 216 or a
 217 .Dv SOCK_STREAM
 218 socket.
 219 This option provides a mechanism for the receiver to
 220 receive the credentials of the process as a
 221 .Xr recvmsg 2
 222 control message.
 223 The
 224 .Va msg_control
 225 field in the
 226 .Vt msghdr
 227 structure points to a buffer that contains a
 228 .Vt cmsghdr
 229 structure followed by a variable length
 230 .Vt sockcred
 231 structure, defined in
 232 .In sys/socket.h
 233 as follows:
 234 .Bd -literal
 235 struct sockcred {
 236   uid_t sc_uid;         /* real user id */
 237   uid_t sc_euid;        /* effective user id */
 238   gid_t sc_gid;         /* real group id */
 239   gid_t sc_egid;        /* effective group id */
 240   int   sc_ngroups;     /* number of supplemental groups */
 241   gid_t sc_groups[1];   /* variable length */
 242 };
 243 .Ed
 244 .Pp
 245 The
 246 .Fn SOCKCREDSIZE
 247 macro computes the size of the
 248 .Vt sockcred
 249 structure for a specified number
 250 of groups.
 251 The
 252 .Vt cmsghdr
 253 fields have the following values:
 254 .Bd -literal
 255 cmsg_len = CMSG_LEN(SOCKCREDSIZE(ngroups))
 256 cmsg_level = SOL_SOCKET
 257 cmsg_type = SCM_CREDS
 258 .Ed
 259 .It Dv LOCAL_CONNWAIT
 260 Used with
 261 .Dv SOCK_STREAM
 262 sockets, this option causes the
 263 .Xr connect 2
 264 function to block until
 265 .Xr accept 2
 266 has been called on the listening socket.
 267 .El
 268 .Sh SEE ALSO
 269 .Xr socket 2 ,
 270 .Xr intro 4
 271 .Rs
 272 .%T "An Introductory 4.3 BSD Interprocess Communication Tutorial"
 273 .%B PS1
 274 .%N 7
 275 .Re
 276 .Rs
 277 .%T "An Advanced 4.3 BSD Interprocess Communication Tutorial"
 278 .%B PS1
 279 .%N 8
 280 .Re