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
| 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: head/lib/libc/sys/read.2 50476 1999-08-28 00:22:10Z peter $
| 33.\" $FreeBSD: head/lib/libc/sys/read.2 57686 2000-03-02 09:14:21Z sheldonh $
|
34.\"
35.Dd February 26, 1994
36.Dt READ 2
37.Os BSD 4
38.Sh NAME
39.Nm read ,
40.Nm readv ,
41.Nm pread
42.Nd read input
43.Sh SYNOPSIS
44.Fd #include <sys/types.h>
45.Fd #include <sys/uio.h>
46.Fd #include <unistd.h>
47.Ft ssize_t
48.Fn read "int d" "void *buf" "size_t nbytes"
49.Ft ssize_t
50.Fn readv "int d" "const struct iovec *iov" "int iovcnt"
51.Ft ssize_t
52.Fn pread "int d" "void *buf" "size_t nbytes" "off_t offset"
53.Sh DESCRIPTION
54.Fn Read
55attempts to read
56.Fa nbytes
57of data from the object referenced by the descriptor
58.Fa d
59into the buffer pointed to by
60.Fa buf .
61.Fn Readv
62performs the same action, but scatters the input data
63into the
64.Fa iovcnt
65buffers specified by the members of the
66.Fa iov
67array: iov[0], iov[1], ..., iov[iovcnt\|\-\|1].
68.Fn Pread
69performs the same function, but reads from the specified position in
70the file without modifying the file pointer.
71.Pp
72For
73.Fn readv ,
74the
75.Fa iovec
76structure is defined as:
77.Pp
78.Bd -literal -offset indent -compact
79struct iovec {
80 char *iov_base; /* Base address. */
81 size_t iov_len; /* Length. */
82};
83.Ed
84.Pp
85Each
86.Fa iovec
87entry specifies the base address and length of an area
88in memory where data should be placed.
89.Fn Readv
90will always fill an area completely before proceeding
91to the next.
92.Pp
93On objects capable of seeking, the
94.Fn read
95starts at a position
96given by the pointer associated with
97.Fa d
98(see
99.Xr lseek 2 ) .
100Upon return from
101.Fn read ,
102the pointer is incremented by the number of bytes actually read.
103.Pp
104Objects that are not capable of seeking always read from the current
105position. The value of the pointer associated with such an
106object is undefined.
107.Pp
108Upon successful completion,
109.Fn read ,
110.Fn readv ,
111and
112.Fn pread
113return the number of bytes actually read and placed in the buffer.
114The system guarantees to read the number of bytes requested if
115the descriptor references a normal file that has that many bytes left
116before the end-of-file, but in no other case.
117.Pp
118.Sh IMPLEMENTATION NOTES
119.Pp
120In the non-threaded library
121.Fn read
122is implemented as the
123.Va read
124syscall.
125.Pp
126In the threaded library, the
127.Va read
128syscall is assembled to
129.Fn _thread_sys_read
130and
131.Fn read
132is implemented as a function which locks
133.Va d
134for read, then calls
135.Fn _thread_sys_read .
136If the call to
137.Fn _thread_sys_read
| 34.\"
35.Dd February 26, 1994
36.Dt READ 2
37.Os BSD 4
38.Sh NAME
39.Nm read ,
40.Nm readv ,
41.Nm pread
42.Nd read input
43.Sh SYNOPSIS
44.Fd #include <sys/types.h>
45.Fd #include <sys/uio.h>
46.Fd #include <unistd.h>
47.Ft ssize_t
48.Fn read "int d" "void *buf" "size_t nbytes"
49.Ft ssize_t
50.Fn readv "int d" "const struct iovec *iov" "int iovcnt"
51.Ft ssize_t
52.Fn pread "int d" "void *buf" "size_t nbytes" "off_t offset"
53.Sh DESCRIPTION
54.Fn Read
55attempts to read
56.Fa nbytes
57of data from the object referenced by the descriptor
58.Fa d
59into the buffer pointed to by
60.Fa buf .
61.Fn Readv
62performs the same action, but scatters the input data
63into the
64.Fa iovcnt
65buffers specified by the members of the
66.Fa iov
67array: iov[0], iov[1], ..., iov[iovcnt\|\-\|1].
68.Fn Pread
69performs the same function, but reads from the specified position in
70the file without modifying the file pointer.
71.Pp
72For
73.Fn readv ,
74the
75.Fa iovec
76structure is defined as:
77.Pp
78.Bd -literal -offset indent -compact
79struct iovec {
80 char *iov_base; /* Base address. */
81 size_t iov_len; /* Length. */
82};
83.Ed
84.Pp
85Each
86.Fa iovec
87entry specifies the base address and length of an area
88in memory where data should be placed.
89.Fn Readv
90will always fill an area completely before proceeding
91to the next.
92.Pp
93On objects capable of seeking, the
94.Fn read
95starts at a position
96given by the pointer associated with
97.Fa d
98(see
99.Xr lseek 2 ) .
100Upon return from
101.Fn read ,
102the pointer is incremented by the number of bytes actually read.
103.Pp
104Objects that are not capable of seeking always read from the current
105position. The value of the pointer associated with such an
106object is undefined.
107.Pp
108Upon successful completion,
109.Fn read ,
110.Fn readv ,
111and
112.Fn pread
113return the number of bytes actually read and placed in the buffer.
114The system guarantees to read the number of bytes requested if
115the descriptor references a normal file that has that many bytes left
116before the end-of-file, but in no other case.
117.Pp
118.Sh IMPLEMENTATION NOTES
119.Pp
120In the non-threaded library
121.Fn read
122is implemented as the
123.Va read
124syscall.
125.Pp
126In the threaded library, the
127.Va read
128syscall is assembled to
129.Fn _thread_sys_read
130and
131.Fn read
132is implemented as a function which locks
133.Va d
134for read, then calls
135.Fn _thread_sys_read .
136If the call to
137.Fn _thread_sys_read
|
138would block, a context switch is performed. Before returning,
| 138would block, a context switch is performed.
139Before returning,
|
139.Fn read
140unlocks
141.Va d .
142.Pp
143In the non-threaded library
144.Fn readv
145is implemented as the
146.Va readv
147syscall.
148.Pp
149In the threaded library, the
150.Va readv
151syscall is assembled to
152.Fn _thread_sys_readv
153and
154.Fn readv
155is implemented as a function which locks
156.Va d
157for read, then calls
158.Fn _thread_sys_readv .
159If the call to
160.Fn _thread_sys_readv
| 140.Fn read
141unlocks
142.Va d .
143.Pp
144In the non-threaded library
145.Fn readv
146is implemented as the
147.Va readv
148syscall.
149.Pp
150In the threaded library, the
151.Va readv
152syscall is assembled to
153.Fn _thread_sys_readv
154and
155.Fn readv
156is implemented as a function which locks
157.Va d
158for read, then calls
159.Fn _thread_sys_readv .
160If the call to
161.Fn _thread_sys_readv
|
161would block, a context switch is performed. Before returning,
| 162would block, a context switch is performed.
163Before returning,
|
162.Fn readv
163unlocks
164.Va d .
165.Sh RETURN VALUES
166If successful, the
| 164.Fn readv
165unlocks
166.Va d .
167.Sh RETURN VALUES
168If successful, the
|
167number of bytes actually read is returned. Upon reading end-of-file,
| 169number of bytes actually read is returned.
170Upon reading end-of-file,
|
168zero is returned.
169Otherwise, a -1 is returned and the global variable
170.Va errno
171is set to indicate the error.
172.Sh ERRORS
173.Fn Read ,
174.Fn readv ,
175and
176.Fn pread
177will succeed unless:
178.Bl -tag -width Er
179.It Bq Er EBADF
180.Fa D
181is not a valid file or socket descriptor open for reading.
182.It Bq Er EFAULT
183.Fa Buf
184points outside the allocated address space.
185.It Bq Er EIO
186An I/O error occurred while reading from the file system.
187.It Bq Er EINTR
188A read from a slow device was interrupted before
189any data arrived by the delivery of a signal.
190.It Bq Er EINVAL
191The pointer associated with
192.Fa d
193was negative.
194.It Bq Er EAGAIN
195The file was marked for non-blocking I/O,
196and no data were ready to be read.
197.El
198.Pp
199In addition,
200.Fn readv
201may return one of the following errors:
202.Bl -tag -width Er
203.It Bq Er EINVAL
204.Fa Iovcnt
205was less than or equal to 0, or greater than 16.
206.It Bq Er EINVAL
207One of the
208.Fa iov_len
209values in the
210.Fa iov
211array was negative.
212.It Bq Er EINVAL
213The sum of the
214.Fa iov_len
215values in the
216.Fa iov
217array overflowed a 32-bit integer.
218.It Bq Er EFAULT
219Part of the
220.Fa iov
221points outside the process's allocated address space.
222.El
223.Pp
224The
225.Fn pread
226call may also return the following errors:
227.Bl -tag -width Er
228.It Bq Er EINVAL
229The specified file offset is invalid.
230.It Bq Er ESPIPE
231The file descriptor is associated with a pipe, socket, or FIFO.
232.El
233.Sh SEE ALSO
234.Xr dup 2 ,
235.Xr fcntl 2 ,
236.Xr open 2 ,
237.Xr pipe 2 ,
238.Xr select 2 ,
239.Xr socket 2 ,
240.Xr socketpair 2
241.Sh STANDARDS
242The
243.Fn read
244function call is expected to conform to
245.St -p1003.1-90 .
246The
247.Fn readv
248and
249.Fn pread
250functions are expected to conform to
251.St -xpg4.2 .
252.Sh HISTORY
253The
254.Fn pread
255function call
256appeared in
257.At V.4 .
258The
259.Fn readv
260function call
261appeared in
262.Bx 4.2 .
263A
264.Fn read
265function call appeared in
266.At v6 .
| 171zero is returned.
172Otherwise, a -1 is returned and the global variable
173.Va errno
174is set to indicate the error.
175.Sh ERRORS
176.Fn Read ,
177.Fn readv ,
178and
179.Fn pread
180will succeed unless:
181.Bl -tag -width Er
182.It Bq Er EBADF
183.Fa D
184is not a valid file or socket descriptor open for reading.
185.It Bq Er EFAULT
186.Fa Buf
187points outside the allocated address space.
188.It Bq Er EIO
189An I/O error occurred while reading from the file system.
190.It Bq Er EINTR
191A read from a slow device was interrupted before
192any data arrived by the delivery of a signal.
193.It Bq Er EINVAL
194The pointer associated with
195.Fa d
196was negative.
197.It Bq Er EAGAIN
198The file was marked for non-blocking I/O,
199and no data were ready to be read.
200.El
201.Pp
202In addition,
203.Fn readv
204may return one of the following errors:
205.Bl -tag -width Er
206.It Bq Er EINVAL
207.Fa Iovcnt
208was less than or equal to 0, or greater than 16.
209.It Bq Er EINVAL
210One of the
211.Fa iov_len
212values in the
213.Fa iov
214array was negative.
215.It Bq Er EINVAL
216The sum of the
217.Fa iov_len
218values in the
219.Fa iov
220array overflowed a 32-bit integer.
221.It Bq Er EFAULT
222Part of the
223.Fa iov
224points outside the process's allocated address space.
225.El
226.Pp
227The
228.Fn pread
229call may also return the following errors:
230.Bl -tag -width Er
231.It Bq Er EINVAL
232The specified file offset is invalid.
233.It Bq Er ESPIPE
234The file descriptor is associated with a pipe, socket, or FIFO.
235.El
236.Sh SEE ALSO
237.Xr dup 2 ,
238.Xr fcntl 2 ,
239.Xr open 2 ,
240.Xr pipe 2 ,
241.Xr select 2 ,
242.Xr socket 2 ,
243.Xr socketpair 2
244.Sh STANDARDS
245The
246.Fn read
247function call is expected to conform to
248.St -p1003.1-90 .
249The
250.Fn readv
251and
252.Fn pread
253functions are expected to conform to
254.St -xpg4.2 .
255.Sh HISTORY
256The
257.Fn pread
258function call
259appeared in
260.At V.4 .
261The
262.Fn readv
263function call
264appeared in
265.Bx 4.2 .
266A
267.Fn read
268function call appeared in
269.At v6 .
|