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

   1 .\"     $NetBSD: 2.1.t,v 1.2 1998/01/09 06:54:47 perry Exp $
   2 .\"
   3 .\" Copyright (c) 1983, 1993, 1994
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. Neither the name of the University nor the names of its contributors
  15 .\"    may be used to endorse or promote products derived from this software
  16 .\"    without specific prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .\"     @(#)2.1.t       8.4 (Berkeley) 5/26/94
  31 .\"
  32 .Sh 2 "Generic operations
  33 .PP
  34 Many system abstractions support the
  35 .Fn read ,
  36 .Fn write ,
  37 and
  38 .Fn ioctl
  39 operations.
  40 We describe the basics of these common primitives here.
  41 Similarly, the mechanisms whereby normally synchronous operations
  42 may occur in a non-blocking or asynchronous fashion are
  43 common to all system-defined abstractions and are described here.
  44 .Sh 3 "Read and write
  45 .PP
  46 The
  47 .Fn read
  48 and
  49 .Fn write
  50 system calls can be applied to communications channels,
  51 files, terminals and devices.
  52 They have the form:
  53 .DS
  54 .Fd read 3 "read input
  55 cc = read(fd, buf, nbytes);
  56 result ssize_t cc; int fd; result void *buf; size_t nbytes;
  57 .DE
  58 .DS
  59 .Fd write 3 "write output
  60 cc = write(fd, buf, nbytes);
  61 result ssize_t cc; int fd; void *buf; size_t nbytes;
  62 .DE
  63 The
  64 .Fn read
  65 call transfers as much data as possible from the
  66 object defined by \fIfd\fP to the buffer at address \fIbuf\fP of
  67 size \fInbytes\fP.  The number of bytes transferred is
  68 returned in \fIcc\fP, which is \-1 if a return occurred before
  69 any data was transferred because of an error or use of non-blocking
  70 operations.
  71 A return value of 0 is used to indicate an end-of-file condition.
  72 .PP
  73 The
  74 .Fn write
  75 call transfers data from the buffer to the
  76 object defined by \fIfd\fP.  Depending on the type of \fIfd\fP,
  77 it is possible that the
  78 .Fn write
  79 call will accept only a portion of the provided bytes;
  80 the user should resubmit the other bytes in a later request.
  81 Error returns because of interrupted or otherwise incomplete operations
  82 are possible, in which case no data will have been transferred.
  83 .PP
  84 Scattering of data on input, or gathering of data for output
  85 is also possible using an array of input/output vector descriptors.
  86 The type for the descriptors is defined in \fI<sys/uio.h>\fP as:
  87 .DS
  88 .TS
  89 l s s s
  90 l l l l.
  91 struct iovec {
  92         char    *iov_base;      /* base of a component */
  93         size_t  iov_len;        /* length of a component */
  94 };
  95 .TE
  96 .DE
  97 .LP
  98 The \fIiov_base\fP field should be treated as if its type were
  99 ``void *'' as POSIX and other versions of the structure may use
 100 that type.
 101 Thus, pointer arithmetic should not use this value without a cast.
 102 .LP
 103 The calls using an array of \fIiovec\fP structures are:
 104 .DS
 105 .Fd readv 3 "read gathered input
 106 cc = readv(fd, iov, iovlen);
 107 result ssize_t cc; int fd; struct iovec *iov; int iovlen;
 108 .DE
 109 .DS
 110 .Fd writev 3 "write scattered output
 111 cc = writev(fd, iov, iovlen);
 112 result ssize_t cc; int fd; struct iovec *iov; int iovlen;
 113 .DE
 114 Here \fIiovlen\fP is the count of elements in the \fIiov\fP array.
 115 .Sh 3 "Input/output control
 116 .LP
 117 Control operations on an object are performed by the
 118 .Fn ioctl
 119 operation:
 120 .DS
 121 .Fd ioctl 3 "control device
 122 ioctl(fd, request, buffer);
 123 int fd; u_long request; caddr_t buffer;
 124 .DE
 125 This operation causes the specified \fIrequest\fP to be performed
 126 on the object \fIfd\fP.  The \fIrequest\fP parameter specifies
 127 whether the argument buffer is to be read, written, read and written,
 128 or is not used, and also the size of the buffer, as well as the
 129 request.
 130 Different descriptor types and subtypes within descriptor types
 131 may use distinct
 132 .Fn ioctl
 133 requests. For example,
 134 operations on terminals control flushing of input and output
 135 queues and setting of terminal parameters; operations on
 136 disks cause formatting operations to occur; operations on tapes
 137 control tape positioning.
 138 The names for basic control operations are defined by \fI<sys/ioctl.h>\fP,
 139 or more specifically by files it includes.
 140 .Sh 3 "Non-blocking and asynchronous operations
 141 .PP
 142 A process that wishes to do non-blocking operations on one of
 143 its descriptors sets the descriptor in non-blocking mode as
 144 described in section
 145 .Xr 1.5.4 .
 146 Thereafter the
 147 .Fn read
 148 call will return a specific EWOULDBLOCK error indication
 149 if there is no data to be
 150 .Fn read .
 151 The process may
 152 .Fn select
 153 the associated descriptor to determine when a read is possible.
 154 .PP
 155 Output attempted when a descriptor can accept less than is requested
 156 will either accept some of the provided data, returning a shorter than normal
 157 length, or return an error indicating that the operation would block.
 158 More output can be performed as soon as a
 159 .Fn select
 160 call indicates
 161 the object is writable.
 162 .PP
 163 Operations other than data input or output
 164 may be performed on a descriptor in a non-blocking fashion.
 165 These operations will return with a characteristic error indicating
 166 that they are in progress
 167 if they cannot complete immediately.  The descriptor
 168 may then be
 169 .Fn select 'ed
 170 for
 171 .Fn write
 172 to find out when the operation has been completed.
 173 When
 174 .Fn select
 175 indicates the descriptor is writable, the operation has completed.
 176 Depending on the nature of the descriptor and the operation,
 177 additional activity may be started or the new state may be tested.