1.\" $NetBSD: read.2,v 1.33 2010/04/05 07:53:47 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 April 3, 2010 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.El 165.Pp 166In addition, 167.Fn readv 168and 169.Fn preadv 170may return one of the following errors: 171.Bl -tag -width Er 172.It Bq Er EFAULT 173Part of the 174.Fa iov 175points outside the process's allocated address space. 176.It Bq Er EINVAL 177.Fa iovcnt 178was less than or equal to 0, or greater than 179.Dv {IOV_MAX} ; 180or one of the 181.Fa iov_len 182values in the 183.Fa iov 184array was negative; or 185the sum of the 186.Fa iov_len 187values in the 188.Fa iov 189array overflowed a 32-bit integer. 190.El 191.Pp 192The 193.Fn pread 194and 195.Fn preadv 196calls may also return the following errors: 197.Bl -tag -width Er 198.It Bq Er EINVAL 199The specified file offset is invalid. 200.It Bq Er ESPIPE 201The file descriptor is associated with a pipe, socket, or FIFO. 202.El 203.Sh SEE ALSO 204.Xr dup 2 , 205.Xr fcntl 2 , 206.Xr open 2 , 207.Xr pipe 2 , 208.Xr poll 2 , 209.Xr select 2 , 210.Xr sigaction 2 , 211.Xr socket 2 , 212.Xr socketpair 2 213.Sh STANDARDS 214The 215.Fn read 216function conforms to 217.St -p1003.1-90 . 218The 219.Fn readv 220and 221.Fn pread 222functions conform to 223.St -xpg4.2 . 224.Sh HISTORY 225The 226.Fn preadv 227function call 228appeared in 229.Nx 1.4 . 230The 231.Fn pread 232function call 233appeared in 234.At V.4 . 235The 236.Fn readv 237function call 238appeared in 239.Bx 4.2 . 240The 241.Fn read 242function call appeared in 243.At v2 . 244.Sh CAVEATS 245Error checks should explicitly test for \-1. 246Code such as 247.Bd -literal 248 while ((nr = read(fd, buf, sizeof(buf))) \*[Gt] 0) 249.Ed 250.Pp 251is not maximally portable, as some platforms allow for 252.Va nbytes 253to range between 254.Dv SSIZE_MAX 255and 256.Dv SIZE_MAX 257\- 2, in which case the return value of an error-free 258.Fn read 259may appear as a negative number distinct from \-1. 260Proper loops should use 261.Bd -literal 262 while ((nr = read(fd, buf, sizeof(buf))) != -1 \*[Am]\*[Am] nr != 0) 263.Ed 264