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