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