share/doc/psd/05.sysman/1.5.t

   1 .\" Copyright (c) 1983, 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 .\"     @(#)1.5.t       8.1 (Berkeley) 6/8/93
  33 .\"
  34 .sh Descriptors
  35 .PP
  36 .NH 3
  37 The reference table
  38 .PP
  39 Each process has access to resources through
  40 \fIdescriptors\fP.  Each descriptor is a handle allowing
  41 the process to reference objects such as files, devices
  42 and communications links.
  43 .PP
  44 Rather than allowing processes direct access to descriptors, the system
  45 introduces a level of indirection, so that descriptors may be shared
  46 between processes.  Each process has a \fIdescriptor reference table\fP,
  47 containing pointers to the actual descriptors.  The descriptors
  48 themselves thus have multiple references, and are reference counted by the
  49 system.
  50 .PP
  51 Each process has a fixed size descriptor reference table, where
  52 the size is returned by the \fIgetdtablesize\fP call:
  53 .DS
  54 nds = getdtablesize();
  55 result int nds;
  56 .DE
  57 and guaranteed to be at least 20.  The entries in the descriptor reference
  58 table are referred to by small integers; for example if there
  59 are 20 slots they are numbered 0 to 19.
  60 .NH 3
  61 Descriptor properties
  62 .PP
  63 Each descriptor has a logical set of properties maintained
  64 by the system and defined by its \fItype\fP.
  65 Each type supports a set of operations;
  66 some operations, such as reading and writing, are common to several
  67 abstractions, while others are unique.
  68 The generic operations applying to many of these types are described
  69 in section 2.1.  Naming contexts, files and directories are described in
  70 section 2.2.  Section 2.3 describes communications domains and sockets.
  71 Terminals and (structured and unstructured) devices are described
  72 in section 2.4.
  73 .NH 3
  74 Managing descriptor references
  75 .PP
  76 A duplicate of a descriptor reference may be made by doing
  77 .DS
  78 new = dup(old);
  79 result int new; int old;
  80 .DE
  81 returning a copy of descriptor reference \fIold\fP indistinguishable from
  82 the original.  The \fInew\fP chosen by the system will be the
  83 smallest unused descriptor reference slot.
  84 A copy of a descriptor reference may be made in a specific slot
  85 by doing
  86 .DS
  87 dup2(old, new);
  88 int old, new;
  89 .DE
  90 The \fIdup2\fP call causes the system to deallocate the descriptor reference
  91 current occupying slot \fInew\fP, if any, replacing it with a reference
  92 to the same descriptor as old.
  93 This deallocation is also performed by:
  94 .DS
  95 close(old);
  96 int old;
  97 .DE
  98 .NH 3
  99 Multiplexing requests
 100 .PP
 101 The system provides a
 102 standard way to do
 103 synchronous and asynchronous multiplexing of operations.
 104 .PP
 105 Synchronous multiplexing is performed by using the \fIselect\fP call
 106 to examine the state of multiple descriptors simultaneously,
 107 and to wait for state changes on those descriptors.
 108 Sets of descriptors of interest are specified as bit masks,
 109 as follows:
 110 .DS
 111 #include <sys/types.h>
 112
 113 nds = select(nd, in, out, except, tvp);
 114 result int nds; int nd; result fd_set *in, *out, *except;
 115 struct timeval *tvp;
 116
 117 FD_ZERO(&fdset);
 118 FD_SET(fd, &fdset);
 119 FD_CLR(fd, &fdset);
 120 FD_ISSET(fd, &fdset);
 121 int fs; fs_set fdset;
 122 .DE
 123 The \fIselect\fP call examines the descriptors
 124 specified by the
 125 sets \fIin\fP, \fIout\fP and \fIexcept\fP, replacing
 126 the specified bit masks by the subsets that select true for input,
 127 output, and exceptional conditions respectively (\fInd\fP
 128 indicates the number of file descriptors specified by the bit masks).
 129 If any descriptors meet the following criteria,
 130 then the number of such descriptors is returned in \fInds\fP and the
 131 bit masks are updated.
 132 .if n .ds bu *
 133 .if t .ds bu \(bu
 134 .IP \*(bu
 135 A descriptor selects for input if an input oriented operation
 136 such as \fIread\fP or \fIreceive\fP is possible, or if a
 137 connection request may be accepted (see section 2.3.1.4).
 138 .IP \*(bu
 139 A descriptor selects for output if an output oriented operation
 140 such as \fIwrite\fP or \fIsend\fP is possible, or if an operation
 141 that was ``in progress'', such as connection establishment,
 142 has completed (see section 2.1.3).
 143 .IP \*(bu
 144 A descriptor selects for an exceptional condition if a condition
 145 that would cause a SIGURG signal to be generated exists (see section 1.3.2),
 146 or other device-specific events have occurred.
 147 .LP
 148 If none of the specified conditions is true, the operation
 149 waits for one of the conditions to arise,
 150 blocking at most the amount of time specified by \fItvp\fP.
 151 If \fItvp\fP is given as 0, the \fIselect\fP waits indefinitely.
 152 .PP
 153 Options affecting I/O on a descriptor
 154 may be read and set by the call:
 155 .DS
 156 ._d
 157 dopt = fcntl(d, cmd, arg)
 158 result int dopt; int d, cmd, arg;
 159
 160 /* interesting values for cmd */
 161 #define F_SETFL 3       /* set descriptor options */
 162 #define F_GETFL 4       /* get descriptor options */
 163 #define F_SETOWN        5       /* set descriptor owner (pid/pgrp) */
 164 #define F_GETOWN        6       /* get descriptor owner (pid/pgrp) */
 165 .DE
 166 The F_SETFL \fIcmd\fP may be used to set a descriptor in
 167 non-blocking I/O mode and/or enable signaling when I/O is
 168 possible.  F_SETOWN may be used to specify a process or process
 169 group to be signaled when using the latter mode of operation
 170 or when urgent indications arise.
 171 .PP
 172 Operations on non-blocking descriptors will
 173 either complete immediately,
 174 note an error EWOULDBLOCK,
 175 partially complete an input or output operation returning a partial count,
 176 or return an error EINPROGRESS noting that the requested operation is
 177 in progress.
 178 A descriptor which has signalling enabled will cause the specified process
 179 and/or process group
 180 be signaled, with a SIGIO for input, output, or in-progress
 181 operation complete, or
 182 a SIGURG for exceptional conditions.
 183 .PP
 184 For example, when writing to a terminal
 185 using non-blocking output,
 186 the system will accept only as much data as there is buffer space for
 187 and return; when making a connection on a \fIsocket\fP, the operation may
 188 return indicating that the connection establishment is ``in progress''.
 189 The \fIselect\fP facility can be used to determine when further
 190 output is possible on the terminal, or when the connection establishment
 191 attempt is complete.
 192 .NH 3
 193 Descriptor wrapping.\(dg
 194 .PP
 195 .FS
 196 \(dg The facilities described in this section are not included
 197 in 4.3BSD.
 198 .FE
 199 A user process may build descriptors of a specified type by
 200 \fIwrapping\fP a communications channel with a system supplied protocol
 201 translator:
 202 .DS
 203 new = wrap(old, proto)
 204 result int new; int old; struct dprop *proto;
 205 .DE
 206 Operations on the descriptor \fIold\fP are then translated by the
 207 system provided protocol translator into requests on the underlying
 208 object \fIold\fP in a way defined by the protocol.
 209 The protocols supported by the kernel may vary from system to system
 210 and are described in the programmers manual.
 211 .PP
 212 Protocols may be based on communications multiplexing or a rights-passing
 213 style of handling multiple requests made on the same object.  For instance,
 214 a protocol for implementing a file abstraction may or may not include
 215 locally generated ``read-ahead'' requests.  A protocol that provides for
 216 read-ahead may provide higher performance but have a more difficult
 217 implementation.
 218 .PP
 219 Another example is the terminal driving facilities.  Normally a terminal
 220 is associated with a communications line, and the terminal type
 221 and standard terminal access protocol are wrapped around a synchronous
 222 communications line and given to the user.  If a virtual terminal
 223 is required, the terminal driver can be wrapped around a communications
 224 link, the other end of which is held by a virtual terminal protocol
 225 interpreter.