1.\" $OpenBSD: read.2,v 1.19 2001/05/14 15:11:26 espie Exp $ 2.\" $NetBSD: read.2,v 1.6 1995/02/27 12:35:47 cgd Exp $ 3.\" 4.\" Copyright (c) 1980, 1991, 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. All advertising materials mentioning features or use of this software 16.\" must display the following acknowledgement: 17.\" This product includes software developed by the University of 18.\" California, Berkeley and its contributors. 19.\" 4. Neither the name of the University nor the names of its contributors 20.\" may be used to endorse or promote products derived from this software 21.\" without specific prior written permission. 22.\" 23.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 24.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 25.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 26.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 27.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 28.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 29.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 30.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 31.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 32.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 33.\" SUCH DAMAGE. 34.\" 35.\" @(#)read.2 8.4 (Berkeley) 2/26/94 36.\" 37.Dd July 28, 1998 38.Dt READ 2 39.Os 40.Sh NAME 41.Nm read , 42.Nm readv , 43.Nm pread , 44.Nm preadv 45.Nd read input 46.Sh SYNOPSIS 47.Fd #include <sys/types.h> 48.Fd #include <unistd.h> 49.Ft ssize_t 50.Fn read "int d" "void *buf" "size_t nbytes" 51.Ft ssize_t 52.Fn pread "int d" "void *buf" "size_t nbytes" "off_t offset" 53.Pp 54.Fd #include <sys/types.h> 55.Fd #include <sys/uio.h> 56.Fd #include <unistd.h> 57.Ft ssize_t 58.Fn readv "int d" "const struct iovec *iov" "int iovcnt" 59.Ft ssize_t 60.Fn preadv "int d" "const struct iovec *iov" "int iovcnt" "off_t offset" 61.Sh DESCRIPTION 62.Fn read 63attempts to read 64.Fa nbytes 65of data from the object referenced by the descriptor 66.Fa d 67into the buffer pointed to by 68.Fa buf . 69.Fn readv 70performs the same action, but scatters the input data 71into the 72.Fa iovcnt 73buffers specified by the members of the 74.Fa iov 75array: iov[0], iov[1], ..., iov[iovcnt\|\-\|1]. 76.Fn pread 77and 78.Fn preadv 79perform the same functions, but read from the specified position in 80the file without modifying the file pointer. 81.Pp 82For 83.Fn readv 84and 85.Fn preadv , 86the 87.Fa iovec 88structure is defined as: 89.Pp 90.Bd -literal -offset indent -compact 91struct iovec { 92 void *iov_base; 93 size_t iov_len; 94}; 95.Ed 96.Pp 97Each 98.Fa iovec 99entry specifies the base address and length of an area 100in memory where data should be placed. 101.Fn readv 102will always fill an area completely before proceeding 103to the next. 104.Pp 105On objects capable of seeking, the 106.Fn read 107starts at a position 108given by the pointer associated with 109.Fa d 110(see 111.Xr lseek 2 ) . 112Upon return from 113.Fn read , 114the pointer is incremented by the number of bytes actually read. 115.Pp 116Objects that are not capable of seeking always read from the current 117position. 118The value of the pointer associated with such an object is undefined. 119.Pp 120Upon successful completion, 121.Fn read 122.Fn readv , 123.Fn pread , 124and 125.Fn preadv 126return the number of bytes actually read and placed in the buffer. 127The system guarantees to read the number of bytes requested if 128the descriptor references a normal file that has that many bytes left 129before the end-of-file, but in no other case. 130.Pp 131Note that 132.Fn readv 133and 134.Fn preadv 135will fail if the value of 136.Fa iovcnt 137exceedes the constant 138.Dv IOV_MAX . 139.Sh RETURN VALUES 140If successful, the 141number of bytes actually read is returned. 142Upon reading end-of-file, zero is returned. 143Otherwise, a \-1 is returned and the global variable 144.Va errno 145is set to indicate the error. 146.Sh ERRORS 147.Fn read 148.Fn readv , 149.Fn pread , 150and 151.Fn preadv 152will succeed unless: 153.Bl -tag -width Er 154.It Bq Er EBADF 155.Fa d 156is not a valid file or socket descriptor open for reading. 157.It Bq Er EFAULT 158.Fa buf 159points outside the allocated address space. 160.It Bq Er EIO 161An I/O error occurred while reading from the file system. 162.It Bq Er EINTR 163A read from a slow device was interrupted before 164any data arrived by the delivery of a signal. 165.It Bq Er EINVAL 166The pointer associated with 167.Fa d 168was negative. 169.It Bq Er EAGAIN 170The file was marked for non-blocking I/O, 171and no data were ready to be read. 172.El 173.Pp 174In addition, 175.Fn read 176and 177.Fn pread 178may return the following error: 179.Bl -tag -width Er 180.It Bq Er EINVAL 181.Fa nbytes 182was larger than 183.Dv SSIZE_MAX . 184.El 185.Pp 186Also, 187.Fn readv 188and 189.Fn preadv 190may return one of the following errors: 191.Bl -tag -width Er 192.It Bq Er EINVAL 193.Fa iovcnt 194was less than or equal to 0, or greater than 195.Dv IOV_MAX . 196.It Bq Er EINVAL 197The sum of the 198.Fa iov_len 199values in the 200.Fa iov 201array overflowed an 202.Em ssize_t . 203.It Bq Er EFAULT 204Part of the 205.Fa iov 206points outside the process's allocated address space. 207.El 208.Sh SEE ALSO 209.Xr dup 2 , 210.Xr fcntl 2 , 211.Xr open 2 , 212.Xr pipe 2 , 213.Xr poll 2 , 214.Xr select 2 , 215.Xr socket 2 , 216.Xr socketpair 2 217.Sh STANDARDS 218The 219.Fn read 220function conforms to 221.St -p1003.1-90 . 222The 223.Fn readv 224and 225.Fn pread 226functions conform to 227.St -xpg4.2 . 228.Sh CAVEATS 229Error checks should explicitly test for \-1. 230Code such as 231.Bd -literal 232 while ((nr = read(fd, buf, sizeof(buf))) > 0) 233.Ed 234.Pp 235is not maximally portable, as some platforms allow for 236.Va nbytes 237to range between 238.Dv SSIZE_MAX 239and 240.Dv SIZE_MAX 241\- 2, in which case the return value of an error-free 242.Fn read 243may appear as a negative number distinct from \-1. 244Proper loops should use 245.Bd -literal 246 while ((nr = read(fd, buf, sizeof(buf))) != -1 && nr != 0) 247.Ed 248.Sh HISTORY 249The 250.Fn preadv 251function first appeared in 252.Ox 2.7 . 253The 254.Fn pread 255function appeared in 256.At V.4 . 257The 258.Fn readv 259function call appeared in 260.Bx 4.2 . 261The 262.Fn read 263function call appeared in 264.At v6 . 265