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