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 .\"
  34 .Dd June 9, 1993
  35 .Dt UNIX 4
  36 .Os
  37 .Sh NAME
  38 .Nm unix
  39 .Nd UNIX-domain protocol family
  40 .Sh SYNOPSIS
  41 .Fd #include <sys/types.h>
  42 .Fd #include <sys/un.h>
  43 .Sh DESCRIPTION
  44 The
  45 .Tn UNIX Ns -domain
  46 protocol family is a collection of protocols
  47 that provides local (on-machine) interprocess
  48 communication through the normal
  49 .Xr socket 2
  50 mechanisms.
  51 The
  52 .Tn UNIX Ns -domain
  53 family supports the
  54 .Dv SOCK_STREAM
  55 and
  56 .Dv SOCK_DGRAM
  57 socket types and uses
  58 filesystem pathnames for addressing.
  59 .Sh ADDRESSING
  60 .Tn UNIX Ns -domain
  61 addresses are variable-length filesystem pathnames of
  62 at most 104 characters.
  63 The include file
  64 .Aq Pa sys/un.h
  65 defines this address:
  66 .Bd -literal -offset indent
  67 struct sockaddr_un {
  68 u_char  sun_len;
  69 u_char  sun_family;
  70 char    sun_path[104];
  71 };
  72 .Ed
  73 .Pp
  74 Binding a name to a
  75 .Tn UNIX Ns -domain
  76 socket with
  77 .Xr bind 2
  78 causes a socket file to be created in the filesystem.
  79 This file is
  80 .Em not
  81 removed when the socket is closed\(em\c
  82 .Xr unlink 2
  83 must be used to remove the file.
  84 .Pp
  85 The
  86 .Tn UNIX Ns -domain
  87 protocol family does not support broadcast addressing or any form
  88 of
  89 .Dq wildcard
  90 matching on incoming messages.
  91 All addresses are absolute- or relative-pathnames
  92 of other
  93 .Tn UNIX Ns -domain
  94 sockets.
  95 Normal filesystem access-control mechanisms are also
  96 applied when referencing pathnames; e.g., the destination
  97 of a
  98 .Xr connect 2
  99 or
 100 .Xr sendto 2
 101 must be writable.
 102 .Sh PROTOCOLS
 103 The
 104 .Tn UNIX Ns -domain
 105 protocol family is comprised of simple
 106 transport protocols that support the
 107 .Dv SOCK_STREAM
 108 and
 109 .Dv SOCK_DGRAM
 110 abstractions.
 111 .Dv SOCK_STREAM
 112 sockets also support the communication of
 113 .Ux
 114 file descriptors through the use of the
 115 .Ar msg_control
 116 field in the
 117 .Ar msg
 118 argument to
 119 .Xr sendmsg 2
 120 and
 121 .Xr recvmsg 2 .
 122 .Pp
 123 Any valid descriptor may be sent in a message.
 124 The file descriptor(s) to be passed are described using a
 125 .Ar struct cmsghdr
 126 that is defined in the include file
 127 .Aq Pa sys/socket.h .
 128 The type of the message is
 129 .Dv SCM_RIGHTS ,
 130 and the data portion of the messages is an array of integers
 131 representing the file descriptors to be passed.
 132 The number of descriptors being passed is defined
 133 by the length field of the message;
 134 the length field is the sum of the size of the header
 135 plus the size of the array of file descriptors.
 136 .Pp
 137 The received descriptor is a
 138 .Em duplicate
 139 of the sender's descriptor, as if it were created with a call to
 140 .Xr dup 2 .
 141 Per-process descriptor flags, set with
 142 .Xr fcntl 2 ,
 143 are
 144 .Em not
 145 passed to a receiver.
 146 Descriptors that are awaiting delivery, or that are
 147 purposely not received, are automatically closed by the system
 148 when the destination socket is closed.
 149 .Sh SEE ALSO
 150 .Xr socket 2 ,
 151 .Xr intro 4
 152 .Rs
 153 .%T "An Introductory 4.3 BSD Interprocess Communication Tutorial"
 154 .%B PS1
 155 .%N 7
 156 .Re
 157 .Rs
 158 .%T "An Advanced 4.3 BSD Interprocess Communication Tutorial"
 159 .%B PS1
 160 .%N 8
 161 .Re