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. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)unix.4      8.1 (Berkeley) 6/9/93
  29 .\" $FreeBSD: src/share/man/man4/unix.4,v 1.3.2.4 2002/04/22 08:59:53 dd Exp $
  30 .\" $DragonFly: src/share/man/man4/unix.4,v 1.3 2006/05/26 19:39:39 swildner Exp $
  31 .\"
  32 .Dd July 15, 2001
  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 .Ux 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 .Ux Ns -domain
  51 family supports the
  52 .Dv SOCK_STREAM ,
  53 .Dv SOCK_DGRAM
  54 and
  55 .Dv SOCK_SEQPACKET
  56 socket types and uses
  57 filesystem pathnames for addressing.
  58 .Sh ADDRESSING
  59 .Ux Ns -domain
  60 addresses are variable-length filesystem pathnames of
  61 at most 104 characters.
  62 The include file
  63 .In sys/un.h
  64 defines this address:
  65 .Bd -literal -offset indent
  66 struct sockaddr_un {
  67 u_char  sun_len;
  68 u_char  sun_family;
  69 char    sun_path[104];
  70 };
  71 .Ed
  72 .Pp
  73 Binding a name to a
  74 .Ux Ns -domain
  75 socket with
  76 .Xr bind 2
  77 causes a socket file to be created in the filesystem.
  78 This file is
  79 .Em not
  80 removed when the socket is closed \(em
  81 .Xr unlink 2
  82 must be used to remove the file.
  83 .Pp
  84 The
  85 .Ux Ns -domain
  86 protocol family does not support broadcast addressing or any form
  87 of
  88 .Dq wildcard
  89 matching on incoming messages.
  90 All addresses are absolute- or relative-pathnames
  91 of other
  92 .Ux Ns -domain
  93 sockets.
  94 Normal filesystem access-control mechanisms are also
  95 applied when referencing pathnames; e.g., the destination
  96 of a
  97 .Xr connect 2
  98 or
  99 .Xr sendto 2
 100 must be writable.
 101 .Sh PROTOCOLS
 102 The
 103 .Ux Ns -domain
 104 protocol family is comprised of simple
 105 transport protocols that support the
 106 .Dv SOCK_STREAM ,
 107 .Dv SOCK_DGRAM
 108 and
 109 .Dv SOCK_SEQPACKET
 110 abstractions.
 111 .Dv SOCK_STREAM ,
 112 .Dv SOCK_DGRAM
 113 and
 114 .Dv SOCK_SEQPACKET
 115 sockets also support the communication of
 116 .Ux
 117 file descriptors through the use of the
 118 .Va msg_control
 119 field in the
 120 .Fa msg
 121 argument to
 122 .Xr sendmsg 2
 123 and
 124 .Xr recvmsg 2 .
 125 .Pp
 126 Any valid descriptor may be sent in a message.
 127 The file descriptor(s) to be passed are described using a
 128 .Vt "struct cmsghdr"
 129 that is defined in the include file
 130 .In sys/socket.h .
 131 The type of the message is
 132 .Dv SCM_RIGHTS ,
 133 and the data portion of the messages is an array of integers
 134 representing the file descriptors to be passed.
 135 The number of descriptors being passed is defined
 136 by the length field of the message;
 137 the length field is the sum of the size of the header
 138 plus the size of the array of file descriptors.
 139 .Pp
 140 The received descriptor is a
 141 .Em duplicate
 142 of the sender's descriptor, as if it were created with a call to
 143 .Xr dup 2 .
 144 Per-process descriptor flags, set with
 145 .Xr fcntl 2 ,
 146 are
 147 .Em not
 148 passed to a receiver.
 149 Descriptors that are awaiting delivery, or that are
 150 purposely not received, are automatically closed by the system
 151 when the destination socket is closed.
 152 .Pp
 153 The effective credentials (i.e., the user ID and group list) of a
 154 peer on a
 155 .Dv SOCK_STREAM
 156 socket may be obtained using the
 157 .Dv LOCAL_PEERCRED
 158 socket option.
 159 This may be used by a server to obtain and verify the credentials of
 160 its client, and vice versa by the client to verify the credentials
 161 of the server.
 162 These will arrive in the form of a filled in
 163 .Vt "struct xucred"
 164 (defined in
 165 .In sys/ucred.h ) .
 166 The credentials presented to the server (the
 167 .Xr listen 2
 168 caller) are those of the client when it called
 169 .Xr connect 2 ;
 170 the credentials presented to the client (the
 171 .Xr connect 2
 172 caller) are those of the server when it called
 173 .Xr listen 2 .
 174 This mechanism is reliable; there is no way for either party to influence
 175 the credentials presented to its peer except by calling the appropriate
 176 system call (e.g.,
 177 .Xr connect 2
 178 or
 179 .Xr listen 2 )
 180 under different effective credentials.
 181 .Sh SEE ALSO
 182 .Xr socket 2 ,
 183 .Xr intro 4
 184 .Rs
 185 .%T "An Introductory 4.3 BSD Interprocess Communication Tutorial"
 186 .%B PS1
 187 .%N 7
 188 .Re
 189 .Rs
 190 .%T "An Advanced 4.3 BSD Interprocess Communication Tutorial"
 191 .%B PS1
 192 .%N 8
 193 .Re