1.\" $OpenBSD: read.2,v 1.38 2021/11/21 23:44:55 jan 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: November 21 2021 $ 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 fail if: 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 EINTR 156A read from a slow device 157(i.e. one that might block for an arbitrary amount of time) 158was interrupted by the delivery of a signal 159before any data arrived. 160.It Bq Er EIO 161An I/O error occurred while reading from the file system. 162.It Bq Er EISDIR 163The underlying file is a directory. 164.El 165.Pp 166In addition, 167.Fn read 168and 169.Fn readv 170may return the following errors: 171.Bl -tag -width Er 172.It Bq Er EAGAIN 173The file was marked for non-blocking I/O, 174and no data were ready to be read. 175.It Bq Er ENOTCONN 176The file is a socket associated with a connection-oriented protocol 177and has not been connected. 178.It Bq Er EIO 179The process is a member of a background process attempting to read 180from its controlling terminal, the process is ignoring or blocking 181the 182.Dv SIGTTIN 183signal or the process group is orphaned. 184.El 185.Pp 186.Fn read 187and 188.Fn pread 189may return the following error: 190.Bl -tag -width Er 191.It Bq Er EINVAL 192.Fa nbytes 193was larger than 194.Dv SSIZE_MAX . 195.El 196.Pp 197.Fn pread 198and 199.Fn preadv 200may return the following errors: 201.Bl -tag -width Er 202.It Bq Er EINVAL 203.Fa offset 204was negative. 205.It Bq Er ESPIPE 206.Fa d 207is associated with a pipe, socket, FIFO, or tty. 208.El 209.Pp 210.Fn readv 211and 212.Fn preadv 213may return the following errors: 214.Bl -tag -width Er 215.It Bq Er EINVAL 216.Fa iovcnt 217was less than or equal to 0, or greater than 218.Dv IOV_MAX . 219.It Bq Er EINVAL 220The sum of the 221.Fa iov_len 222values in the 223.Fa iov 224array overflowed an 225.Vt ssize_t . 226.It Bq Er EFAULT 227Part of 228.Fa iov 229points outside the process's allocated address space. 230.El 231.Sh SEE ALSO 232.Xr dup 2 , 233.Xr fcntl 2 , 234.Xr open 2 , 235.Xr pipe 2 , 236.Xr poll 2 , 237.Xr select 2 , 238.Xr socket 2 , 239.Xr socketpair 2 240.Sh STANDARDS 241The 242.Fn read , 243.Fn readv , 244and 245.Fn pread 246functions conform to 247.St -p1003.1-2008 . 248.Sh HISTORY 249A 250.Fn read 251system call first appeared in 252.At v1 ; 253.Fn readv 254in 255.Bx 4.1c ; 256.Fn pread 257in 258.At V.4 ; 259and 260.Fn preadv 261in 262.Ox 2.7 . 263.Sh CAVEATS 264Error checks should explicitly test for \-1. 265Code such as 266.Bd -literal -offset indent 267while ((nr = read(fd, buf, sizeof(buf))) > 0) 268.Ed 269.Pp 270is not maximally portable, as some platforms allow for 271.Fa nbytes 272to range between 273.Dv SSIZE_MAX 274and 275.Dv SIZE_MAX 276\- 2, in which case the return value of an error-free 277.Fn read 278may appear as a negative number distinct from \-1. 279Proper loops should use 280.Bd -literal -offset indent 281while ((nr = read(fd, buf, sizeof(buf))) != -1 && nr != 0) 282.Ed 283