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 .\"
  31 .Dd November 1, 2015
  32 .Dt UNIX 4
  33 .Os
  34 .Sh NAME
  35 .Nm unix
  36 .Nd UNIX-domain protocol family
  37 .Sh SYNOPSIS
  38 .In sys/types.h
  39 .In sys/un.h
  40 .Sh DESCRIPTION
  41 The
  42 .Ux Ns -domain
  43 protocol family is a collection of protocols
  44 that provides local (on-machine) interprocess
  45 communication through the normal
  46 .Xr socket 2
  47 mechanisms.
  48 The
  49 .Ux Ns -domain
  50 family supports the
  51 .Dv SOCK_STREAM ,
  52 .Dv SOCK_DGRAM
  53 and
  54 .Dv SOCK_SEQPACKET
  55 socket types and uses
  56 filesystem pathnames for addressing.
  57 .Sh ADDRESSING
  58 .Ux Ns -domain
  59 addresses are variable-length filesystem pathnames of
  60 at most 104 characters.
  61 The include file
  62 .In sys/un.h
  63 defines this address:
  64 .Bd -literal -offset indent
  65 struct sockaddr_un {
  66 u_char          sun_len;
  67 sa_family_t     sun_family;
  68 char            sun_path[104];
  69 };
  70 .Ed
  71 .Pp
  72 Binding a name to a
  73 .Ux 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
  80 .Xr unlink 2
  81 must be used to remove the file.
  82 .Pp
  83 The
  84 .Ux Ns -domain
  85 protocol family does not support broadcast addressing or any form
  86 of
  87 .Dq wildcard
  88 matching on incoming messages.
  89 All addresses are absolute- or relative-pathnames
  90 of other
  91 .Ux Ns -domain
  92 sockets.
  93 Normal filesystem access-control mechanisms are also
  94 applied when referencing pathnames; e.g., the destination
  95 of a
  96 .Xr connect 2
  97 or
  98 .Xr sendto 2
  99 must be writable.
 100 .Sh PROTOCOLS
 101 The
 102 .Ux Ns -domain
 103 protocol family is comprised of simple
 104 transport protocols that support the
 105 .Dv SOCK_STREAM ,
 106 .Dv SOCK_DGRAM
 107 and
 108 .Dv SOCK_SEQPACKET
 109 abstractions.
 110 .Dv SOCK_STREAM ,
 111 .Dv SOCK_DGRAM
 112 and
 113 .Dv SOCK_SEQPACKET
 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 via
 142 .Li dup(fd)
 143 or
 144 .Li fcntl(fd, F_DUPFD_CLOEXEC, 0)
 145 depending on whether
 146 .Dv MSG_CMSG_CLOEXEC
 147 is passed in the
 148 .Xr recvmsg 2
 149 call.
 150 Descriptors that are awaiting delivery, or that are
 151 purposely not received, are automatically closed by the system
 152 when the destination socket is closed.
 153 .Pp
 154 The effective credentials (i.e., the user ID and group list) of a
 155 peer on a
 156 .Dv SOCK_STREAM
 157 socket may be obtained using the
 158 .Dv LOCAL_PEERCRED
 159 socket option.
 160 This may be used by a server to obtain and verify the credentials of
 161 its client, and vice versa by the client to verify the credentials
 162 of the server.
 163 These will arrive in the form of a filled in
 164 .Vt "struct xucred"
 165 (defined in
 166 .In sys/ucred.h ) .
 167 The credentials presented to the server (the
 168 .Xr listen 2
 169 caller) are those of the client when it called
 170 .Xr connect 2 ;
 171 the credentials presented to the client (the
 172 .Xr connect 2
 173 caller) are those of the server when it called
 174 .Xr listen 2 .
 175 This mechanism is reliable; there is no way for either party to influence
 176 the credentials presented to its peer except by calling the appropriate
 177 system call (e.g.,
 178 .Xr connect 2
 179 or
 180 .Xr listen 2 )
 181 under different effective credentials.
 182 .Sh SEE ALSO
 183 .Xr socket 2 ,
 184 .Xr intro 4
 185 .Rs
 186 .%T "An Introductory 4.3 BSD Interprocess Communication Tutorial"
 187 .%B PS1
 188 .%N 7
 189 .Re
 190 .Rs
 191 .%T "An Advanced 4.3 BSD Interprocess Communication Tutorial"
 192 .%B PS1
 193 .%N 8
 194 .Re