lib/libc/sys/read.2

   1 .\" Copyright (c) 1980, 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. 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 .\"     @(#)read.2      8.4 (Berkeley) 2/26/94
  29 .\" $FreeBSD: src/lib/libc/sys/read.2,v 1.9.2.6 2001/12/14 18:34:01 ru Exp $
  30 .\" $DragonFly: src/lib/libc/sys/read.2,v 1.5 2006/04/27 16:01:33 swildner Exp $
  31 .\"
  32 .Dd April 27, 2006
  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 sys/types.h
  45 .In sys/uio.h
  46 .In unistd.h
  47 .Ft ssize_t
  48 .Fn read "int d" "void *buf" "size_t nbytes"
  49 .Ft ssize_t
  50 .Fn readv "int d" "const struct iovec *iov" "int iovcnt"
  51 .Ft ssize_t
  52 .Fn pread "int d" "void *buf" "size_t nbytes" "off_t offset"
  53 .Ft ssize_t
  54 .Fn preadv "int d" "const struct iovec *iov" "int iovcnt" "off_t offset"
  55 .Sh DESCRIPTION
  56 .Fn Read
  57 attempts to read
  58 .Fa nbytes
  59 of data from the object referenced by the descriptor
  60 .Fa d
  61 into the buffer pointed to by
  62 .Fa buf .
  63 .Fn Readv
  64 performs the same action, but scatters the input data
  65 into the
  66 .Fa iovcnt
  67 buffers specified by the members of the
  68 .Fa iov
  69 array: iov[0], iov[1], ..., iov[iovcnt\|\-\|1].
  70 The
  71 .Fn pread
  72 and
  73 .Fn preadv
  74 calls perform the same function, but read from the specified position in
  75 the file without modifying the file pointer.
  76 .Pp
  77 For
  78 .Fn readv
  79 and
  80 .Fn preadv ,
  81 the
  82 .Fa iovec
  83 structure is defined as:
  84 .Pp
  85 .Bd -literal -offset indent -compact
  86 struct iovec {
  87         char   *iov_base;  /* Base address. */
  88         size_t iov_len;    /* Length. */
  89 };
  90 .Ed
  91 .Pp
  92 Each
  93 .Fa iovec
  94 entry specifies the base address and length of an area
  95 in memory where data should be placed.
  96 .Fn Readv
  97 and
  98 .Fn preadv
  99 will always fill an area completely before proceeding
 100 to the next.
 101 .Pp
 102 On objects capable of seeking, the
 103 .Fn read
 104 starts at a position
 105 given by the pointer associated with
 106 .Fa d
 107 (see
 108 .Xr lseek 2 ) .
 109 Upon return from
 110 .Fn read ,
 111 the pointer is incremented by the number of bytes actually read.
 112 .Pp
 113 Objects that are not capable of seeking always read from the current
 114 position.  The value of the pointer associated with such an
 115 object is undefined.
 116 .Pp
 117 Upon successful completion,
 118 .Fn read ,
 119 .Fn readv ,
 120 .Fn pread ,
 121 and
 122 .Fn preadv
 123 return the number of bytes actually read and placed in the buffer.
 124 The system guarantees to read the number of bytes requested if
 125 the descriptor references a normal file that has that many bytes left
 126 before the end-of-file, but in no other case.
 127 .Sh RETURN VALUES
 128 If successful, the
 129 number of bytes actually read is returned.
 130 Upon reading end-of-file,
 131 zero is returned.
 132 Otherwise, a -1 is returned and the global variable
 133 .Va errno
 134 is set to indicate the error.
 135 .Sh ERRORS
 136 .Fn Read ,
 137 .Fn readv ,
 138 .Fn pread ,
 139 and
 140 .Fn preadv
 141 will succeed unless:
 142 .Bl -tag -width Er
 143 .It Bq Er EBADF
 144 .Fa D
 145 is not a valid file or socket descriptor open for reading.
 146 .It Bq Er EFAULT
 147 .Fa Buf
 148 points outside the allocated address space.
 149 .It Bq Er EIO
 150 An I/O error occurred while reading from the file system.
 151 .It Bq Er EINTR
 152 A read from a slow device was interrupted before
 153 any data arrived by the delivery of a signal.
 154 .It Bq Er EINVAL
 155 The pointer associated with
 156 .Fa d
 157 was negative.
 158 .It Bq Er EAGAIN
 159 The file was marked for non-blocking I/O,
 160 and no data were ready to be read.
 161 .El
 162 .Pp
 163 In addition,
 164 .Fn readv
 165 and
 166 .Fn preadv
 167 may return one of the following errors:
 168 .Bl -tag -width Er
 169 .It Bq Er EINVAL
 170 .Fa Iovcnt
 171 was less than or equal to 0, or greater than 16.
 172 .It Bq Er EINVAL
 173 One of the
 174 .Fa iov_len
 175 values in the
 176 .Fa iov
 177 array was negative.
 178 .It Bq Er EINVAL
 179 The sum of the
 180 .Fa iov_len
 181 values in the
 182 .Fa iov
 183 array overflowed a 32-bit integer.
 184 .It Bq Er EFAULT
 185 Part of the
 186 .Fa iov
 187 points outside the process's allocated address space.
 188 .El
 189 .Pp
 190 The
 191 .Fn pread
 192 and
 193 .Fn preadv
 194 calls may also return the following errors:
 195 .Bl -tag -width Er
 196 .It Bq Er EINVAL
 197 The specified file offset is invalid.
 198 .It Bq Er ESPIPE
 199 The file descriptor is associated with a pipe, socket, or FIFO.
 200 .El
 201 .Sh SEE ALSO
 202 .Xr dup 2 ,
 203 .Xr fcntl 2 ,
 204 .Xr open 2 ,
 205 .Xr pipe 2 ,
 206 .Xr select 2 ,
 207 .Xr socket 2 ,
 208 .Xr socketpair 2
 209 .Sh STANDARDS
 210 The
 211 .Fn read
 212 function call is expected to conform to
 213 .St -p1003.1-90 .
 214 The
 215 .Fn readv
 216 and
 217 .Fn pread
 218 functions are expected to conform to
 219 .St -xpg4.2 .
 220 .Sh HISTORY
 221 The
 222 .Fn preadv
 223 function call was added in
 224 .Dx 1.5 .
 225 The
 226 .Fn pread
 227 function call
 228 appeared in
 229 .At V.4 .
 230 The
 231 .Fn readv
 232 function call
 233 appeared in
 234 .Bx 4.2 .
 235 A
 236 .Fn read
 237 function call appeared in
 238 .At v6 .