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: src/lib/libc/sys/read.2,v 1.9.2.6 2001/12/14 18:34:01 ru Exp $ 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.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 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 RETURN VALUES 120If successful, the 121number of bytes actually read is returned. 122Upon reading end-of-file, 123zero is returned. 124Otherwise, a -1 is returned and the global variable 125.Va errno 126is set to indicate the error. 127.Sh ERRORS 128.Fn Read , 129.Fn readv , 130and 131.Fn pread 132will succeed unless: 133.Bl -tag -width Er 134.It Bq Er EBADF 135.Fa D 136is not a valid file or socket descriptor open for reading. 137.It Bq Er EFAULT 138.Fa Buf 139points outside the allocated address space. 140.It Bq Er EIO 141An I/O error occurred while reading from the file system. 142.It Bq Er EINTR 143A read from a slow device was interrupted before 144any data arrived by the delivery of a signal. 145.It Bq Er EINVAL 146The pointer associated with 147.Fa d 148was negative. 149.It Bq Er EAGAIN 150The file was marked for non-blocking I/O, 151and no data were ready to be read. 152.El 153.Pp 154In addition, 155.Fn readv 156may return one of the following errors: 157.Bl -tag -width Er 158.It Bq Er EINVAL 159.Fa Iovcnt 160was less than or equal to 0, or greater than 16. 161.It Bq Er EINVAL 162One of the 163.Fa iov_len 164values in the 165.Fa iov 166array was negative. 167.It Bq Er EINVAL 168The sum of the 169.Fa iov_len 170values in the 171.Fa iov 172array overflowed a 32-bit integer. 173.It Bq Er EFAULT 174Part of the 175.Fa iov 176points outside the process's allocated address space. 177.El 178.Pp 179The 180.Fn pread 181call may also return the following errors: 182.Bl -tag -width Er 183.It Bq Er EINVAL 184The specified file offset is invalid. 185.It Bq Er ESPIPE 186The file descriptor is associated with a pipe, socket, or FIFO. 187.El 188.Sh SEE ALSO 189.Xr dup 2 , 190.Xr fcntl 2 , 191.Xr open 2 , 192.Xr pipe 2 , 193.Xr select 2 , 194.Xr socket 2 , 195.Xr socketpair 2 196.Sh STANDARDS 197The 198.Fn read 199function call is expected to conform to 200.St -p1003.1-90 . 201The 202.Fn readv 203and 204.Fn pread 205functions are expected to conform to 206.St -xpg4.2 . 207.Sh HISTORY 208The 209.Fn pread 210function call 211appeared in 212.At V.4 . 213The 214.Fn readv 215function call 216appeared in 217.Bx 4.2 . 218A 219.Fn read 220function call appeared in 221.At v6 . 222