bsd/man/man2/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 .\"
  35 .Dd February 26, 1994
  36 .Dt READ 2
  37 .Os
  38 .Sh NAME
  39 .Nm pread ,
  40 .Nm read ,
  41 .Nm preadv ,
  42 .Nm readv
  43 .Nd read input
  44 .Sh LIBRARY
  45 .Lb libc
  46 .Sh SYNOPSIS
  47 .In sys/types.h
  48 .In sys/uio.h
  49 .In unistd.h
  50 .Ft ssize_t
  51 .Fo pread
  52 .Fa "int d"
  53 .Fa "void *buf"
  54 .Fa "size_t nbyte"
  55 .Fa "off_t offset"
  56 .Fc
  57 .Ft ssize_t
  58 .Fo read
  59 .Fa "int fildes"
  60 .Fa "void *buf"
  61 .Fa "size_t nbyte"
  62 .Fc
  63 .Ft ssize_t
  64 .Fo preadv
  65 .Fa "int d"
  66 .Fa "const struct iovec *iov"
  67 .Fa "int iovcnt"
  68 .Fa "off_t offset"
  69 .Fc
  70 .Ft ssize_t
  71 .Fo readv
  72 .Fa "int d"
  73 .Fa "const struct iovec *iov"
  74 .Fa "int iovcnt"
  75 .Fc
  76 .Sh DESCRIPTION
  77 .Fn read
  78 attempts to read
  79 .Fa nbyte
  80 bytes of data from the object referenced by the descriptor
  81 .Fa fildes
  82 into the buffer pointed to by
  83 .Fa buf .
  84 .Fn readv
  85 performs the same action,
  86 but scatters the input data into the
  87 .Fa iovcnt
  88 buffers specified by the members of the
  89 .Fa iov
  90 array: iov[0], iov[1], ..., iov[iovcnt\|\-\|1].
  91 .Fn pread
  92 and
  93 .Fn preadv
  94 perform the same functions,
  95 but read from the specified position in the file
  96 without modifying the file pointer.
  97 .Pp
  98 For
  99 .Fn readv
 100 and
 101 .Fn preadv ,
 102 the
 103 .Fa iovec
 104 structure is defined as:
 105 .Pp
 106 .Bd -literal -offset indent -compact
 107 struct iovec {
 108         char   *iov_base;  /* Base address. */
 109         size_t iov_len;    /* Length. */
 110 };
 111 .Ed
 112 .Pp
 113 Each
 114 .Fa iovec
 115 entry specifies the base address and length of an area
 116 in memory where data should be placed.
 117 .Fn readv
 118 and
 119 .Fn preadv
 120 will always fill an area completely before proceeding
 121 to the next.
 122 .Pp
 123 On objects capable of seeking, the
 124 .Fn read
 125 starts at a position
 126 given by the pointer associated with
 127 .Fa fildes
 128 (see
 129 .Xr lseek 2 ) .
 130 Upon return from
 131 .Fn read ,
 132 the pointer is incremented by the number of bytes actually read.
 133 .Pp
 134 Objects that are not capable of seeking always read from the current
 135 position.  The value of the pointer associated with such an
 136 object is undefined.
 137 .Pp
 138 Upon successful completion,
 139 .Fn read ,
 140 .Fn readv ,
 141 .Fn pread ,
 142 and
 143 .Fn preadv
 144 return the number of bytes actually read and placed in the buffer.
 145 The system guarantees to read the number of bytes requested if
 146 the descriptor references a normal file that has that many bytes left
 147 before the end-of-file, but in no other case.
 148 .Sh RETURN VALUES
 149 If successful, the
 150 number of bytes actually read is returned.
 151 Upon reading end-of-file,
 152 zero is returned.
 153 Otherwise, a -1 is returned and the global variable
 154 .Va errno
 155 is set to indicate the error.
 156 .Sh ERRORS
 157 The
 158 .Fn read ,
 159 .Fn readv ,
 160 .Fn pread ,
 161 and
 162 .Fn preadv
 163 calls
 164 will succeed unless:
 165 .Bl -tag -width Er
 166 .\" ===========
 167 .It Bq Er EAGAIN
 168 The file was marked for non-blocking I/O,
 169 and no data were ready to be read.
 170 .\" ===========
 171 .It Bq Er EBADF
 172 .Fa fildes
 173 is not a valid file or socket descriptor open for reading.
 174 .\" ===========
 175 .It Bq Er EFAULT
 176 .Fa Buf
 177 points outside the allocated address space.
 178 .\" ===========
 179 .It Bq Er EINTR
 180 A read from a slow device was interrupted before
 181 any data arrived by the delivery of a signal.
 182 .It Bq Er EINVAL
 183 The pointer associated with
 184 .Fa fildes
 185 was negative.
 186 .\" ===========
 187 .It Bq Er EIO
 188 An I/O error occurred while reading from the file system.
 189 .\" ===========
 190 .\" .It Bq Er EIO
 191 .\" The process is a member of a background process
 192 .\" attempting to read from its controlling terminal.
 193 .\" ===========
 194 .\" .It Bq Er EIO
 195 .\" The process is ignoring or blocking the SIGTTIN signal.
 196 .\" ===========
 197 .It Bq Er EIO
 198 The process group is orphaned.
 199 .\" ===========
 200 .It Bq Er EIO
 201 The file is a regular file,
 202 .Fa nbyte
 203 is greater than 0,
 204 the starting position is before the end-of-file,
 205 and the starting position is greater than or equal
 206 to the offset maximum established
 207 for the open file descriptor associated with
 208 .Fa fildes .
 209 .\" ===========
 210 .It Bq Er EISDIR
 211 An attempt is made to read a directory.
 212 .\" ===========
 213 .It Bq Er ENOBUFS
 214 An attempt to allocate a memory buffer fails.
 215 .\" ===========
 216 .It Bq Er ENOMEM
 217 Insufficient memory is available.
 218 .\" ===========
 219 .It Bq Er ENXIO
 220 An action is requested of a device that does not exist.
 221 .\" ===========
 222 .It Bq Er ENXIO
 223 A requested action cannot be performed by the device.
 224 .\" ===========
 225 .It Bq Er ESTALE
 226 An attempt to read a remote file through NFS that has already been deleted in
 227 the server.
 228 .\" ===========
 229 .It Bq Er ETIMEDOUT
 230 The connection timed out while reading a remote file from a soft mounted NFS
 231 volume (see
 232 .Xr mount_nfs 8 ) .
 233 .El
 234 .Pp
 235 .Fn pread
 236 and
 237 .Fn preadv
 238 calls may also return the following errors:
 239 .Bl -tag -width Er
 240 .\" ===========
 241 .It Bq Er EINVAL
 242 The specified file offset is invalid.
 243 .\" ===========
 244 .It Bq Er ESPIPE
 245 The file descriptor is associated with a pipe, socket, or FIFO.
 246 .El
 247 .Pp
 248 The
 249 .Fn read
 250 call may also return the following errors:
 251 .Bl -tag -width Er
 252 .\" ===========
 253 .It Bq Er ECONNRESET
 254 The connection is closed by the peer
 255 during a read attempt on a socket.
 256 .\" ===========
 257 .It Bq Er ENOTCONN
 258 A read is attempted on an unconnected socket.
 259 .\" ===========
 260 .It Bq Er ETIMEDOUT
 261 A transmission timeout occurs
 262 during a read attempt on a socket.
 263 .El
 264 .Pp
 265 The
 266 .Fn readv
 267 and
 268 .Fn preadv
 269 calls may also return one of the following errors:
 270 .Bl -tag -width Er
 271 .\" ===========
 272 .It Bq Er EFAULT
 273 Part of the
 274 .Fa iov
 275 points outside the process's allocated address space.
 276 .\" ===========
 277 .It Bq Er EINVAL
 278 .Fa Iovcnt
 279 was less than or equal to 0, or greater than 16.
 280 .\" ===========
 281 .It Bq Er EINVAL
 282 One of the
 283 .Fa iov_len
 284 values in the
 285 .Fa iov
 286 array was negative.
 287 .\" ===========
 288 .It Bq Er EINVAL
 289 The sum of the
 290 .Fa iov_len
 291 values in the
 292 .Fa iov
 293 array overflowed a 32-bit integer.
 294 .El
 295 .Sh LEGACY SYNOPSIS
 296 .Fd #include <sys/types.h>
 297 .Fd #include <sys/uio.h>
 298 .Fd #include <unistd.h>
 299 .Pp
 300 The include files
 301 .In sys/types.h
 302 and
 303 .In sys/uio.h
 304 are necessary for all functions.
 305 .Sh SEE ALSO
 306 .Xr dup 2 ,
 307 .Xr fcntl 2 ,
 308 .Xr open 2 ,
 309 .Xr pipe 2 ,
 310 .Xr select 2 ,
 311 .Xr socket 2 ,
 312 .Xr socketpair 2 ,
 313 .Xr compat 5
 314 .Sh STANDARDS
 315 The
 316 .Fn read
 317 function call is expected to conform to
 318 .St -p1003.1-90 .
 319 The
 320 .Fn readv
 321 and
 322 .Fn pread
 323 functions are expected to conform to
 324 .St -xpg4.2 .
 325 .Fn preadv
 326 is nonstandard.
 327 .Sh HISTORY
 328 The
 329 .Fn pread
 330 function call
 331 appeared in
 332 .At V.4 .
 333 The
 334 .Fn readv
 335 function call
 336 appeared in
 337 .Bx 4.2 .
 338 A
 339 .Fn read
 340 function call appeared in
 341 .At v6 .