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: src/share/man/man4/unix.4,v 1.3.2.4 2002/04/22 08:59:53 dd Exp $
  34 .\"
  35 .Dd July 15, 2001
  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 and
  57 .Dv SOCK_DGRAM
  58 socket types and uses
  59 filesystem pathnames for addressing.
  60 .Sh ADDRESSING
  61 .Ux Ns -domain
  62 addresses are variable-length filesystem pathnames of
  63 at most 104 characters.
  64 The include file
  65 .Aq Pa sys/un.h
  66 defines this address:
  67 .Bd -literal -offset indent
  68 struct sockaddr_un {
  69 u_char  sun_len;
  70 u_char  sun_family;
  71 char    sun_path[104];
  72 };
  73 .Ed
  74 .Pp
  75 Binding a name to a
  76 .Ux Ns -domain
  77 socket with
  78 .Xr bind 2
  79 causes a socket file to be created in the filesystem.
  80 This file is
  81 .Em not
  82 removed when the socket is closed \(em
  83 .Xr unlink 2
  84 must be used to remove the file.
  85 .Pp
  86 The
  87 .Ux Ns -domain
  88 protocol family does not support broadcast addressing or any form
  89 of
  90 .Dq wildcard
  91 matching on incoming messages.
  92 All addresses are absolute- or relative-pathnames
  93 of other
  94 .Ux Ns -domain
  95 sockets.
  96 Normal filesystem access-control mechanisms are also
  97 applied when referencing pathnames; e.g., the destination
  98 of a
  99 .Xr connect 2
 100 or
 101 .Xr sendto 2
 102 must be writable.
 103 .Sh PROTOCOLS
 104 The
 105 .Ux Ns -domain
 106 protocol family is comprised of simple
 107 transport protocols that support the
 108 .Dv SOCK_STREAM
 109 and
 110 .Dv SOCK_DGRAM
 111 abstractions.
 112 .Dv SOCK_STREAM
 113 sockets also support the communication of
 114 .Ux
 115 file descriptors through the use of the
 116 .Va msg_control
 117 field in the
 118 .Fa msg
 119 argument to
 120 .Xr sendmsg 2
 121 and
 122 .Xr recvmsg 2 .
 123 .Pp
 124 Any valid descriptor may be sent in a message.
 125 The file descriptor(s) to be passed are described using a
 126 .Vt "struct cmsghdr"
 127 that is defined in the include file
 128 .Aq Pa sys/socket.h .
 129 The type of the message is
 130 .Dv SCM_RIGHTS ,
 131 and the data portion of the messages is an array of integers
 132 representing the file descriptors to be passed.
 133 The number of descriptors being passed is defined
 134 by the length field of the message;
 135 the length field is the sum of the size of the header
 136 plus the size of the array of file descriptors.
 137 .Pp
 138 The received descriptor is a
 139 .Em duplicate
 140 of the sender's descriptor, as if it were created with a call to
 141 .Xr dup 2 .
 142 Per-process descriptor flags, set with
 143 .Xr fcntl 2 ,
 144 are
 145 .Em not
 146 passed to a receiver.
 147 Descriptors that are awaiting delivery, or that are
 148 purposely not received, are automatically closed by the system
 149 when the destination socket is closed.
 150 .Pp
 151 The effective credentials (i.e., the user ID and group list) of a
 152 peer on a
 153 .Dv SOCK_STREAM
 154 socket may be obtained using the
 155 .Dv LOCAL_PEERCRED
 156 socket option.
 157 This may be used by a server to obtain and verify the credentials of
 158 its client, and vice versa by the client to verify the credentials
 159 of the server.
 160 These will arrive in the form of a filled in
 161 .Vt "struct xucred"
 162 (defined in
 163 .Aq Pa sys/ucred.h ) .
 164 The credentials presented to the server (the
 165 .Xr listen 2
 166 caller) are those of the client when it called
 167 .Xr connect 2 ;
 168 the credentials presented to the client (the
 169 .Xr connect 2
 170 caller) are those of the server when it called
 171 .Xr listen 2 .
 172 This mechanism is reliable; there is no way for either party to influence
 173 the credentials presented to its peer except by calling the appropriate
 174 system call (e.g.,
 175 .Xr connect 2
 176 or
 177 .Xr listen 2 )
 178 under different effective credentials.
 179 .Sh SEE ALSO
 180 .Xr socket 2 ,
 181 .Xr intro 4
 182 .Rs
 183 .%T "An Introductory 4.3 BSD Interprocess Communication Tutorial"
 184 .%B PS1
 185 .%N 7
 186 .Re
 187 .Rs
 188 .%T "An Advanced 4.3 BSD Interprocess Communication Tutorial"
 189 .%B PS1
 190 .%N 8
 191 .Re