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