1.\" Copyright (c) 1980, 1991 Regents of the University of California. 2.\" 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.\" from: @(#)read.2 6.7 (Berkeley) 3/10/91 33.\" $Id: read.2,v 1.5 1994/09/16 03:08:46 mycroft Exp $ 34.\" 35.Dd March 10, 1991 36.Dt READ 2 37.Os BSD 4 38.Sh NAME 39.Nm read , 40.Nm readv 41.Nd read input 42.Sh SYNOPSIS 43.Fd #include <unistd.h> 44.Fd #include <sys/types.h> 45.Fd #include <sys/uio.h> 46.Ft ssize_t 47.Fn read "int d" "void *buf" "size_t nbytes" 48.Ft int 49.Fn readv "int d" "struct iovec *iov" "int iovcnt" 50.Sh DESCRIPTION 51.Fn Read 52attempts to read 53.Fa nbytes 54of data from the object referenced by the descriptor 55.Fa d 56into the buffer pointed to by 57.Fa buf . 58.Fn Readv 59performs the same action, but scatters the input data 60into the 61.Fa iovcnt 62buffers specified by the members of the 63.Fa iov 64array: iov[0], iov[1], ..., iov[iovcnt\|\-\|1]. 65.Pp 66For 67.Fn readv , 68the 69.Fa iovec 70structure is defined as 71.Bd -literal -offset indent -compact 72struct iovec { 73 caddr_t iov_base; 74 int 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 EWOULDBLOCK 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 150.Dv {UIO_MAXIOV} . 151.It Bq Er EINVAL 152One of the 153.Fa iov_len 154values in the 155.Fa iov 156array was negative. 157.It Bq Er EINVAL 158The sum of the 159.Fa iov_len 160values in the 161.Fa iov 162array overflowed a 32-bit integer. 163.It Bq Er EFAULT 164Part of the 165.Fa iov 166points outside the process's allocated address space. 167.El 168.Sh SEE ALSO 169.Xr dup 2 , 170.Xr fcntl 2 , 171.Xr open 2 , 172.Xr pipe 2 , 173.Xr select 2 , 174.Xr socket 2 , 175.Xr socketpair 2 176.Sh STANDARDS 177The 178.Fn read 179function is expected to conform to 180.St -p1003.1-88 . 181.Sh HISTORY 182The 183.Fn readv 184function call 185appeared in 186.Bx 4.2 . 187The 188.Fn read 189function call appeared in 190.At v6 . 191