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 .\" $DragonFly: src/share/man/man4/unix.4,v 1.3 2006/05/26 19:39:39 swildner Exp $
  35 .\"
  36 .Dd July 15, 2001
  37 .Dt UNIX 4
  38 .Os
  39 .Sh NAME
  40 .Nm unix
  41 .Nd UNIX-domain protocol family
  42 .Sh SYNOPSIS
  43 .In sys/types.h
  44 .In sys/un.h
  45 .Sh DESCRIPTION
  46 The
  47 .Ux Ns -domain
  48 protocol family is a collection of protocols
  49 that provides local (on-machine) interprocess
  50 communication through the normal
  51 .Xr socket 2
  52 mechanisms.
  53 The
  54 .Ux Ns -domain
  55 family supports the
  56 .Dv SOCK_STREAM
  57 and
  58 .Dv SOCK_DGRAM
  59 socket types and uses
  60 filesystem pathnames for addressing.
  61 .Sh ADDRESSING
  62 .Ux Ns -domain
  63 addresses are variable-length filesystem 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 filesystem.
  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
  88 .Ux Ns -domain
  89 protocol family does not support broadcast addressing or any form
  90 of
  91 .Dq wildcard
  92 matching on incoming messages.
  93 All addresses are absolute- or relative-pathnames
  94 of other
  95 .Ux Ns -domain
  96 sockets.
  97 Normal filesystem access-control mechanisms are also
  98 applied when referencing pathnames; e.g., the destination
  99 of a
 100 .Xr connect 2
 101 or
 102 .Xr sendto 2
 103 must be writable.
 104 .Sh PROTOCOLS
 105 The
 106 .Ux Ns -domain
 107 protocol family is comprised of simple
 108 transport protocols that support the
 109 .Dv SOCK_STREAM
 110 and
 111 .Dv SOCK_DGRAM
 112 abstractions.
 113 .Dv SOCK_STREAM
 114 sockets also support the communication of
 115 .Ux
 116 file descriptors through the use of the
 117 .Va msg_control
 118 field in the
 119 .Fa msg
 120 argument to
 121 .Xr sendmsg 2
 122 and
 123 .Xr recvmsg 2 .
 124 .Pp
 125 Any valid descriptor may be sent in a message.
 126 The file descriptor(s) to be passed are described using a
 127 .Vt "struct cmsghdr"
 128 that is defined in the include file
 129 .In sys/socket.h .
 130 The type of the message is
 131 .Dv SCM_RIGHTS ,
 132 and the data portion of the messages is an array of integers
 133 representing the file descriptors to be passed.
 134 The number of descriptors being passed is defined
 135 by the length field of the message;
 136 the length field is the sum of the size of the header
 137 plus the size of the array of file descriptors.
 138 .Pp
 139 The received descriptor is a
 140 .Em duplicate
 141 of the sender's descriptor, as if it were created with a call to
 142 .Xr dup 2 .
 143 Per-process descriptor flags, set with
 144 .Xr fcntl 2 ,
 145 are
 146 .Em not
 147 passed to a receiver.
 148 Descriptors that are awaiting delivery, or that are
 149 purposely not received, are automatically closed by the system
 150 when the destination socket is closed.
 151 .Pp
 152 The effective credentials (i.e., the user ID and group list) of a
 153 peer on a
 154 .Dv SOCK_STREAM
 155 socket may be obtained using the
 156 .Dv LOCAL_PEERCRED
 157 socket option.
 158 This may be used by a server to obtain and verify the credentials of
 159 its client, and vice versa by the client to verify the credentials
 160 of the server.
 161 These will arrive in the form of a filled in
 162 .Vt "struct xucred"
 163 (defined in
 164 .In sys/ucred.h ) .
 165 The credentials presented to the server (the
 166 .Xr listen 2
 167 caller) are those of the client when it called
 168 .Xr connect 2 ;
 169 the credentials presented to the client (the
 170 .Xr connect 2
 171 caller) are those of the server when it called
 172 .Xr listen 2 .
 173 This mechanism is reliable; there is no way for either party to influence
 174 the credentials presented to its peer except by calling the appropriate
 175 system call (e.g.,
 176 .Xr connect 2
 177 or
 178 .Xr listen 2 )
 179 under different effective credentials.
 180 .Sh SEE ALSO
 181 .Xr socket 2 ,
 182 .Xr intro 4
 183 .Rs
 184 .%T "An Introductory 4.3 BSD Interprocess Communication Tutorial"
 185 .%B PS1
 186 .%N 7
 187 .Re
 188 .Rs
 189 .%T "An Advanced 4.3 BSD Interprocess Communication Tutorial"
 190 .%B PS1
 191 .%N 8
 192 .Re