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