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