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