1.\" Copyright (c) 1980, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" %sccs.include.redist.man% 5.\" 6.\" @(#)read.2 8.4 (Berkeley) 02/26/94 7.\" 8.Dd 9.Dt READ 2 10.Os BSD 4 11.Sh NAME 12.Nm read , 13.Nm readv 14.Nd read input 15.Sh SYNOPSIS 16.Fd #include <sys/types.h> 17.Fd #include <sys/uio.h> 18.Fd #include <unistd.h> 19.Ft ssize_t 20.Fn read "int d" "void *buf" "size_t nbytes" 21.Ft ssize_t 22.Fn readv "int d" "const struct iovec *iov" "int iovcnt" 23.Sh DESCRIPTION 24.Fn Read 25attempts to read 26.Fa nbytes 27of data from the object referenced by the descriptor 28.Fa d 29into the buffer pointed to by 30.Fa buf . 31.Fn Readv 32performs the same action, but scatters the input data 33into the 34.Fa iovcnt 35buffers specified by the members of the 36.Fa iov 37array: iov[0], iov[1], ..., iov[iovcnt\|\-\|1]. 38.Pp 39For 40.Fn readv , 41the 42.Fa iovec 43structure is defined as: 44.Pp 45.Bd -literal -offset indent -compact 46struct iovec { 47 void *iov_base; 48 size_t iov_len; 49}; 50.Ed 51.Pp 52Each 53.Fa iovec 54entry specifies the base address and length of an area 55in memory where data should be placed. 56.Fn Readv 57will always fill an area completely before proceeding 58to the next. 59.Pp 60On objects capable of seeking, the 61.Fn read 62starts at a position 63given by the pointer associated with 64.Fa d 65(see 66.Xr lseek 2 ) . 67Upon return from 68.Fn read , 69the pointer is incremented by the number of bytes actually read. 70.Pp 71Objects that are not capable of seeking always read from the current 72position. The value of the pointer associated with such an 73object is undefined. 74.Pp 75Upon successful completion, 76.Fn read 77and 78.Fn readv 79return the number of bytes actually read and placed in the buffer. 80The system guarantees to read the number of bytes requested if 81the descriptor references a normal file that has that many bytes left 82before the end-of-file, but in no other case. 83.Pp 84.Sh RETURN VALUES 85If successful, the 86number of bytes actually read is returned. Upon reading end-of-file, 87zero is returned. 88Otherwise, a -1 is returned and the global variable 89.Va errno 90is set to indicate the error. 91.Sh ERRORS 92.Fn Read 93and 94.Fn readv 95will succeed unless: 96.Bl -tag -width Er 97.It Bq Er EBADF 98.Fa D 99is not a valid file or socket descriptor open for reading. 100.It Bq Er EFAULT 101.Fa Buf 102points outside the allocated address space. 103.It Bq Er EIO 104An I/O error occurred while reading from the file system. 105.It Bq Er EINTR 106A read from a slow device was interrupted before 107any data arrived by the delivery of a signal. 108.It Bq Er EINVAL 109The pointer associated with 110.Fa d 111was negative. 112.It Bq Er EAGAIN 113The file was marked for non-blocking I/O, 114and no data were ready to be read. 115.El 116.Pp 117In addition, 118.Fn readv 119may return one of the following errors: 120.Bl -tag -width Er 121.It Bq Er EINVAL 122.Fa Iovcnt 123was less than or equal to 0, or greater than 16. 124.It Bq Er EINVAL 125One of the 126.Fa iov_len 127values in the 128.Fa iov 129array was negative. 130.It Bq Er EINVAL 131The sum of the 132.Fa iov_len 133values in the 134.Fa iov 135array overflowed a 32-bit integer. 136.It Bq Er EFAULT 137Part of the 138.Fa iov 139points outside the process's allocated address space. 140.El 141.Sh SEE ALSO 142.Xr dup 2 , 143.Xr fcntl 2 , 144.Xr open 2 , 145.Xr pipe 2 , 146.Xr select 2 , 147.Xr socket 2 , 148.Xr socketpair 2 149.Sh STANDARDS 150.Fn Read 151is expected to conform to IEEE Std 1003.1-1988 152.Pq Dq Tn POSIX . 153.Sh HISTORY 154The 155.Fn readv 156function call 157appeared in 158.Bx 4.2 . 159A 160.Nm read 161function call 162appeared in 163Version 6 AT&T UNIX. 164