| read.2 (141663) | read.2 (147813) |
|---|---|
| 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. --- 16 unchanged lines hidden (view full) --- 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 | 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. --- 16 unchanged lines hidden (view full) --- 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: head/lib/libc/sys/read.2 141663 2005-02-10 20:09:01Z cperciva $ | 33.\" $FreeBSD: head/lib/libc/sys/read.2 147813 2005-07-07 18:17:55Z jhb $ |
| 34.\" 35.Dd October 16, 2004 36.Dt READ 2 37.Os 38.Sh NAME 39.Nm read , 40.Nm readv , | 34.\" 35.Dd October 16, 2004 36.Dt READ 2 37.Os 38.Sh NAME 39.Nm read , 40.Nm readv , |
| 41.Nm pread | 41.Nm pread , 42.Nm preadv |
| 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 | 43.Nd read input 44.Sh LIBRARY 45.Lb libc 46.Sh SYNOPSIS 47.In sys/types.h 48.In sys/uio.h 49.In unistd.h 50.Ft ssize_t 51.Fn read "int d" "void *buf" "size_t nbytes" 52.Ft ssize_t |
| 53.Fn pread "int d" "void *buf" "size_t nbytes" "off_t offset" 54.Ft ssize_t |
|
| 52.Fn readv "int d" "const struct iovec *iov" "int iovcnt" 53.Ft ssize_t | 55.Fn readv "int d" "const struct iovec *iov" "int iovcnt" 56.Ft ssize_t |
| 54.Fn pread "int d" "void *buf" "size_t nbytes" "off_t offset" | 57.Fn preadv "int d" "const struct iovec *iov" "int iovcnt" "off_t offset" |
| 55.Sh DESCRIPTION 56The 57.Fn read 58system call 59attempts to read 60.Fa nbytes 61of data from the object referenced by the descriptor 62.Fa d --- 5 unchanged lines hidden (view full) --- 68performs the same action, but scatters the input data 69into the 70.Fa iovcnt 71buffers specified by the members of the 72.Fa iov 73array: iov[0], iov[1], ..., iov[iovcnt\|\-\|1]. 74The 75.Fn pread | 58.Sh DESCRIPTION 59The 60.Fn read 61system call 62attempts to read 63.Fa nbytes 64of data from the object referenced by the descriptor 65.Fa d --- 5 unchanged lines hidden (view full) --- 71performs the same action, but scatters the input data 72into the 73.Fa iovcnt 74buffers specified by the members of the 75.Fa iov 76array: iov[0], iov[1], ..., iov[iovcnt\|\-\|1]. 77The 78.Fn pread |
| 76system call 77performs the same function, but reads from the specified position in | 79and 80.Fn preadv 81system calls 82perform the same functions, but read from the specified position in |
| 78the file without modifying the file pointer. 79.Pp 80For | 83the file without modifying the file pointer. 84.Pp 85For |
| 81.Fn readv , | 86.Fn readv 87and 88.Fn preadv , |
| 82the 83.Fa iovec 84structure is defined as: 85.Pp 86.Bd -literal -offset indent -compact 87struct iovec { 88 void *iov_base; /* Base address. */ 89 size_t iov_len; /* Length. */ --- 24 unchanged lines hidden (view full) --- 114Objects that are not capable of seeking always read from the current 115position. 116The value of the pointer associated with such an 117object is undefined. 118.Pp 119Upon successful completion, 120.Fn read , 121.Fn readv , | 89the 90.Fa iovec 91structure is defined as: 92.Pp 93.Bd -literal -offset indent -compact 94struct iovec { 95 void *iov_base; /* Base address. */ 96 size_t iov_len; /* Length. */ --- 24 unchanged lines hidden (view full) --- 121Objects that are not capable of seeking always read from the current 122position. 123The value of the pointer associated with such an 124object is undefined. 125.Pp 126Upon successful completion, 127.Fn read , 128.Fn readv , |
| 122and | |
| 123.Fn pread | 129.Fn pread |
| 130and 131.Fn preadv |
|
| 124return the number of bytes actually read and placed in the buffer. 125The system guarantees to read the number of bytes requested if 126the descriptor references a normal file that has that many bytes left 127before the end-of-file, but in no other case. 128.Sh RETURN VALUES 129If successful, the 130number of bytes actually read is returned. 131Upon reading end-of-file, 132zero is returned. 133Otherwise, a -1 is returned and the global variable 134.Va errno 135is set to indicate the error. 136.Sh ERRORS 137The 138.Fn read , 139.Fn readv , | 132return the number of bytes actually read and placed in the buffer. 133The system guarantees to read the number of bytes requested if 134the descriptor references a normal file that has that many bytes left 135before the end-of-file, but in no other case. 136.Sh RETURN VALUES 137If successful, the 138number of bytes actually read is returned. 139Upon reading end-of-file, 140zero is returned. 141Otherwise, a -1 is returned and the global variable 142.Va errno 143is set to indicate the error. 144.Sh ERRORS 145The 146.Fn read , 147.Fn readv , |
| 140and | |
| 141.Fn pread | 148.Fn pread |
| 149and 150.Fn preadv |
|
| 142system calls 143will succeed unless: 144.Bl -tag -width Er 145.It Bq Er EBADF 146The 147.Fa d 148argument 149is not a valid file or socket descriptor open for reading. --- 34 unchanged lines hidden (view full) --- 184The value 185.Fa nbytes 186is greater than 187.Dv INT_MAX . 188.El 189.Pp 190In addition, 191.Fn readv | 151system calls 152will succeed unless: 153.Bl -tag -width Er 154.It Bq Er EBADF 155The 156.Fa d 157argument 158is not a valid file or socket descriptor open for reading. --- 34 unchanged lines hidden (view full) --- 193The value 194.Fa nbytes 195is greater than 196.Dv INT_MAX . 197.El 198.Pp 199In addition, 200.Fn readv |
| 201and 202.Fn preadv |
|
| 192may return one of the following errors: 193.Bl -tag -width Er 194.It Bq Er EINVAL 195The 196.Fa iovcnt 197argument 198was less than or equal to 0, or greater than 199.Dv IOV_MAX . --- 12 unchanged lines hidden (view full) --- 212.It Bq Er EFAULT 213Part of the 214.Fa iov 215array points outside the process's allocated address space. 216.El 217.Pp 218The 219.Fn pread | 203may return one of the following errors: 204.Bl -tag -width Er 205.It Bq Er EINVAL 206The 207.Fa iovcnt 208argument 209was less than or equal to 0, or greater than 210.Dv IOV_MAX . --- 12 unchanged lines hidden (view full) --- 223.It Bq Er EFAULT 224Part of the 225.Fa iov 226array points outside the process's allocated address space. 227.El 228.Pp 229The 230.Fn pread |
| 220system call may also return the following errors: | 231and 232.Fn preadv 233system calls may also return the following errors: |
| 221.Bl -tag -width Er 222.It Bq Er EINVAL 223The 224.Fa offset 225value was negative. 226.It Bq Er ESPIPE 227The file descriptor is associated with a pipe, socket, or FIFO. 228.El --- 16 unchanged lines hidden (view full) --- 245The 246.Fn readv 247and 248.Fn pread 249system calls are expected to conform to 250.St -xpg4.2 . 251.Sh HISTORY 252The | 234.Bl -tag -width Er 235.It Bq Er EINVAL 236The 237.Fa offset 238value was negative. 239.It Bq Er ESPIPE 240The file descriptor is associated with a pipe, socket, or FIFO. 241.El --- 16 unchanged lines hidden (view full) --- 258The 259.Fn readv 260and 261.Fn pread 262system calls are expected to conform to 263.St -xpg4.2 . 264.Sh HISTORY 265The |
| 266.Fn preadv 267system call appeared in 268.Fx 6.0 . 269The |
|
| 253.Fn pread 254function appeared in 255.At V.4 . 256The 257.Fn readv 258system call appeared in 259.Bx 4.2 . 260The 261.Fn read 262function appeared in 263.At v6 . | 270.Fn pread 271function appeared in 272.At V.4 . 273The 274.Fn readv 275system call appeared in 276.Bx 4.2 . 277The 278.Fn read 279function appeared in 280.At v6 . |