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