share/man/man4/unix.4

   1 .\"     $NetBSD: unix.4,v 1.19 2007/08/09 15:23:03 he Exp $
   2 .\"
   3 .\" Copyright (c) 1991, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. Neither the name of the University nor the names of its contributors
  15 .\"    may be used to endorse or promote products derived from this software
  16 .\"    without specific prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .\"     @(#)unix.4      8.1 (Berkeley) 6/9/93
  31 .\"
  32 .Dd October 30, 2006
  33 .Dt UNIX 4
  34 .Os
  35 .Sh NAME
  36 .Nm unix
  37 .Nd UNIX-domain protocol family
  38 .Sh SYNOPSIS
  39 .In sys/types.h
  40 .In sys/un.h
  41 .Sh DESCRIPTION
  42 The
  43 .Tn UNIX Ns -domain
  44 protocol family is a collection of protocols
  45 that provides local (on-machine) interprocess
  46 communication through the normal
  47 .Xr socket 2
  48 mechanisms.
  49 The
  50 .Tn UNIX Ns -domain
  51 family supports the
  52 .Dv SOCK_STREAM
  53 and
  54 .Dv SOCK_DGRAM
  55 socket types and uses
  56 filesystem pathnames for addressing.
  57 .Sh ADDRESSING
  58 .Tn UNIX Ns -domain
  59 addresses are variable-length filesystem pathnames of
  60 at most 104 characters.
  61 The include file
  62 .Aq Pa 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 .Tn UNIX Ns -domain
  74 socket with
  75 .Xr bind 2
  76 causes a socket file to be created in the filesystem.
  77 This file is
  78 .Em not
  79 removed when the socket is closed\(em\c
  80 .Xr unlink 2
  81 must be used to remove the file.
  82 .Pp
  83 The length of
  84 .Tn UNIX 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 .Aq Pa sys/un.h .
  93 The
  94 .Ar sun_path
  95 field must be terminated by a NUL character to be used with
  96 .Fn SUN_LEN ,
  97 but the terminating NUL is
  98 .Em not
  99 part of the address.
 100 The
 101 .Nx
 102 kernel ignores any user-set value in the
 103 .Va sun_len
 104 member of the structure.
 105 .Pp
 106 The
 107 .Tn UNIX Ns -domain
 108 protocol family does not support broadcast addressing or any form
 109 of
 110 .Dq wildcard
 111 matching on incoming messages.
 112 All addresses are absolute- or relative-pathnames
 113 of other
 114 .Tn UNIX Ns -domain
 115 sockets.
 116 Normal filesystem access-control mechanisms are also
 117 applied when referencing pathnames; e.g., the destination
 118 of a
 119 .Xr connect 2
 120 or
 121 .Xr sendto 2
 122 must be writable.
 123 .Sh PROTOCOLS
 124 The
 125 .Tn UNIX Ns -domain
 126 protocol family comprises simple
 127 transport protocols that support the
 128 .Dv SOCK_STREAM
 129 and
 130 .Dv SOCK_DGRAM
 131 abstractions.
 132 .Dv SOCK_STREAM
 133 sockets also support the communication of
 134 .Ux
 135 file descriptors through the use of the
 136 .Ar msg_control
 137 field in the
 138 .Ar msg
 139 argument to
 140 .Xr sendmsg 2
 141 and
 142 .Xr recvmsg 2 .
 143 .Pp
 144 Any valid descriptor may be sent in a message.
 145 The file descriptor(s) to be passed are described using a
 146 .Ar struct cmsghdr
 147 that is defined in the include file
 148 .Aq Pa sys/socket.h .
 149 The type of the message is
 150 .Dv SCM_RIGHTS ,
 151 and the data portion of the messages is an array of integers
 152 representing the file descriptors to be passed.
 153 The number of descriptors being passed is defined
 154 by the length field of the message;
 155 the length field is the sum of the size of the header
 156 plus the size of the array of file descriptors.
 157 .Pp
 158 The received descriptor is a
 159 .Em duplicate
 160 of the sender's descriptor, as if it were created with a call to
 161 .Xr dup 2 .
 162 Per-process descriptor flags, set with
 163 .Xr fcntl 2 ,
 164 are
 165 .Em not
 166 passed to a receiver.
 167 Descriptors that are awaiting delivery, or that are
 168 purposely not received, are automatically closed by the system
 169 when the destination socket is closed.
 170 .Pp
 171 A UNIX-domain socket supports two
 172 .Tn socket-level
 173 options for use with
 174 .Xr setsockopt 2
 175 and
 176 .Xr getsockopt 2 :
 177 .Pp
 178 The
 179 .Dv LOCAL_CREDS
 180 option may be enabled on a
 181 .Dv SOCK_DGRAM
 182 or a
 183 .Dv SOCK_STREAM
 184 socket.
 185 This option provides a mechanism for the receiver to
 186 receive the credentials of the process as a
 187 .Xr recvmsg 2
 188 control message.
 189 The msg_control field in the msghdr structure points
 190 to a buffer that contains a cmsghdr structure followed by a variable
 191 length sockcred structure, defined in
 192 .Aq Pa sys/socket.h
 193 as follows:
 194 .Bd -literal
 195 struct sockcred {
 196         uid_t   sc_uid;                 /* real user id */
 197         uid_t   sc_euid;                /* effective user id */
 198         gid_t   sc_gid;                 /* real group id */
 199         gid_t   sc_egid;                /* effective group id */
 200         int     sc_ngroups;             /* number of supplemental groups */
 201         gid_t   sc_groups[1];           /* variable length */
 202 };
 203 .Ed
 204 .Pp
 205 The
 206 .Dv LOCAL_PEEREID
 207 option may be used with
 208 .Xr getsockopt 2
 209 to get the PID and effective user and group IDs of a
 210 .Dv SOCK_STREAM
 211 peer when it did
 212 .Xr connect 2
 213 or
 214 .Xr bind 2 .
 215 The returned structure is
 216 .Bd -literal
 217 struct unpcbid {
 218         pid_t unp_pid;                  /* process id */
 219         uid_t unp_euid;                 /* effective user id */
 220         gid_t unp_egid;                 /* effective group id */
 221 };
 222 .Ed
 223 as defined in
 224 .Aq Pa sys/un.h .
 225 .Pp
 226 The
 227 .Fn SOCKCREDSIZE
 228 macro computes the size of the sockcred structure for a specified number
 229 of groups.
 230 The cmsghdr fields have the following values:
 231 .Bd -literal
 232 cmsg_len = sizeof(struct cmsghdr) + SOCKCREDSIZE(ngroups)
 233 cmsg_level = SOL_SOCKET
 234 cmsg_type = SCM_CREDS
 235 .Ed
 236 .Sh EXAMPLES
 237 The following code fragment shows how to bind a socket to pathname:
 238 .Bd -literal -offset indent
 239 const char *pathname = "/path/to/socket";
 240 struct sockaddr_un addr;
 241 int ret;
 242
 243 memset(\*[Am]addr, 0, sizeof(addr));
 244 addr.sun_family = AF_LOCAL;
 245 if (strlen(pathname) \*[Ge] sizeof(addr.sun_path))
 246         goto too_long;
 247 strncpy(addr.sun_path, pathname, sizeof(addr.sun_path));
 248 ret = bind(s, (const struct sockaddr *)\*[Am]addr, SUN_LEN(\*[Am]addr));
 249 if (ret != 0)
 250         goto bind_failed;
 251 \&...
 252
 253 .Ed
 254 .Sh COMPATIBILITY
 255 The
 256 .Ar sun_len
 257 field exists only in system derived from 4.4BSD.
 258 On systems which don't have the
 259 .Fn SUN_LEN
 260 macro, the following definition is recommended:
 261 .Bd -literal -offset indent
 262 #ifndef SUN_LEN
 263 #define SUN_LEN(su)     sizeof(struct(sockaddr_un))
 264 #endif
 265 .Ed
 266 .Sh SEE ALSO
 267 .Xr socket 2 ,
 268 .Xr intro 4
 269 .Rs
 270 .%T "An Introductory 4.4BSD Interprocess Communication Tutorial"
 271 .%A Stuart Sechrest
 272 .Re
 273 .Pq see Pa /usr/share/doc/psd/20.ipctut
 274 .Rs
 275 .%T "Advanced 4.4BSD IPC Tutorial"
 276 .%A Samuel J. Leffler
 277 .%A Robert S. Fabry
 278 .%A William N. Joy
 279 .%A Phil Lapsley
 280 .%A Steve Miller
 281 .%A Chris Torek
 282 .Re
 283 .Pq see Pa /usr/share/doc/psd/21.ipc