xref: /xnu-8019.80.24/bsd/man/man2/read.2 (revision a325d9c4a84054e40bbe985afedcb50ab80993ea) 
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 June 3, 2021
36.Dt READ 2
37.Os
38.Sh NAME
39.Nm pread ,
40.Nm read ,
41.Nm preadv ,
42.Nm readv
43.Nd read input
44.Sh LIBRARY
45.Lb libc
46.Sh SYNOPSIS
47.In sys/types.h
48.In sys/uio.h
49.In unistd.h
50.Ft ssize_t
51.Fo pread
52.Fa "int d"
53.Fa "void *buf"
54.Fa "size_t nbyte"
55.Fa "off_t offset"
56.Fc
57.Ft ssize_t
58.Fo read
59.Fa "int fildes"
60.Fa "void *buf"
61.Fa "size_t nbyte"
62.Fc
63.Ft ssize_t
64.Fo preadv
65.Fa "int d"
66.Fa "const struct iovec *iov"
67.Fa "int iovcnt"
68.Fa "off_t offset"
69.Fc
70.Ft ssize_t
71.Fo readv
72.Fa "int d"
73.Fa "const struct iovec *iov"
74.Fa "int iovcnt"
75.Fc
76.Sh DESCRIPTION
77.Fn read
78attempts to read
79.Fa nbyte
80bytes of data from the object referenced by the descriptor
81.Fa fildes
82into the buffer pointed to by
83.Fa buf .
84.Fn readv
85performs the same action,
86but scatters the input data into the
87.Fa iovcnt
88buffers specified by the members of the
89.Fa iov
90array: iov[0], iov[1], ..., iov[iovcnt\|\-\|1].
91.Fn pread
92and
93.Fn preadv
94perform the same functions,
95but read from the specified position in the file
96without modifying the file pointer.
97.Pp
98For
99.Fn readv
100and
101.Fn preadv ,
102the
103.Fa iovec
104structure is defined as:
105.Pp
106.Bd -literal -offset indent -compact
107struct iovec {
108	char   *iov_base;  /* Base address. */
109	size_t iov_len;    /* Length. */
110};
111.Ed
112.Pp
113Each
114.Fa iovec
115entry specifies the base address and length of an area
116in memory where data should be placed.
117.Fn readv
118and
119.Fn preadv
120will always fill an area completely before proceeding
121to the next.
122.Pp
123On objects capable of seeking, the
124.Fn read
125starts at a position
126given by the pointer associated with
127.Fa fildes
128(see
129.Xr lseek 2 ) .
130Upon return from
131.Fn read ,
132the pointer is incremented by the number of bytes actually read.
133.Pp
134Objects that are not capable of seeking always read from the current
135position.  The value of the pointer associated with such an
136object is undefined.
137.Pp
138Upon successful completion,
139.Fn read ,
140.Fn readv ,
141.Fn pread ,
142and
143.Fn preadv
144return the number of bytes actually read and placed in the buffer.
145The system guarantees to read the number of bytes requested if
146the descriptor references a normal file that has that many bytes left
147before the end-of-file, but in no other case.
148.Sh RETURN VALUES
149If successful, the
150number of bytes actually read is returned.
151Upon reading end-of-file,
152zero is returned.
153Otherwise, a -1 is returned and the global variable
154.Va errno
155is set to indicate the error.
156.Sh ERRORS
157The
158.Fn read ,
159.Fn readv ,
160.Fn pread ,
161and
162.Fn preadv
163calls
164will succeed unless:
165.Bl -tag -width Er
166.\" ===========
167.It Bq Er EAGAIN
168The file was marked for non-blocking I/O,
169and no data were ready to be read.
170.\" ===========
171.It Bq Er EBADF
172.Fa fildes
173is not a valid file or socket descriptor open for reading.
174.\" ===========
175.It Bq Er EFAULT
176.Fa Buf
177points outside the allocated address space.
178.\" ===========
179.It Bq Er EINTR
180A read from a slow device was interrupted before
181any data arrived by the delivery of a signal.
182.It Bq Er EINVAL
183The pointer associated with
184.Fa fildes
185was negative.
186.\" ===========
187.It Bq Er EIO
188An I/O error occurred while reading from the file system.
189.\" ===========
190.\" .It Bq Er EIO
191.\" The process is a member of a background process
192.\" attempting to read from its controlling terminal.
193.\" ===========
194.\" .It Bq Er EIO
195.\" The process is ignoring or blocking the SIGTTIN signal.
196.\" ===========
197.It Bq Er EIO
198The process group is orphaned.
199.\" ===========
200.It Bq Er EIO
201The file is a regular file,
202.Fa nbyte
203is greater than 0,
204the starting position is before the end-of-file,
205and the starting position is greater than or equal
206to the offset maximum established
207for the open file descriptor associated with
208.Fa fildes .
209.\" ===========
210.It Bq Er EISDIR
211An attempt is made to read a directory.
212.\" ===========
213.It Bq Er ENOBUFS
214An attempt to allocate a memory buffer fails.
215.\" ===========
216.It Bq Er ENOMEM
217Insufficient memory is available.
218.\" ===========
219.It Bq Er ENXIO
220An action is requested of a device that does not exist.
221.\" ===========
222.It Bq Er ENXIO
223A requested action cannot be performed by the device.
224.\" ===========
225.It Bq Er ESTALE
226An attempt to read a remote file through NFS that has already been deleted in
227the server.
228.\" ===========
229.It Bq Er ETIMEDOUT
230The connection timed out while reading a remote file from a soft mounted NFS
231volume (see
232.Xr mount_nfs 8 ) .
233.\" ===========
234.It Bq Er ETIMEDOUT
235The file is a
236.Dq dataless
237file that requires materialization and materialization timed out or
238encountered some other temporary failure.
239.\" ===========
240.It Bq Er EDEADLK
241The file is a
242.Dq dataless
243file that requires materialization and the I/O policy of the current thread
244or process disallows dataless file materialization
245.Po see
246.Xr getiopolicy_np 3
247.Pc .
248.El
249.Pp
250.Fn pread
251and
252.Fn preadv
253calls may also return the following errors:
254.Bl -tag -width Er
255.\" ===========
256.It Bq Er EINVAL
257The specified file offset is invalid.
258.\" ===========
259.It Bq Er ESPIPE
260The file descriptor is associated with a pipe, socket, or FIFO.
261.El
262.Pp
263The
264.Fn read
265call may also return the following errors:
266.Bl -tag -width Er
267.\" ===========
268.It Bq Er ECONNRESET
269The connection is closed by the peer
270during a read attempt on a socket.
271.\" ===========
272.It Bq Er ENOTCONN
273A read is attempted on an unconnected socket.
274.\" ===========
275.It Bq Er ETIMEDOUT
276A transmission timeout occurs
277during a read attempt on a socket.
278.El
279.Pp
280The
281.Fn readv
282and
283.Fn preadv
284calls may also return one of the following errors:
285.Bl -tag -width Er
286.\" ===========
287.It Bq Er EFAULT
288Part of the
289.Fa iov
290points outside the process's allocated address space.
291.\" ===========
292.It Bq Er EINVAL
293.Fa Iovcnt
294was less than or equal to 0, or greater than 16.
295.\" ===========
296.It Bq Er EINVAL
297One of the
298.Fa iov_len
299values in the
300.Fa iov
301array was negative.
302.\" ===========
303.It Bq Er EINVAL
304The sum of the
305.Fa iov_len
306values in the
307.Fa iov
308array overflowed a 32-bit integer.
309.El
310.Sh LEGACY SYNOPSIS
311.Fd #include <sys/types.h>
312.Fd #include <sys/uio.h>
313.Fd #include <unistd.h>
314.Pp
315The include files
316.In sys/types.h
317and
318.In sys/uio.h
319are necessary for all functions.
320.Sh SEE ALSO
321.Xr dup 2 ,
322.Xr fcntl 2 ,
323.Xr open 2 ,
324.Xr pipe 2 ,
325.Xr select 2 ,
326.Xr socket 2 ,
327.Xr socketpair 2 ,
328.Xr compat 5
329.Sh STANDARDS
330The
331.Fn read
332function call is expected to conform to
333.St -p1003.1-90 .
334The
335.Fn readv
336and
337.Fn pread
338functions are expected to conform to
339.St -xpg4.2 .
340.Fn preadv
341is nonstandard.
342.Sh HISTORY
343The
344.Fn pread
345function call
346appeared in
347.At V.4 .
348The
349.Fn readv
350function call
351appeared in
352.Bx 4.2 .
353A
354.Fn read
355function call appeared in
356.At v6 .
357