| @@ -1,275 +1,275 @@ | | | @@ -1,275 +1,275 @@ |
1 | .\" $NetBSD: read.2,v 1.38 2019/08/07 19:13:49 wiz Exp $ | | 1 | .\" $NetBSD: read.2,v 1.39 2019/09/02 00:00:25 sevan Exp $ |
2 | .\" | | 2 | .\" |
3 | .\" Copyright (c) 1980, 1991, 1993 | | 3 | .\" Copyright (c) 1980, 1991, 1993 |
4 | .\" The Regents of the University of California. All rights reserved. | | 4 | .\" The Regents of the University of California. All rights reserved. |
5 | .\" | | 5 | .\" |
6 | .\" Redistribution and use in source and binary forms, with or without | | 6 | .\" Redistribution and use in source and binary forms, with or without |
7 | .\" modification, are permitted provided that the following conditions | | 7 | .\" modification, are permitted provided that the following conditions |
8 | .\" are met: | | 8 | .\" are met: |
9 | .\" 1. Redistributions of source code must retain the above copyright | | 9 | .\" 1. Redistributions of source code must retain the above copyright |
10 | .\" notice, this list of conditions and the following disclaimer. | | 10 | .\" notice, this list of conditions and the following disclaimer. |
11 | .\" 2. Redistributions in binary form must reproduce the above copyright | | 11 | .\" 2. Redistributions in binary form must reproduce the above copyright |
12 | .\" notice, this list of conditions and the following disclaimer in the | | 12 | .\" notice, this list of conditions and the following disclaimer in the |
13 | .\" documentation and/or other materials provided with the distribution. | | 13 | .\" documentation and/or other materials provided with the distribution. |
14 | .\" 3. Neither the name of the University nor the names of its contributors | | 14 | .\" 3. Neither the name of the University nor the names of its contributors |
15 | .\" may be used to endorse or promote products derived from this software | | 15 | .\" may be used to endorse or promote products derived from this software |
16 | .\" without specific prior written permission. | | 16 | .\" without specific prior written permission. |
17 | .\" | | 17 | .\" |
18 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND | | 18 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND |
19 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | | 19 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
20 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | | 20 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
21 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | | 21 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE |
22 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | | 22 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL |
23 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | | 23 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS |
24 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | | 24 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) |
25 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | | 25 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT |
26 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | | 26 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY |
27 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | | 27 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF |
28 | .\" SUCH DAMAGE. | | 28 | .\" SUCH DAMAGE. |
29 | .\" | | 29 | .\" |
30 | .\" @(#)read.2 8.4 (Berkeley) 2/26/94 | | 30 | .\" @(#)read.2 8.4 (Berkeley) 2/26/94 |
31 | .\" | | 31 | .\" |
32 | .Dd August 7, 2019 | | 32 | .Dd September 2, 2019 |
33 | .Dt READ 2 | | 33 | .Dt READ 2 |
34 | .Os | | 34 | .Os |
35 | .Sh NAME | | 35 | .Sh NAME |
36 | .Nm read , | | 36 | .Nm read , |
37 | .Nm readv , | | 37 | .Nm readv , |
38 | .Nm pread , | | 38 | .Nm pread , |
39 | .Nm preadv | | 39 | .Nm preadv |
40 | .Nd read input | | 40 | .Nd read input |
41 | .Sh LIBRARY | | 41 | .Sh LIBRARY |
42 | .Lb libc | | 42 | .Lb libc |
43 | .Sh SYNOPSIS | | 43 | .Sh SYNOPSIS |
44 | .In unistd.h | | 44 | .In unistd.h |
45 | .Ft ssize_t | | 45 | .Ft ssize_t |
46 | .Fn read "int d" "void *buf" "size_t nbytes" | | 46 | .Fn read "int d" "void *buf" "size_t nbytes" |
47 | .Ft ssize_t | | 47 | .Ft ssize_t |
48 | .Fn pread "int d" "void *buf" "size_t nbytes" "off_t offset" | | 48 | .Fn pread "int d" "void *buf" "size_t nbytes" "off_t offset" |
49 | .In sys/uio.h | | 49 | .In sys/uio.h |
50 | .Ft ssize_t | | 50 | .Ft ssize_t |
51 | .Fn readv "int d" "const struct iovec *iov" "int iovcnt" | | 51 | .Fn readv "int d" "const struct iovec *iov" "int iovcnt" |
52 | .Ft ssize_t | | 52 | .Ft ssize_t |
53 | .Fn preadv "int d" "const struct iovec *iov" "int iovcnt" "off_t offset" | | 53 | .Fn preadv "int d" "const struct iovec *iov" "int iovcnt" "off_t offset" |
54 | .Sh DESCRIPTION | | 54 | .Sh DESCRIPTION |
55 | .Fn read | | 55 | .Fn read |
56 | attempts to read | | 56 | attempts to read |
57 | .Fa nbytes | | 57 | .Fa nbytes |
58 | of data from the object referenced by the descriptor | | 58 | of data from the object referenced by the descriptor |
59 | .Fa d | | 59 | .Fa d |
60 | into the buffer pointed to by | | 60 | into the buffer pointed to by |
61 | .Fa buf . | | 61 | .Fa buf . |
62 | .Fn readv | | 62 | .Fn readv |
63 | performs the same action, but scatters the input data | | 63 | performs the same action, but scatters the input data |
64 | into the | | 64 | into the |
65 | .Fa iovcnt | | 65 | .Fa iovcnt |
66 | buffers specified by the members of the | | 66 | buffers specified by the members of the |
67 | .Fa iov | | 67 | .Fa iov |
68 | array: iov[0], iov[1], ..., iov[iovcnt\|\-\|1]. | | 68 | array: iov[0], iov[1], ..., iov[iovcnt\|\-\|1]. |
69 | .Fn pread | | 69 | .Fn pread |
70 | and | | 70 | and |
71 | .Fn preadv | | 71 | .Fn preadv |
72 | perform the same functions, but read from the specified position in | | 72 | perform the same functions, but read from the specified position in |
73 | the file without modifying the file pointer. | | 73 | the file without modifying the file pointer. |
74 | .Pp | | 74 | .Pp |
75 | For | | 75 | For |
76 | .Fn readv | | 76 | .Fn readv |
77 | and | | 77 | and |
78 | .Fn preadv , | | 78 | .Fn preadv , |
79 | the | | 79 | the |
80 | .Fa iovec | | 80 | .Fa iovec |
81 | structure is defined as: | | 81 | structure is defined as: |
82 | .Pp | | 82 | .Pp |
83 | .Bd -literal -offset indent -compact | | 83 | .Bd -literal -offset indent -compact |
84 | struct iovec { | | 84 | struct iovec { |
85 | void *iov_base; | | 85 | void *iov_base; |
86 | size_t iov_len; | | 86 | size_t iov_len; |
87 | }; | | 87 | }; |
88 | .Ed | | 88 | .Ed |
89 | .Pp | | 89 | .Pp |
90 | Each | | 90 | Each |
91 | .Fa iovec | | 91 | .Fa iovec |
92 | entry specifies the base address and length of an area | | 92 | entry specifies the base address and length of an area |
93 | in memory where data should be placed. | | 93 | in memory where data should be placed. |
94 | .Fn readv | | 94 | .Fn readv |
95 | will always fill an area completely before proceeding | | 95 | will always fill an area completely before proceeding |
96 | to the next. | | 96 | to the next. |
97 | .Pp | | 97 | .Pp |
98 | On objects capable of seeking, the | | 98 | On objects capable of seeking, the |
99 | .Fn read | | 99 | .Fn read |
100 | starts at a position | | 100 | starts at a position |
101 | given by the file pointer associated with | | 101 | given by the file pointer associated with |
102 | .Fa d | | 102 | .Fa d |
103 | (see | | 103 | (see |
104 | .Xr lseek 2 ) . | | 104 | .Xr lseek 2 ) . |
105 | Upon return from | | 105 | Upon return from |
106 | .Fn read , | | 106 | .Fn read , |
107 | the file pointer is incremented by the number of bytes actually read. | | 107 | the file pointer is incremented by the number of bytes actually read. |
108 | .Pp | | 108 | .Pp |
109 | Objects that are not capable of seeking always read from the current | | 109 | Objects that are not capable of seeking always read from the current |
110 | position. | | 110 | position. |
111 | The value of the file pointer associated with such an object is undefined. | | 111 | The value of the file pointer associated with such an object is undefined. |
112 | .Pp | | 112 | .Pp |
113 | Upon successful completion, | | 113 | Upon successful completion, |
114 | .Fn read , | | 114 | .Fn read , |
115 | .Fn readv , | | 115 | .Fn readv , |
116 | .Fn pread , | | 116 | .Fn pread , |
117 | and | | 117 | and |
118 | .Fn preadv | | 118 | .Fn preadv |
119 | return the number of bytes actually read and placed in the buffer. | | 119 | return the number of bytes actually read and placed in the buffer. |
120 | The system guarantees to read the number of bytes requested if | | 120 | The system guarantees to read the number of bytes requested if |
121 | the descriptor references a normal file that has that many bytes left | | 121 | the descriptor references a normal file that has that many bytes left |
122 | before the end-of-file, but in no other case. | | 122 | before the end-of-file, but in no other case. |
123 | .Sh RETURN VALUES | | 123 | .Sh RETURN VALUES |
124 | If successful, the | | 124 | If successful, the |
125 | number of bytes actually read is returned. | | 125 | number of bytes actually read is returned. |
126 | Upon reading end-of-file, zero is returned. | | 126 | Upon reading end-of-file, zero is returned. |
127 | Otherwise, a \-1 is returned and the global variable | | 127 | Otherwise, a \-1 is returned and the global variable |
128 | .Va errno | | 128 | .Va errno |
129 | is set to indicate the error. | | 129 | is set to indicate the error. |
130 | .Sh ERRORS | | 130 | .Sh ERRORS |
131 | .Fn read , | | 131 | .Fn read , |
132 | .Fn readv , | | 132 | .Fn readv , |
133 | .Fn pread , | | 133 | .Fn pread , |
134 | and | | 134 | and |
135 | .Fn preadv | | 135 | .Fn preadv |
136 | will succeed unless: | | 136 | will succeed unless: |
137 | .Bl -tag -width Er | | 137 | .Bl -tag -width Er |
138 | .It Bq Er EAGAIN | | 138 | .It Bq Er EAGAIN |
139 | The file was marked for non-blocking I/O, | | 139 | The file was marked for non-blocking I/O, |
140 | and no data were ready to be read. | | 140 | and no data were ready to be read. |
141 | .It Bq Er EBADF | | 141 | .It Bq Er EBADF |
142 | .Fa d | | 142 | .Fa d |
143 | is not a valid file or socket descriptor open for reading. | | 143 | is not a valid file or socket descriptor open for reading. |
144 | .It Bq Er EFAULT | | 144 | .It Bq Er EFAULT |
145 | .Fa buf | | 145 | .Fa buf |
146 | points outside the allocated address space. | | 146 | points outside the allocated address space. |
147 | .It Bq Er EINTR | | 147 | .It Bq Er EINTR |
148 | A read from a slow device | | 148 | A read from a slow device |
149 | (i.e. one that might block for an arbitrary amount of time) | | 149 | (i.e. one that might block for an arbitrary amount of time) |
150 | was interrupted by the delivery of a signal | | 150 | was interrupted by the delivery of a signal |
151 | before any data arrived. | | 151 | before any data arrived. |
152 | See | | 152 | See |
153 | .Xr sigaction 2 | | 153 | .Xr sigaction 2 |
154 | for more information on the interaction between signals and system | | 154 | for more information on the interaction between signals and system |
155 | calls. | | 155 | calls. |
156 | .It Bq Er EINVAL | | 156 | .It Bq Er EINVAL |
157 | The file pointer associated with | | 157 | The file pointer associated with |
158 | .Fa d | | 158 | .Fa d |
159 | was negative; or | | 159 | was negative; or |
160 | the total length of the I/O is more than can be expressed by the ssize_t | | 160 | the total length of the I/O is more than can be expressed by the ssize_t |
161 | return value. | | 161 | return value. |
162 | .It Bq Er EIO | | 162 | .It Bq Er EIO |
163 | An I/O error occurred while reading from the file system. | | 163 | An I/O error occurred while reading from the file system. |
164 | .It Bq Er EISDIR | | 164 | .It Bq Er EISDIR |
165 | .Fa d | | 165 | .Fa d |
166 | refers to a directory and the implementation does not allow the directory | | 166 | refers to a directory and the implementation does not allow the directory |
167 | to be read using | | 167 | to be read using |
168 | .Fn read | | 168 | .Fn read |
169 | or | | 169 | or |
170 | .Fn pread . | | 170 | .Fn pread . |
171 | The | | 171 | The |
172 | .Fn readdir | | 172 | .Fn readdir |
173 | function should be used instead. | | 173 | function should be used instead. |
174 | .It Bq Er ENOBUFS | | 174 | .It Bq Er ENOBUFS |
175 | A message was not delivered because it would have overflowed the buffer. | | 175 | A message was not delivered because it would have overflowed the buffer. |
176 | .El | | 176 | .El |
177 | .Pp | | 177 | .Pp |
178 | In addition, | | 178 | In addition, |
179 | .Fn readv | | 179 | .Fn readv |
180 | and | | 180 | and |
181 | .Fn preadv | | 181 | .Fn preadv |
182 | may return one of the following errors: | | 182 | may return one of the following errors: |
183 | .Bl -tag -width Er | | 183 | .Bl -tag -width Er |
184 | .It Bq Er EFAULT | | 184 | .It Bq Er EFAULT |
185 | Part of the | | 185 | Part of the |
186 | .Fa iov | | 186 | .Fa iov |
187 | points outside the process's allocated address space. | | 187 | points outside the process's allocated address space. |
188 | .It Bq Er EINVAL | | 188 | .It Bq Er EINVAL |
189 | .Fa iovcnt | | 189 | .Fa iovcnt |
190 | was less than or equal to 0, or greater than | | 190 | was less than or equal to 0, or greater than |
191 | .Brq Dv IOV_MAX ; | | 191 | .Brq Dv IOV_MAX ; |
192 | or one of the | | 192 | or one of the |
193 | .Fa iov_len | | 193 | .Fa iov_len |
194 | values in the | | 194 | values in the |
195 | .Fa iov | | 195 | .Fa iov |
196 | array was negative; or | | 196 | array was negative; or |
197 | the sum of the | | 197 | the sum of the |
198 | .Fa iov_len | | 198 | .Fa iov_len |
199 | values in the | | 199 | values in the |
200 | .Fa iov | | 200 | .Fa iov |
201 | array overflowed a 32-bit integer. | | 201 | array overflowed a 32-bit integer. |
202 | .El | | 202 | .El |
203 | .Pp | | 203 | .Pp |
204 | The | | 204 | The |
205 | .Fn pread | | 205 | .Fn pread |
206 | and | | 206 | and |
207 | .Fn preadv | | 207 | .Fn preadv |
208 | calls may also return the following errors: | | 208 | calls may also return the following errors: |
209 | .Bl -tag -width Er | | 209 | .Bl -tag -width Er |
210 | .It Bq Er EINVAL | | 210 | .It Bq Er EINVAL |
211 | The specified file offset is invalid. | | 211 | The specified file offset is invalid. |
212 | .It Bq Er ESPIPE | | 212 | .It Bq Er ESPIPE |
213 | The file descriptor is associated with a pipe, socket, or FIFO. | | 213 | The file descriptor is associated with a pipe, socket, or FIFO. |
214 | .El | | 214 | .El |
215 | .Sh SEE ALSO | | 215 | .Sh SEE ALSO |
216 | .Xr dup 2 , | | 216 | .Xr dup 2 , |
217 | .Xr fcntl 2 , | | 217 | .Xr fcntl 2 , |
218 | .Xr open 2 , | | 218 | .Xr open 2 , |
219 | .Xr pipe 2 , | | 219 | .Xr pipe 2 , |
220 | .Xr poll 2 , | | 220 | .Xr poll 2 , |
221 | .Xr select 2 , | | 221 | .Xr select 2 , |
222 | .Xr sigaction 2 , | | 222 | .Xr sigaction 2 , |
223 | .Xr socket 2 , | | 223 | .Xr socket 2 , |
224 | .Xr socketpair 2 | | 224 | .Xr socketpair 2 |
225 | .Sh STANDARDS | | 225 | .Sh STANDARDS |
226 | The | | 226 | The |
227 | .Fn read | | 227 | .Fn read |
228 | function conforms to | | 228 | function conforms to |
229 | .St -p1003.1-90 . | | 229 | .St -p1003.1-90 . |
230 | The | | 230 | The |
231 | .Fn readv | | 231 | .Fn readv |
232 | and | | 232 | and |
233 | .Fn pread | | 233 | .Fn pread |
234 | functions conform to | | 234 | functions conform to |
235 | .St -xpg4.2 . | | 235 | .St -xpg4.2 . |
236 | .Sh HISTORY | | 236 | .Sh HISTORY |
237 | The | | 237 | The |
238 | .Fn preadv | | 238 | .Fn preadv |
239 | function call | | 239 | function call |
240 | appeared in | | 240 | appeared in |
241 | .Nx 1.4 . | | 241 | .Nx 1.4 . |
242 | The | | 242 | The |
243 | .Fn pread | | 243 | .Fn pread |
244 | function call | | 244 | function call |
245 | appeared in | | 245 | appeared in |
246 | .At V.4 . | | 246 | .At V.4 . |
247 | The | | 247 | The |
248 | .Fn readv | | 248 | .Fn readv |
249 | function call | | 249 | function call |
250 | appeared in | | 250 | appeared in |
251 | .Bx 4.2 . | | 251 | .Bx 4.2 . |
252 | The | | 252 | The |
253 | .Fn read | | 253 | .Fn read |
254 | function call appeared in | | 254 | function call appeared in |
255 | .At v2 . | | 255 | .At v1 . |
256 | .Sh CAVEATS | | 256 | .Sh CAVEATS |
257 | Error checks should explicitly test for \-1. | | 257 | Error checks should explicitly test for \-1. |
258 | Code such as | | 258 | Code such as |
259 | .Bd -literal | | 259 | .Bd -literal |
260 | while ((nr = read(fd, buf, sizeof(buf))) > 0) | | 260 | while ((nr = read(fd, buf, sizeof(buf))) > 0) |
261 | .Ed | | 261 | .Ed |
262 | .Pp | | 262 | .Pp |
263 | is not maximally portable, as some platforms allow for | | 263 | is not maximally portable, as some platforms allow for |
264 | .Va nbytes | | 264 | .Va nbytes |
265 | to range between | | 265 | to range between |
266 | .Dv SSIZE_MAX | | 266 | .Dv SSIZE_MAX |
267 | and | | 267 | and |
268 | .Dv SIZE_MAX | | 268 | .Dv SIZE_MAX |
269 | \- 2, in which case the return value of an error-free | | 269 | \- 2, in which case the return value of an error-free |
270 | .Fn read | | 270 | .Fn read |
271 | may appear as a negative number distinct from \-1. | | 271 | may appear as a negative number distinct from \-1. |
272 | Proper loops should use | | 272 | Proper loops should use |
273 | .Bd -literal | | 273 | .Bd -literal |
274 | while ((nr = read(fd, buf, sizeof(buf))) != -1 && nr != 0) | | 274 | while ((nr = read(fd, buf, sizeof(buf))) != -1 && nr != 0) |
275 | .Ed | | 275 | .Ed |