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