1.\" $NetBSD: read.2,v 1.31 2007/08/02 23:46:39 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 August 2, 2007 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 EBADF 139.Fa d 140is not a valid file or socket descriptor open for reading. 141.It Bq Er EFAULT 142.Fa buf 143points outside the allocated address space. 144.It Bq Er EIO 145An I/O error occurred while reading from the file system. 146.It Bq Er EINTR 147A read from a slow device 148(i.e. one that might block for an arbitrary amount of time) 149was interrupted by the delivery of a signal 150before any data arrived. 151See 152.Xr sigaction 2 153for more information on the interaction between signals and system 154calls. 155.It Bq Er EINVAL 156The file pointer associated with 157.Fa d 158was negative. 159.It Bq Er EINVAL 160The total length of the I/O is more than can be expressed by the ssize_t 161return value. 162.It Bq Er EAGAIN 163The file was marked for non-blocking I/O, 164and no data were ready to be read. 165.El 166.Pp 167In addition, 168.Fn readv 169and 170.Fn preadv 171may return one of the following errors: 172.Bl -tag -width Er 173.It Bq Er EINVAL 174.Fa iovcnt 175was less than or equal to 0, or greater than 176.Dv {IOV_MAX} . 177.It Bq Er EINVAL 178One of the 179.Fa iov_len 180values in the 181.Fa iov 182array was negative. 183.It Bq Er EINVAL 184The sum of the 185.Fa iov_len 186values in the 187.Fa iov 188array overflowed a 32-bit integer. 189.It Bq Er EFAULT 190Part of the 191.Fa iov 192points outside the process's allocated address space. 193.El 194.Pp 195The 196.Fn pread 197and 198.Fn preadv 199calls may also return the following errors: 200.Bl -tag -width Er 201.It Bq Er EINVAL 202The specified file offset is invalid. 203.It Bq Er ESPIPE 204The file descriptor is associated with a pipe, socket, or FIFO. 205.El 206.Sh SEE ALSO 207.Xr dup 2 , 208.Xr fcntl 2 , 209.Xr open 2 , 210.Xr pipe 2 , 211.Xr poll 2 , 212.Xr select 2 , 213.Xr sigaction 2 , 214.Xr socket 2 , 215.Xr socketpair 2 216.Sh STANDARDS 217The 218.Fn read 219function conforms to 220.St -p1003.1-90 . 221The 222.Fn readv 223and 224.Fn pread 225functions conform to 226.St -xpg4.2 . 227.Sh HISTORY 228The 229.Fn preadv 230function call 231appeared in 232.Nx 1.4 . 233The 234.Fn pread 235function call 236appeared in 237.At V.4 . 238The 239.Fn readv 240function call 241appeared in 242.Bx 4.2 . 243The 244.Fn read 245function call appeared in 246.At v6 . 247.Sh CAVEATS 248Error checks should explicitly test for \-1. 249Code such as 250.Bd -literal 251 while ((nr = read(fd, buf, sizeof(buf))) \*[Gt] 0) 252.Ed 253.Pp 254is not maximally portable, as some platforms allow for 255.Va nbytes 256to range between 257.Dv SSIZE_MAX 258and 259.Dv SIZE_MAX 260\- 2, in which case the return value of an error-free 261.Fn read 262may appear as a negative number distinct from \-1. 263Proper loops should use 264.Bd -literal 265 while ((nr = read(fd, buf, sizeof(buf))) != -1 \*[Am]\*[Am] nr != 0) 266.Ed 267