Commit | Line | Data |
---|---|---|
e02f9a7b KM |
1 | .\" Copyright (c) 1980 Regents of the University of California. |
2 | .\" All rights reserved. The Berkeley software License Agreement | |
3 | .\" specifies the terms and conditions for redistribution. | |
4 | .\" | |
3e664f4b | 5 | .\" @(#)read.2 6.6 (Berkeley) %G% |
e02f9a7b | 6 | .\" |
4b664abe | 7 | .TH READ 2 "" |
e02f9a7b KM |
8 | .UC 4 |
9 | .SH NAME | |
a7ae7183 | 10 | read, readv \- read input |
e02f9a7b KM |
11 | .SH SYNOPSIS |
12 | .nf | |
a7ae7183 KM |
13 | .ft B |
14 | cc = read(d, buf, nbytes) | |
15 | int cc, d; | |
16 | char *buf; | |
17 | int nbytes; | |
18 | .PP | |
19 | .ft B | |
20 | #include <sys/types.h> | |
21 | #include <sys/uio.h> | |
22 | .PP | |
23 | .ft B | |
24 | cc = readv(d, iov, iovcnt) | |
25 | int cc, d; | |
26 | struct iovec *iov; | |
27 | int iovcnt; | |
e02f9a7b KM |
28 | .fi |
29 | .SH DESCRIPTION | |
a7ae7183 KM |
30 | .I Read |
31 | attempts to read | |
e02f9a7b | 32 | .I nbytes |
a7ae7183 KM |
33 | of data from the object referenced by the descriptor |
34 | .I d | |
35 | into the buffer pointed to by | |
36 | .IR buf . | |
37 | .I Readv | |
38 | performs the same action, but scatters the input data | |
39 | into the | |
40 | .I iovcnt | |
41 | buffers specified by the members of the | |
d1c0365c | 42 | .I iov |
a7ae7183 | 43 | array: iov[0], iov[1], ..., iov[iovcnt\|\-\|1]. |
e02f9a7b | 44 | .PP |
a7ae7183 KM |
45 | For |
46 | .IR readv , | |
47 | the | |
48 | .I iovec | |
49 | structure is defined as | |
e02f9a7b | 50 | .PP |
a7ae7183 KM |
51 | .nf |
52 | .RS | |
53 | .DT | |
54 | struct iovec { | |
55 | caddr_t iov_base; | |
56 | int iov_len; | |
57 | }; | |
58 | .RE | |
59 | .fi | |
e02f9a7b | 60 | .PP |
a7ae7183 KM |
61 | Each |
62 | .I iovec | |
63 | entry specifies the base address and length of an area | |
64 | in memory where data should be placed. | |
65 | .I Readv | |
66 | will always fill an area completely before proceeding | |
67 | to the next. | |
68 | .PP | |
69 | On objects capable of seeking, the | |
e02f9a7b | 70 | .I read |
a7ae7183 KM |
71 | starts at a position |
72 | given by the pointer associated with | |
3e664f4b KD |
73 | .IR d |
74 | (see | |
75 | .IR lseek (2)). | |
a7ae7183 KM |
76 | Upon return from |
77 | .IR read , | |
78 | the pointer is incremented by the number of bytes actually read. | |
79 | .PP | |
80 | Objects that are not capable of seeking always read from the current | |
d1c0365c | 81 | position. The value of the pointer associated with such an |
a7ae7183 | 82 | object is undefined. |
e02f9a7b | 83 | .PP |
a7ae7183 | 84 | Upon successful completion, |
e02f9a7b | 85 | .I read |
a7ae7183 KM |
86 | and |
87 | .I readv | |
88 | return the number of bytes actually read and placed in the buffer. | |
89 | The system guarantees to read the number of bytes requested if | |
15fa213a MK |
90 | the descriptor references a normal file that has that many bytes left |
91 | before the end-of-file, but in no other case. | |
a7ae7183 KM |
92 | .PP |
93 | If the returned value is 0, then | |
94 | end-of-file has been reached. | |
95 | .SH "RETURN VALUE | |
96 | If successful, the | |
97 | number of bytes actually read is returned. | |
98 | Otherwise, a \-1 is returned and the global variable | |
99 | .I errno | |
100 | is set to indicate the error. | |
101 | .SH "ERRORS | |
102 | .I Read | |
103 | and | |
104 | .I readv | |
105 | will fail if one or more of the following are true: | |
106 | .TP 15 | |
107 | [EBADF] | |
4b664abe | 108 | \fID\fP is not a valid file or socket descriptor open for reading. |
a7ae7183 KM |
109 | .TP 15 |
110 | [EFAULT] | |
111 | \fIBuf\fP points outside the allocated address space. | |
112 | .TP 15 | |
fd690c8b KM |
113 | [EIO] |
114 | An I/O error occurred while reading from the file system. | |
115 | .TP 15 | |
a7ae7183 KM |
116 | [EINTR] |
117 | A read from a slow device was interrupted before | |
118 | any data arrived by the delivery of a signal. | |
d1c0365c JL |
119 | .TP 15 |
120 | [EINVAL] | |
121 | The pointer associated with | |
122 | .I d | |
123 | was negative. | |
15fa213a MK |
124 | .TP 15 |
125 | [EWOULDBLOCK] | |
126 | The file was marked for non-blocking I/O, | |
127 | and no data were ready to be read. | |
a7ae7183 KM |
128 | .PP |
129 | In addition, | |
130 | .I readv | |
131 | may return one of the following errors: | |
132 | .TP 15 | |
133 | [EINVAL] | |
134 | .I Iovcnt | |
135 | was less than or equal to 0, or greater than 16. | |
136 | .TP 15 | |
137 | [EINVAL] | |
138 | One of the | |
139 | .I iov_len | |
140 | values in the | |
141 | .I iov | |
142 | array was negative. | |
143 | .TP 15 | |
144 | [EINVAL] | |
145 | The sum of the | |
146 | .I iov_len | |
147 | values in the | |
148 | .I iov | |
149 | array overflowed a 32-bit integer. | |
fd690c8b KM |
150 | .TP 15 |
151 | [EFAULT] | |
152 | Part of the \fIiov\fP points outside the process's allocated address space. | |
a7ae7183 | 153 | .SH "SEE ALSO" |
15fa213a | 154 | dup(2), fcntl(2), open(2), pipe(2), select(2), socket(2), socketpair(2) |