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