lib/libc/sys/read.2

   1 .\"     $NetBSD: read.2,v 1.30 2006/10/13 20:58:50 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 1980, 1991, 1993
   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 .\"     @(#)read.2      8.4 (Berkeley) 2/26/94
  31 .\"
  32 .Dd August 2, 2007
  33 .Dt READ 2
  34 .Os
  35 .Sh NAME
  36 .Nm read ,
  37 .Nm readv ,
  38 .Nm pread ,
  39 .Nm preadv
  40 .Nd read input
  41 .Sh LIBRARY
  42 .Lb libc
  43 .Sh SYNOPSIS
  44 .In unistd.h
  45 .Ft ssize_t
  46 .Fn read "int d" "void *buf" "size_t nbytes"
  47 .Ft ssize_t
  48 .Fn pread "int d" "void *buf" "size_t nbytes" "off_t offset"
  49 .In sys/uio.h
  50 .Ft ssize_t
  51 .Fn readv "int d" "const struct iovec *iov" "int iovcnt"
  52 .Ft ssize_t
  53 .Fn preadv "int d" "const struct iovec *iov" "int iovcnt" "off_t offset"
  54 .Sh DESCRIPTION
  55 .Fn read
  56 attempts to read
  57 .Fa nbytes
  58 of data from the object referenced by the descriptor
  59 .Fa d
  60 into the buffer pointed to by
  61 .Fa buf .
  62 .Fn readv
  63 performs the same action, but scatters the input data
  64 into the
  65 .Fa iovcnt
  66 buffers specified by the members of the
  67 .Fa iov
  68 array: iov[0], iov[1], ..., iov[iovcnt\|\-\|1].
  69 .Fn pread
  70 and
  71 .Fn preadv
  72 perform the same functions, but read from the specified position in
  73 the file without modifying the file pointer.
  74 .Pp
  75 For
  76 .Fn readv
  77 and
  78 .Fn preadv ,
  79 the
  80 .Fa iovec
  81 structure is defined as:
  82 .Pp
  83 .Bd -literal -offset indent -compact
  84 struct iovec {
  85         void *iov_base;
  86         size_t iov_len;
  87 };
  88 .Ed
  89 .Pp
  90 Each
  91 .Fa iovec
  92 entry specifies the base address and length of an area
  93 in memory where data should be placed.
  94 .Fn readv
  95 will always fill an area completely before proceeding
  96 to the next.
  97 .Pp
  98 On objects capable of seeking, the
  99 .Fn read
 100 starts at a position
 101 given by the file pointer associated with
 102 .Fa d
 103 (see
 104 .Xr lseek 2 ) .
 105 Upon return from
 106 .Fn read ,
 107 the file pointer is incremented by the number of bytes actually read.
 108 .Pp
 109 Objects that are not capable of seeking always read from the current
 110 position.
 111 The value of the file pointer associated with such an object is undefined.
 112 .Pp
 113 Upon successful completion,
 114 .Fn read ,
 115 .Fn readv ,
 116 .Fn pread ,
 117 and
 118 .Fn preadv
 119 return the number of bytes actually read and placed in the buffer.
 120 The system guarantees to read the number of bytes requested if
 121 the descriptor references a normal file that has that many bytes left
 122 before the end-of-file, but in no other case.
 123 .Sh RETURN VALUES
 124 If successful, the
 125 number of bytes actually read is returned.
 126 Upon reading end-of-file, zero is returned.
 127 Otherwise, a \-1 is returned and the global variable
 128 .Va errno
 129 is set to indicate the error.
 130 .Sh ERRORS
 131 .Fn read ,
 132 .Fn readv ,
 133 .Fn pread ,
 134 and
 135 .Fn preadv
 136 will succeed unless:
 137 .Bl -tag -width Er
 138 .It Bq Er EBADF
 139 .Fa d
 140 is not a valid file or socket descriptor open for reading.
 141 .It Bq Er EFAULT
 142 .Fa buf
 143 points outside the allocated address space.
 144 .It Bq Er EIO
 145 An I/O error occurred while reading from the file system.
 146 .It Bq Er EINTR
 147 A read from a slow device
 148 (i.e. one that might block for an arbitrary amount of time)
 149 was interrupted by the delivery of a signal
 150 before any data arrived.
 151 See
 152 .Xr sigaction 2
 153 for more information on the interaction between signals and system
 154 calls.
 155 .It Bq Er EINVAL
 156 The file pointer associated with
 157 .Fa d
 158 was negative.
 159 .It Bq Er EINVAL
 160 The total length of the I/O is more than can be expressed by the ssize_t
 161 return value.
 162 .It Bq Er EAGAIN
 163 The file was marked for non-blocking I/O,
 164 and no data were ready to be read.
 165 .El
 166 .Pp
 167 In addition,
 168 .Fn readv
 169 and
 170 .Fn preadv
 171 may return one of the following errors:
 172 .Bl -tag -width Er
 173 .It Bq Er EINVAL
 174 .Fa iovcnt
 175 was less than or equal to 0, or greater than
 176 .Dv {IOV_MAX} .
 177 .It Bq Er EINVAL
 178 One of the
 179 .Fa iov_len
 180 values in the
 181 .Fa iov
 182 array was negative.
 183 .It Bq Er EINVAL
 184 The sum of the
 185 .Fa iov_len
 186 values in the
 187 .Fa iov
 188 array overflowed a 32-bit integer.
 189 .It Bq Er EFAULT
 190 Part of the
 191 .Fa iov
 192 points outside the process's allocated address space.
 193 .El
 194 .Pp
 195 The
 196 .Fn pread
 197 and
 198 .Fn preadv
 199 calls may also return the following errors:
 200 .Bl -tag -width Er
 201 .It Bq Er EINVAL
 202 The specified file offset is invalid.
 203 .It Bq Er ESPIPE
 204 The file descriptor is associated with a pipe, socket, or FIFO.
 205 .El
 206 .Sh SEE ALSO
 207 .Xr dup 2 ,
 208 .Xr fcntl 2 ,
 209 .Xr open 2 ,
 210 .Xr pipe 2 ,
 211 .Xr poll 2 ,
 212 .Xr select 2 ,
 213 .Xr sigaction 2 ,
 214 .Xr socket 2 ,
 215 .Xr socketpair 2
 216 .Sh STANDARDS
 217 The
 218 .Fn read
 219 function conforms to
 220 .St -p1003.1-90 .
 221 The
 222 .Fn readv
 223 and
 224 .Fn pread
 225 functions conform to
 226 .St -xpg4.2 .
 227 .Sh HISTORY
 228 The
 229 .Fn preadv
 230 function call
 231 appeared in
 232 .Nx 1.4 .
 233 The
 234 .Fn pread
 235 function call
 236 appeared in
 237 .At V.4 .
 238 The
 239 .Fn readv
 240 function call
 241 appeared in
 242 .Bx 4.2 .
 243 The
 244 .Fn read
 245 function call appeared in
 246 .At v6 .
 247 .Sh CAVEATS
 248 Error checks should explicitly test for \-1.
 249 Code such as
 250 .Bd -literal
 251         while ((nr = read(fd, buf, sizeof(buf))) \*[Gt] 0)
 252 .Ed
 253 .Pp
 254 is not maximally portable, as some platforms allow for
 255 .Va nbytes
 256 to range between
 257 .Dv SSIZE_MAX
 258 and
 259 .Dv SIZE_MAX
 260 \- 2, in which case the return value of an error-free
 261 .Fn read
 262 may appear as a negative number distinct from \-1.
 263 Proper loops should use
 264 .Bd -literal
 265         while ((nr = read(fd, buf, sizeof(buf))) != -1 \*[Am]\*[Am] nr != 0)
 266 .Ed