]>
Commit | Line | Data |
---|---|---|
5427f5fb | 1 | .\" Copyright (C) 2007, 2010 Michael Kerrisk <mtk.manpages@gmail.com> |
f37855d1 | 2 | .\" and Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) |
fea681da | 3 | .\" |
93015253 | 4 | .\" %%%LICENSE_START(VERBATIM) |
fea681da MK |
5 | .\" Permission is granted to make and distribute verbatim copies of this |
6 | .\" manual provided the copyright notice and this permission notice are | |
7 | .\" preserved on all copies. | |
8 | .\" | |
9 | .\" Permission is granted to copy and distribute modified versions of this | |
10 | .\" manual under the conditions for verbatim copying, provided that the | |
11 | .\" entire resulting derived work is distributed under the terms of a | |
12 | .\" permission notice identical to this one. | |
c13182ef | 13 | .\" |
fea681da MK |
14 | .\" Since the Linux kernel and libraries are constantly changing, this |
15 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
16 | .\" responsibility for errors or omissions, or for damages resulting from | |
17 | .\" the use of the information contained herein. The author(s) may not | |
18 | .\" have taken the same level of care in the production of this manual, | |
19 | .\" which is licensed free of charge, as they might when working | |
20 | .\" professionally. | |
c13182ef | 21 | .\" |
fea681da MK |
22 | .\" Formatted or processed versions of this manual, if unaccompanied by |
23 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 24 | .\" %%%LICENSE_END |
c08df37a | 25 | .\" |
fea681da MK |
26 | .\" Modified Sat Jul 24 18:34:44 1993 by Rik Faith (faith@cs.unc.edu) |
27 | .\" Merged readv.[23], 2002-10-17, aeb | |
ab44d3d6 MK |
28 | .\" 2007-04-30 mtk, A fairly major rewrite to fix errors and |
29 | .\" add more details. | |
5427f5fb | 30 | .\" 2010-11-16, mtk, Added documentation of preadv() and pwritev() |
fea681da | 31 | .\" |
e0e3a6a3 | 32 | .TH READV 2 2010-11-17 "Linux" "Linux Programmer's Manual" |
fea681da | 33 | .SH NAME |
e0e3a6a3 | 34 | readv, writev, preadv, pwritev \- read or write data into multiple buffers |
fea681da MK |
35 | .SH SYNOPSIS |
36 | .nf | |
37 | .B #include <sys/uio.h> | |
38 | .sp | |
ab44d3d6 | 39 | .BI "ssize_t readv(int " fd ", const struct iovec *" iov ", int " iovcnt ); |
fea681da | 40 | .sp |
ab44d3d6 | 41 | .BI "ssize_t writev(int " fd ", const struct iovec *" iov ", int " iovcnt ); |
e0e3a6a3 | 42 | .sp |
c5662d5d | 43 | .BI "ssize_t preadv(int " fd ", const struct iovec *" iov ", int " iovcnt , |
e0e3a6a3 MK |
44 | .BI " off_t " offset ); |
45 | .sp | |
46 | .BI "ssize_t pwritev(int " fd ", const struct iovec *" iov ", int " iovcnt , | |
47 | .BI " off_t " offset ); | |
fea681da | 48 | .fi |
e0e3a6a3 MK |
49 | .sp |
50 | .in -4n | |
51 | Feature Test Macro Requirements for glibc (see | |
52 | .BR feature_test_macros (7)): | |
53 | .in | |
54 | .sp | |
55 | .BR preadv (), | |
56 | .BR pwritev (): | |
57 | _BSD_SOURCE | |
fea681da MK |
58 | .SH DESCRIPTION |
59 | The | |
8a1dd514 | 60 | .BR readv () |
e7d82451 | 61 | system call reads |
ab44d3d6 MK |
62 | .I iovcnt |
63 | buffers from the file associated with the file descriptor | |
fea681da | 64 | .I fd |
ab44d3d6 | 65 | into the buffers described by |
0daa9e92 | 66 | .I iov |
ab44d3d6 | 67 | ("scatter input"). |
fea681da MK |
68 | .PP |
69 | The | |
8a1dd514 | 70 | .BR writev () |
e7d82451 | 71 | system call writes |
ab44d3d6 MK |
72 | .I iovcnt |
73 | buffers of data described by | |
74 | .I iov | |
fea681da | 75 | to the file associated with the file descriptor |
0daa9e92 | 76 | .I fd |
ab44d3d6 | 77 | ("gather output"). |
fea681da MK |
78 | .PP |
79 | The pointer | |
ab44d3d6 | 80 | .I iov |
988db661 | 81 | points to an array of |
ab44d3d6 MK |
82 | .I iovec |
83 | structures, | |
fea681da | 84 | defined in |
8a1dd514 | 85 | .I <sys/uio.h> |
ab44d3d6 | 86 | as: |
fea681da MK |
87 | .PP |
88 | .br | |
088a639b | 89 | .in +4n |
fea681da | 90 | .nf |
fea681da | 91 | struct iovec { |
ab44d3d6 MK |
92 | void *iov_base; /* Starting address */ |
93 | size_t iov_len; /* Number of bytes to transfer */ | |
fea681da MK |
94 | }; |
95 | .fi | |
088a639b | 96 | .in |
fea681da | 97 | .PP |
fea681da | 98 | The |
8a1dd514 | 99 | .BR readv () |
e7d82451 | 100 | system call works just like |
fea681da MK |
101 | .BR read (2) |
102 | except that multiple buffers are filled. | |
103 | .PP | |
104 | The | |
8a1dd514 | 105 | .BR writev () |
e7d82451 | 106 | system call works just like |
fea681da MK |
107 | .BR write (2) |
108 | except that multiple buffers are written out. | |
ab44d3d6 MK |
109 | .PP |
110 | Buffers are processed in array order. | |
111 | This means that | |
112 | .BR readv () | |
113 | completely fills | |
114 | .IR iov [0] | |
988db661 | 115 | before proceeding to |
ab44d3d6 MK |
116 | .IR iov [1], |
117 | and so on. | |
118 | (If there is insufficient data, then not all buffers pointed to by | |
119 | .I iov | |
120 | may be filled.) | |
121 | Similarly, | |
122 | .BR writev () | |
123 | writes out the entire contents of | |
124 | .IR iov [0] | |
988db661 | 125 | before proceeding to |
ab44d3d6 MK |
126 | .IR iov [1], |
127 | and so on. | |
128 | .PP | |
129 | The data transfers performed by | |
130 | .BR readv () | |
131 | and | |
132 | .BR writev () | |
133 | are atomic: the data written by | |
134 | .BR writev () | |
135 | is written as a single block that is not intermingled with output | |
136 | from writes in other processes (but see | |
137 | .BR pipe (7) | |
138 | for an exception); | |
139 | analogously, | |
140 | .BR readv () | |
141 | is guaranteed to read a contiguous block of data from the file, | |
142 | regardless of read operations performed in other threads or processes | |
143 | that have file descriptors referring to the same open file description | |
988db661 | 144 | (see |
ab44d3d6 | 145 | .BR open (2)). |
e0e3a6a3 MK |
146 | .SS preadv() and pwritev() |
147 | The | |
148 | .BR preadv () | |
149 | system call combines the functionality of | |
150 | .BR readv () | |
151 | and | |
152 | .BR pread (2). | |
153 | It performs the same task as | |
154 | .BR readv (), | |
155 | but adds a fourth argument, | |
156 | .IR offset , | |
157 | which specifies the file offset at which the input operation | |
158 | is to be performed. | |
159 | ||
160 | The | |
161 | .BR pwritev () | |
162 | system call combines the functionality of | |
163 | .BR writev () | |
164 | and | |
165 | .BR pwrite (2). | |
166 | It performs the same task as | |
167 | .BR writev (), | |
168 | but adds a fourth argument, | |
169 | .IR offset , | |
170 | which specifies the file offset at which the output operation | |
171 | is to be performed. | |
172 | ||
173 | The file offset is not changed by these system calls. | |
174 | The file referred to by | |
175 | .I fd | |
176 | must be capable of seeking. | |
47297adb | 177 | .SH RETURN VALUE |
9d04fbe5 | 178 | On success, |
8a1dd514 | 179 | .BR readv () |
e0e3a6a3 MK |
180 | and |
181 | .BR preadv () | |
182 | return the number of bytes read; | |
8a1dd514 | 183 | .BR writev () |
e0e3a6a3 MK |
184 | and |
185 | .BR pwritev () | |
186 | return the number of bytes written. | |
fea681da MK |
187 | On error, \-1 is returned, and \fIerrno\fP is set appropriately. |
188 | .SH ERRORS | |
189 | The errors are as given for | |
190 | .BR read (2) | |
191 | and | |
192 | .BR write (2). | |
e0e3a6a3 MK |
193 | Furthermore, |
194 | .BR preadv () | |
195 | and | |
196 | .BR pwritev () | |
197 | can also fail for the same reasons as | |
198 | .BR lseek (2). | |
199 | Additionally, the following error is defined: | |
fea681da MK |
200 | .TP |
201 | .B EINVAL | |
202 | The sum of the | |
203 | .I iov_len | |
204 | values overflows an | |
8a1dd514 | 205 | .I ssize_t |
c13182ef | 206 | value. |
a8d55537 | 207 | Or, the vector count \fIiovcnt\fP is less than zero or greater than the |
8a1dd514 | 208 | permitted maximum. |
e0e3a6a3 MK |
209 | .SH VERSIONS |
210 | .BR preadv () | |
fea681da | 211 | and |
e0e3a6a3 MK |
212 | .BR pwritev () |
213 | first appeared in Linux 2.6.30; library support was added in glibc 2.10. | |
47297adb | 214 | .SH CONFORMING TO |
e0e3a6a3 MK |
215 | .BR readv (), |
216 | .BR writev (): | |
e7d82451 | 217 | 4.4BSD (these system calls first appeared in 4.2BSD), POSIX.1-2001. |
c4bb193f | 218 | Linux libc5 used \fIsize_t\fP as the type of the \fIiovcnt\fP argument, |
e7d82451 | 219 | and \fIint\fP as the return type. |
fea681da MK |
220 | .\" The readv/writev system calls were buggy before Linux 1.3.40. |
221 | .\" (Says release.libc.) | |
e0e3a6a3 MK |
222 | |
223 | .BR preadv (), | |
224 | .BR pwritev (): | |
225 | nonstandard, but present also on the modern BSDs. | |
4fb31341 | 226 | .SH NOTES |
c634028a | 227 | .SS Linux notes |
c13182ef | 228 | POSIX.1-2001 allows an implementation to place a limit on |
97c1eac8 | 229 | the number of items that can be passed in |
ab44d3d6 | 230 | .IR iov . |
8a1dd514 MK |
231 | An implementation can advertise its limit by defining |
232 | .B IOV_MAX | |
233 | in | |
0daa9e92 | 234 | .I <limits.h> |
8a1dd514 MK |
235 | or at run time via the return value from |
236 | .IR sysconf(_SC_IOV_MAX) . | |
237 | On Linux, the limit advertised by these mechanisms is 1024, | |
238 | which is the true kernel limit. | |
239 | However, the glibc wrapper functions do some extra work if | |
240 | they detect that the underlying kernel system call failed because this | |
c13182ef MK |
241 | limit was exceeded. |
242 | In the case of | |
be6752b6 | 243 | .BR readv (). |
c13182ef | 244 | the wrapper function allocates a temporary buffer large enough |
8a1dd514 | 245 | for all of the items specified by |
ab44d3d6 | 246 | .IR iov , |
c13182ef | 247 | passes that buffer in a call to |
0bfa087b | 248 | .BR read (2), |
8a1dd514 MK |
249 | copies data from the buffer to the locations specified by the |
250 | .I iov_base | |
c13182ef | 251 | fields of the elements of |
ab44d3d6 | 252 | .IR iov , |
8a1dd514 MK |
253 | and then frees the buffer. |
254 | The wrapper function for | |
255 | .BR writev () | |
256 | performs the analogous task using a temporary buffer and a call to | |
0bfa087b | 257 | .BR write (2). |
fea681da | 258 | .SH BUGS |
e7d82451 | 259 | It is not advisable to mix calls to |
8a1dd514 | 260 | .BR readv () |
fea681da | 261 | or |
8a1dd514 | 262 | .BR writev (), |
fea681da MK |
263 | which operate on file descriptors, with the functions from the stdio |
264 | library; the results will be undefined and probably not what you want. | |
ab44d3d6 MK |
265 | .SH EXAMPLE |
266 | The following code sample demonstrates the use of | |
267 | .BR writev (): | |
268 | ||
088a639b | 269 | .in +4n |
ab44d3d6 MK |
270 | .nf |
271 | char *str0 = "hello "; | |
272 | char *str1 = "world\\n"; | |
273 | struct iovec iov[2]; | |
274 | ssize_t nwritten; | |
275 | ||
276 | iov[0].iov_base = str0; | |
277 | iov[0].iov_len = strlen(str0); | |
278 | iov[1].iov_base = str1; | |
279 | iov[1].iov_len = strlen(str1); | |
280 | ||
281 | nwritten = writev(STDOUT_FILENO, iov, 2); | |
282 | .fi | |
283 | .in | |
47297adb | 284 | .SH SEE ALSO |
e0e3a6a3 | 285 | .BR pread (2), |
fea681da MK |
286 | .BR read (2), |
287 | .BR write (2) |