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 February 26, 1994 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.Fd #include <sys/types.h> 47.Fd #include <sys/uio.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 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 56.Fn Read 57attempts to read 58.Fa nbytes 59of data from the object referenced by the descriptor 60.Fa d 61into the buffer pointed to by 62.Fa buf . 63.Fn Readv 64performs the same action, but scatters the input data 65into 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 71performs the same function, but reads from the specified position in 72the file without modifying the file pointer. 73.Pp 74For 75.Fn readv , 76the 77.Fa iovec 78structure is defined as: 79.Pp 80.Bd -literal -offset indent -compact 81struct iovec { 82 char *iov_base; /* Base address. */ 83 size_t iov_len; /* Length. */ 84}; 85.Ed 86.Pp 87Each 88.Fa iovec 89entry specifies the base address and length of an area 90in memory where data should be placed. 91.Fn Readv 92will always fill an area completely before proceeding 93to the next. 94.Pp 95On objects capable of seeking, the 96.Fn read 97starts at a position 98given by the pointer associated with 99.Fa d 100(see 101.Xr lseek 2 ) . 102Upon return from 103.Fn read , 104the pointer is incremented by the number of bytes actually read. 105.Pp 106Objects that are not capable of seeking always read from the current 107position. The value of the pointer associated with such an 108object is undefined. 109.Pp 110Upon successful completion, 111.Fn read , 112.Fn readv , 113and 114.Fn pread 115return the number of bytes actually read and placed in the buffer. 116The system guarantees to read the number of bytes requested if 117the descriptor references a normal file that has that many bytes left 118before the end-of-file, but in no other case. 119.Sh IMPLEMENTATION NOTES 120In the non-threaded library 121.Fn read 122is implemented as the 123.Va read 124syscall. 125.Pp 126In the threaded library, the 127.Va read 128syscall is assembled to 129.Fn _thread_sys_read 130and 131.Fn read 132is implemented as a function which locks 133.Fa d 134for read, then calls 135.Fn _thread_sys_read . 136If the call to 137.Fn _thread_sys_read 138would block, a context switch is performed. 139Before returning, 140.Fn read 141unlocks 142.Fa d . 143.Pp 144In the non-threaded library 145.Fn readv 146is implemented as the 147.Va readv 148syscall. 149.Pp 150In the threaded library, the 151.Va readv 152syscall is assembled to 153.Fn _thread_sys_readv 154and 155.Fn readv 156is implemented as a function which locks 157.Fa d 158for read, then calls 159.Fn _thread_sys_readv . 160If the call to 161.Fn _thread_sys_readv 162would block, a context switch is performed. 163Before returning, 164.Fn readv 165unlocks 166.Fa d . 167.Sh RETURN VALUES 168If successful, the 169number of bytes actually read is returned. 170Upon reading end-of-file, 171zero is returned. 172Otherwise, a -1 is returned and the global variable 173.Va errno 174is set to indicate the error. 175.Sh ERRORS 176.Fn Read , 177.Fn readv , 178and 179.Fn pread 180will succeed unless: 181.Bl -tag -width Er 182.It Bq Er EBADF 183.Fa D 184is not a valid file or socket descriptor open for reading. 185.It Bq Er EFAULT 186.Fa Buf 187points outside the allocated address space. 188.It Bq Er EIO 189An I/O error occurred while reading from the file system. 190.It Bq Er EINTR 191A read from a slow device was interrupted before 192any data arrived by the delivery of a signal. 193.It Bq Er EINVAL 194The pointer associated with 195.Fa d 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.El 201.Pp 202In addition, 203.Fn readv 204may return one of the following errors: 205.Bl -tag -width Er 206.It Bq Er EINVAL 207.Fa Iovcnt 208was less than or equal to 0, or greater than 16. 209.It Bq Er EINVAL 210One of the 211.Fa iov_len 212values in the 213.Fa iov 214array was negative. 215.It Bq Er EINVAL 216The sum of the 217.Fa iov_len 218values in the 219.Fa iov 220array overflowed a 32-bit integer. 221.It Bq Er EFAULT 222Part of the 223.Fa iov 224points outside the process's allocated address space. 225.El 226.Pp 227The 228.Fn pread 229call may also return the following errors: 230.Bl -tag -width Er 231.It Bq Er EINVAL 232The specified file offset is invalid. 233.It Bq Er ESPIPE 234The file descriptor is associated with a pipe, socket, or FIFO. 235.El 236.Sh SEE ALSO 237.Xr dup 2 , 238.Xr fcntl 2 , 239.Xr open 2 , 240.Xr pipe 2 , 241.Xr select 2 , 242.Xr socket 2 , 243.Xr socketpair 2 244.Sh STANDARDS 245The 246.Fn read 247function call is expected to conform to 248.St -p1003.1-90 . 249The 250.Fn readv 251and 252.Fn pread 253functions are expected to conform to 254.St -xpg4.2 . 255.Sh HISTORY 256The 257.Fn pread 258function call 259appeared in 260.At V.4 . 261The 262.Fn readv 263function call 264appeared in 265.Bx 4.2 . 266A 267.Fn read 268function call appeared in 269.At v6 . 270