]> git.saurik.com Git - apple/xnu.git/blame_incremental - bsd/man/man2/read.2
xnu-3248.60.10.tar.gz
[apple/xnu.git] / bsd / man / man2 / read.2
... / ...
CommitLineData
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.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\" notice, this list of conditions and the following disclaimer in the
11.\" documentation and/or other materials provided with the distribution.
12.\" 3. All advertising materials mentioning features or use of this software
13.\" must display the following acknowledgement:
14.\" This product includes software developed by the University of
15.\" California, Berkeley and its contributors.
16.\" 4. Neither the name of the University nor the names of its contributors
17.\" may be used to endorse or promote products derived from this software
18.\" without specific prior written permission.
19.\"
20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
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: src/lib/libc/sys/read.2,v 1.9.2.6 2001/12/14 18:34:01 ru Exp $
34.\"
35.Dd February 26, 1994
36.Dt READ 2
37.Os
38.Sh NAME
39.Nm pread ,
40.Nm read ,
41.Nm readv
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.Fo pread
51.Fa "int d"
52.Fa "void *buf"
53.Fa "size_t nbyte"
54.Fa "off_t offset"
55.Fc
56.Ft ssize_t
57.Fo read
58.Fa "int fildes"
59.Fa "void *buf"
60.Fa "size_t nbyte"
61.Fc
62.Ft ssize_t
63.Fo readv
64.Fa "int d"
65.Fa "const struct iovec *iov"
66.Fa "int iovcnt"
67.Fc
68.Sh DESCRIPTION
69.Fn Read
70attempts to read
71.Fa nbyte
72bytes of data from the object referenced by the descriptor
73.Fa fildes
74into the buffer pointed to by
75.Fa buf .
76.Fn Readv
77performs the same action,
78but scatters the input data into the
79.Fa iovcnt
80buffers specified by the members of the
81.Fa iov
82array: iov[0], iov[1], ..., iov[iovcnt\|\-\|1].
83.Fn Pread
84performs the same function,
85but reads from the specified position in the file
86without modifying the file pointer.
87.Pp
88For
89.Fn readv ,
90the
91.Fa iovec
92structure is defined as:
93.Pp
94.Bd -literal -offset indent -compact
95struct iovec {
96 char *iov_base; /* Base address. */
97 size_t iov_len; /* Length. */
98};
99.Ed
100.Pp
101Each
102.Fa iovec
103entry specifies the base address and length of an area
104in memory where data should be placed.
105.Fn Readv
106will always fill an area completely before proceeding
107to the next.
108.Pp
109On objects capable of seeking, the
110.Fn read
111starts at a position
112given by the pointer associated with
113.Fa fildes
114(see
115.Xr lseek 2 ) .
116Upon return from
117.Fn read ,
118the pointer is incremented by the number of bytes actually read.
119.Pp
120Objects that are not capable of seeking always read from the current
121position. The value of the pointer associated with such an
122object is undefined.
123.Pp
124Upon successful completion,
125.Fn read ,
126.Fn readv ,
127and
128.Fn pread
129return the number of bytes actually read and placed in the buffer.
130The system guarantees to read the number of bytes requested if
131the descriptor references a normal file that has that many bytes left
132before the end-of-file, but in no other case.
133.Sh RETURN VALUES
134If successful, the
135number of bytes actually read is returned.
136Upon reading end-of-file,
137zero is returned.
138Otherwise, a -1 is returned and the global variable
139.Va errno
140is set to indicate the error.
141.Sh ERRORS
142The
143.Fn pread ,
144.Fn read ,
145and
146.Fn readv
147calls
148will succeed unless:
149.Bl -tag -width Er
150.\" ===========
151.It Bq Er EAGAIN
152The file was marked for non-blocking I/O,
153and no data were ready to be read.
154.\" ===========
155.It Bq Er EBADF
156.Fa fildes
157is not a valid file or socket descriptor open for reading.
158.\" ===========
159.It Bq Er EFAULT
160.Fa Buf
161points outside the allocated address space.
162.\" ===========
163.It Bq Er EINTR
164A read from a slow device was interrupted before
165any data arrived by the delivery of a signal.
166.It Bq Er EINVAL
167The pointer associated with
168.Fa fildes
169was negative.
170.\" ===========
171.It Bq Er EIO
172An I/O error occurred while reading from the file system.
173.\" ===========
174.\" .It Bq Er EIO
175.\" The process is a member of a background process
176.\" attempting to read from its controlling terminal.
177.\" ===========
178.\" .It Bq Er EIO
179.\" The process is ignoring or blocking the SIGTTIN signal.
180.\" ===========
181.It Bq Er EIO
182The process group is orphaned.
183.\" ===========
184.It Bq Er EIO
185The file is a regular file,
186.Fa nbyte
187is greater than 0,
188the starting position is before the end-of-file,
189and the starting position is greater than or equal
190to the offset maximum established
191for the open file descriptor associated with
192.Fa fildes .
193.\" ===========
194.It Bq Er EISDIR
195An attempt is made to read a directory.
196.\" ===========
197.It Bq Er ENOBUFS
198An attempt to allocate a memory buffer fails.
199.\" ===========
200.It Bq Er ENOMEM
201Insufficient memory is available.
202.\" ===========
203.It Bq Er ENXIO
204An action is requested of a device that does not exist..
205.\" ===========
206.It Bq Er ENXIO
207A requested action cannot be performed by the device.
208.El
209.Pp
210The
211.Fn pread
212call may also return the following errors:
213.Bl -tag -width Er
214.\" ===========
215.It Bq Er EINVAL
216The specified file offset is invalid.
217.\" ===========
218.It Bq Er ESPIPE
219The file descriptor is associated with a pipe, socket, or FIFO.
220.El
221.Pp
222The
223.Fn read
224call may also return the following errors:
225.Bl -tag -width Er
226.\" ===========
227.It Bq Er ECONNRESET
228The connection is closed by the peer
229during a read attempt on a socket.
230.\" ===========
231.It Bq Er ENOTCONN
232A read is attempted on an unconnected socket.
233.\" ===========
234.It Bq Er ETIMEDOUT
235A transmission timeout occurs
236during a read attempt on a socket.
237.El
238.Pp
239The
240.Fn readv
241call may also return one of the following errors:
242.Bl -tag -width Er
243.\" ===========
244.It Bq Er EFAULT
245Part of the
246.Fa iov
247points outside the process's allocated address space.
248.\" ===========
249.It Bq Er EINVAL
250.Fa Iovcnt
251was less than or equal to 0, or greater than 16.
252.\" ===========
253.It Bq Er EINVAL
254One of the
255.Fa iov_len
256values in the
257.Fa iov
258array was negative.
259.\" ===========
260.It Bq Er EINVAL
261The sum of the
262.Fa iov_len
263values in the
264.Fa iov
265array overflowed a 32-bit integer.
266.El
267.Sh LEGACY SYNOPSIS
268.Fd #include <sys/types.h>
269.Fd #include <sys/uio.h>
270.Fd #include <unistd.h>
271.Pp
272The include files
273.In sys/types.h
274and
275.In sys/uio.h
276are necessary for all functions.
277.Sh SEE ALSO
278.Xr dup 2 ,
279.Xr fcntl 2 ,
280.Xr open 2 ,
281.Xr pipe 2 ,
282.Xr select 2 ,
283.Xr socket 2 ,
284.Xr socketpair 2 ,
285.Xr compat 5
286.Sh STANDARDS
287The
288.Fn read
289function call is expected to conform to
290.St -p1003.1-90 .
291The
292.Fn readv
293and
294.Fn pread
295functions are expected to conform to
296.St -xpg4.2 .
297.Sh HISTORY
298The
299.Fn pread
300function call
301appeared in
302.At V.4 .
303The
304.Fn readv
305function call
306appeared in
307.Bx 4.2 .
308A
309.Fn read
310function call appeared in
311.At v6 .