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