1.\" Copyright (c) 1980, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" @(#)read.2 8.4 (Berkeley) 2/26/94 29.\" 30.Dd June 4, 2020 31.Dt READ 2 32.Os 33.Sh NAME 34.Nm read , 35.Nm readv , 36.Nm pread , 37.Nm preadv 38.Nd read input 39.Sh LIBRARY 40.Lb libc 41.Sh SYNOPSIS 42.In unistd.h 43.Ft ssize_t 44.Fn read "int fd" "void *buf" "size_t nbytes" 45.Ft ssize_t 46.Fn pread "int fd" "void *buf" "size_t nbytes" "off_t offset" 47.In sys/uio.h 48.Ft ssize_t 49.Fn readv "int fd" "const struct iovec *iov" "int iovcnt" 50.Ft ssize_t 51.Fn preadv "int fd" "const struct iovec *iov" "int iovcnt" "off_t offset" 52.Sh DESCRIPTION 53The 54.Fn read 55system call 56attempts to read 57.Fa nbytes 58of data from the object referenced by the descriptor 59.Fa fd 60into the buffer pointed to by 61.Fa buf . 62The 63.Fn readv 64system call 65performs the same action, but scatters the input data 66into the 67.Fa iovcnt 68buffers specified by the members of the 69.Fa iov 70array: iov[0], iov[1], ..., iov[iovcnt\|\-\|1]. 71The 72.Fn pread 73and 74.Fn preadv 75system calls 76perform the same functions, but read from the specified position in 77the file without modifying the file pointer. 78.Pp 79For 80.Fn readv 81and 82.Fn preadv , 83the 84.Fa iovec 85structure is defined as: 86.Pp 87.Bd -literal -offset indent -compact 88struct iovec { 89 void *iov_base; /* Base address. */ 90 size_t iov_len; /* Length. */ 91}; 92.Ed 93.Pp 94Each 95.Fa iovec 96entry specifies the base address and length of an area 97in memory where data should be placed. 98The 99.Fn readv 100system call 101will always fill an area completely before proceeding 102to the next. 103.Pp 104On objects capable of seeking, the 105.Fn read 106starts at a position 107given by the pointer associated with 108.Fa fd 109(see 110.Xr lseek 2 ) . 111Upon return from 112.Fn read , 113the pointer is incremented by the number of bytes actually read. 114.Pp 115Objects that are not capable of seeking always read from the current 116position. 117The value of the pointer associated with such an 118object 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 131In accordance with 132.St -p1003.1-2004 , 133both 134.Xr read 2 135and 136.Xr write 2 137syscalls are atomic with respect to each other in the effects on file 138content, when they operate on regular files. 139If two threads each call one of the 140.Xr read 2 141or 142.Xr write 2 , 143syscalls, each call will see either all of the changes of the other call, 144or none of them. 145The 146.Fx 147kernel implements this guarantee by locking the file ranges affected by 148the calls. 149.Sh RETURN VALUES 150If successful, the 151number of bytes actually read is returned. 152Upon reading end-of-file, 153zero is returned. 154Otherwise, a -1 is returned and the global variable 155.Va errno 156is set to indicate the error. 157.Sh ERRORS 158The 159.Fn read , 160.Fn readv , 161.Fn pread 162and 163.Fn preadv 164system calls 165will succeed unless: 166.Bl -tag -width Er 167.It Bq Er EBADF 168The 169.Fa fd 170argument 171is not a valid file or socket descriptor open for reading. 172.It Bq Er ECONNRESET 173The 174.Fa fd 175argument refers to a socket, and the remote socket end is 176forcibly closed. 177.It Bq Er EFAULT 178The 179.Fa buf 180argument 181points outside the allocated address space. 182.It Bq Er EIO 183An I/O error occurred while reading from the file system. 184.It Bq Er EINTEGRITY 185Corrupted data was detected while reading from the file system. 186.It Bq Er EBUSY 187Failed to read from a file, e.g. /proc/<pid>/regs while <pid> is not stopped 188.It Bq Er EINTR 189A read from a slow device 190(i.e.\& one that might block for an arbitrary amount of time) 191was interrupted by the delivery of a signal 192before any data arrived. 193.It Bq Er EINVAL 194The pointer associated with 195.Fa fd 196was negative. 197.It Bq Er EAGAIN 198The file was marked for non-blocking I/O, 199and no data were ready to be read. 200.It Bq Er EISDIR 201The file descriptor is associated with a directory. 202Directories may only be read directly by root if the filesystem supports it and 203the 204.Dv security.bsd.allow_read_dir 205sysctl MIB is set to a non-zero value. 206For most scenarios, the 207.Xr readdir 3 208function should be used instead. 209.It Bq Er EOPNOTSUPP 210The file descriptor is associated with a file system and file type that 211do not allow regular read operations on it. 212.It Bq Er EOVERFLOW 213The file descriptor is associated with a regular file, 214.Fa nbytes 215is greater than 0, 216.Fa offset 217is before the end-of-file, and 218.Fa offset 219is greater than or equal to the offset maximum established 220for this file system. 221.It Bq Er EINVAL 222The value 223.Fa nbytes 224is greater than 225.Dv INT_MAX . 226.El 227.Pp 228In addition, 229.Fn readv 230and 231.Fn preadv 232may return one of the following errors: 233.Bl -tag -width Er 234.It Bq Er EINVAL 235The 236.Fa iovcnt 237argument 238was less than or equal to 0, or greater than 239.Dv IOV_MAX . 240.It Bq Er EINVAL 241One of the 242.Fa iov_len 243values in the 244.Fa iov 245array was negative. 246.It Bq Er EINVAL 247The sum of the 248.Fa iov_len 249values in the 250.Fa iov 251array overflowed a 32-bit integer. 252.It Bq Er EFAULT 253Part of the 254.Fa iov 255array points outside the process's allocated address space. 256.El 257.Pp 258The 259.Fn pread 260and 261.Fn preadv 262system calls may also return the following errors: 263.Bl -tag -width Er 264.It Bq Er EINVAL 265The 266.Fa offset 267value was negative. 268.It Bq Er ESPIPE 269The file descriptor is associated with a pipe, socket, or FIFO. 270.El 271.Sh SEE ALSO 272.Xr dup 2 , 273.Xr fcntl 2 , 274.Xr getdirentries 2 , 275.Xr open 2 , 276.Xr pipe 2 , 277.Xr select 2 , 278.Xr socket 2 , 279.Xr socketpair 2 , 280.Xr fread 3 , 281.Xr readdir 3 282.Sh STANDARDS 283The 284.Fn read 285system call is expected to conform to 286.St -p1003.1-90 . 287The 288.Fn readv 289and 290.Fn pread 291system calls are expected to conform to 292.St -xpg4.2 . 293.Sh HISTORY 294The 295.Fn preadv 296system call appeared in 297.Fx 6.0 . 298The 299.Fn pread 300function appeared in 301.At V.4 . 302The 303.Fn readv 304system call appeared in 305.Bx 4.2 . 306The 307.Fn read 308function appeared in 309.At v1 . 310