]>
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 | .\" |
5fbde956 | 4 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
c08df37a | 5 | .\" |
fea681da MK |
6 | .\" Modified Sat Jul 24 18:34:44 1993 by Rik Faith (faith@cs.unc.edu) |
7 | .\" Merged readv.[23], 2002-10-17, aeb | |
ab44d3d6 MK |
8 | .\" 2007-04-30 mtk, A fairly major rewrite to fix errors and |
9 | .\" add more details. | |
5427f5fb | 10 | .\" 2010-11-16, mtk, Added documentation of preadv() and pwritev() |
fea681da | 11 | .\" |
6e00b7a8 | 12 | .TH READV 2 2021-08-27 "Linux" "Linux Programmer's Manual" |
fea681da | 13 | .SH NAME |
cc849b73 | 14 | readv, writev, preadv, pwritev, preadv2, pwritev2 \- read or write data into multiple buffers |
9811face AC |
15 | .SH LIBRARY |
16 | Standard C library | |
8fc3b2cf | 17 | .RI ( libc ", " \-lc ) |
fea681da MK |
18 | .SH SYNOPSIS |
19 | .nf | |
20 | .B #include <sys/uio.h> | |
68e4db0a | 21 | .PP |
ab44d3d6 | 22 | .BI "ssize_t readv(int " fd ", const struct iovec *" iov ", int " iovcnt ); |
ab44d3d6 | 23 | .BI "ssize_t writev(int " fd ", const struct iovec *" iov ", int " iovcnt ); |
68e4db0a | 24 | .PP |
c5662d5d | 25 | .BI "ssize_t preadv(int " fd ", const struct iovec *" iov ", int " iovcnt , |
f2667a72 | 26 | .BI " off_t " offset ); |
e0e3a6a3 MK |
27 | .BI "ssize_t pwritev(int " fd ", const struct iovec *" iov ", int " iovcnt , |
28 | .BI " off_t " offset ); | |
68e4db0a | 29 | .PP |
d948a870 CH |
30 | .BI "ssize_t preadv2(int " fd ", const struct iovec *" iov ", int " iovcnt , |
31 | .BI " off_t " offset ", int " flags ); | |
d948a870 | 32 | .BI "ssize_t pwritev2(int " fd ", const struct iovec *" iov ", int " iovcnt , |
f2667a72 | 33 | .BI " off_t " offset ", int " flags ); |
fea681da | 34 | .fi |
68e4db0a | 35 | .PP |
d39ad78f | 36 | .RS -4 |
e0e3a6a3 MK |
37 | Feature Test Macro Requirements for glibc (see |
38 | .BR feature_test_macros (7)): | |
d39ad78f | 39 | .RE |
68e4db0a | 40 | .PP |
e0e3a6a3 MK |
41 | .BR preadv (), |
42 | .BR pwritev (): | |
9d281e06 | 43 | .nf |
51c612fb MK |
44 | Since glibc 2.19: |
45 | _DEFAULT_SOURCE | |
46 | Glibc 2.19 and earlier: | |
47 | _BSD_SOURCE | |
9d281e06 | 48 | .fi |
fea681da MK |
49 | .SH DESCRIPTION |
50 | The | |
8a1dd514 | 51 | .BR readv () |
e7d82451 | 52 | system call reads |
ab44d3d6 MK |
53 | .I iovcnt |
54 | buffers from the file associated with the file descriptor | |
fea681da | 55 | .I fd |
ab44d3d6 | 56 | into the buffers described by |
0daa9e92 | 57 | .I iov |
ab44d3d6 | 58 | ("scatter input"). |
fea681da MK |
59 | .PP |
60 | The | |
8a1dd514 | 61 | .BR writev () |
e7d82451 | 62 | system call writes |
ab44d3d6 MK |
63 | .I iovcnt |
64 | buffers of data described by | |
65 | .I iov | |
fea681da | 66 | to the file associated with the file descriptor |
0daa9e92 | 67 | .I fd |
ab44d3d6 | 68 | ("gather output"). |
fea681da MK |
69 | .PP |
70 | The pointer | |
ab44d3d6 | 71 | .I iov |
988db661 | 72 | points to an array of |
ab44d3d6 MK |
73 | .I iovec |
74 | structures, | |
fea681da | 75 | defined in |
8a1dd514 | 76 | .I <sys/uio.h> |
ab44d3d6 | 77 | as: |
fea681da | 78 | .PP |
088a639b | 79 | .in +4n |
b8302363 | 80 | .EX |
fea681da | 81 | struct iovec { |
ab44d3d6 MK |
82 | void *iov_base; /* Starting address */ |
83 | size_t iov_len; /* Number of bytes to transfer */ | |
fea681da | 84 | }; |
b8302363 | 85 | .EE |
088a639b | 86 | .in |
fea681da | 87 | .PP |
fea681da | 88 | The |
8a1dd514 | 89 | .BR readv () |
e7d82451 | 90 | system call works just like |
fea681da MK |
91 | .BR read (2) |
92 | except that multiple buffers are filled. | |
93 | .PP | |
94 | The | |
8a1dd514 | 95 | .BR writev () |
e7d82451 | 96 | system call works just like |
fea681da MK |
97 | .BR write (2) |
98 | except that multiple buffers are written out. | |
ab44d3d6 MK |
99 | .PP |
100 | Buffers are processed in array order. | |
101 | This means that | |
102 | .BR readv () | |
103 | completely fills | |
e7ff7535 | 104 | .I iov[0] |
988db661 | 105 | before proceeding to |
e7ff7535 | 106 | .IR iov[1] , |
ab44d3d6 MK |
107 | and so on. |
108 | (If there is insufficient data, then not all buffers pointed to by | |
109 | .I iov | |
110 | may be filled.) | |
111 | Similarly, | |
112 | .BR writev () | |
113 | writes out the entire contents of | |
e7ff7535 | 114 | .I iov[0] |
988db661 | 115 | before proceeding to |
e7ff7535 | 116 | .IR iov[1] , |
ab44d3d6 MK |
117 | and so on. |
118 | .PP | |
119 | The data transfers performed by | |
120 | .BR readv () | |
121 | and | |
122 | .BR writev () | |
123 | are atomic: the data written by | |
6d8e9b7e | 124 | .\" Regarding atomicity, see https://bugzilla.kernel.org/show_bug.cgi?id=10596 |
ab44d3d6 MK |
125 | .BR writev () |
126 | is written as a single block that is not intermingled with output | |
9b94b63d | 127 | from writes in other processes; |
ab44d3d6 MK |
128 | analogously, |
129 | .BR readv () | |
130 | is guaranteed to read a contiguous block of data from the file, | |
131 | regardless of read operations performed in other threads or processes | |
132 | that have file descriptors referring to the same open file description | |
988db661 | 133 | (see |
ab44d3d6 | 134 | .BR open (2)). |
e0e3a6a3 MK |
135 | .SS preadv() and pwritev() |
136 | The | |
137 | .BR preadv () | |
138 | system call combines the functionality of | |
139 | .BR readv () | |
140 | and | |
141 | .BR pread (2). | |
142 | It performs the same task as | |
143 | .BR readv (), | |
144 | but adds a fourth argument, | |
145 | .IR offset , | |
146 | which specifies the file offset at which the input operation | |
147 | is to be performed. | |
efeece04 | 148 | .PP |
e0e3a6a3 MK |
149 | The |
150 | .BR pwritev () | |
151 | system call combines the functionality of | |
152 | .BR writev () | |
153 | and | |
bfd08d77 | 154 | .BR pwrite (2). |
e0e3a6a3 | 155 | It performs the same task as |
bfd08d77 | 156 | .BR writev (), |
e0e3a6a3 MK |
157 | but adds a fourth argument, |
158 | .IR offset , | |
159 | which specifies the file offset at which the output operation | |
160 | is to be performed. | |
efeece04 | 161 | .PP |
e0e3a6a3 MK |
162 | The file offset is not changed by these system calls. |
163 | The file referred to by | |
164 | .I fd | |
165 | must be capable of seeking. | |
d948a870 | 166 | .SS preadv2() and pwritev2() |
3b31ec64 | 167 | These system calls are similar to |
d948a870 CH |
168 | .BR preadv () |
169 | and | |
170 | .BR pwritev () | |
3b31ec64 MK |
171 | calls, but add a fifth argument, |
172 | .IR flags , | |
173 | which modifies the behavior on a per-call basis. | |
efeece04 | 174 | .PP |
3b31ec64 | 175 | Unlike |
d948a870 CH |
176 | .BR preadv () |
177 | and | |
3b31ec64 MK |
178 | .BR pwritev (), |
179 | if the | |
180 | .I offset | |
181 | argument is \-1, then the current file offset is used and updated. | |
efeece04 | 182 | .PP |
3b31ec64 MK |
183 | The |
184 | .I flags | |
185 | argument contains a bitwise OR of zero or more of the following flags: | |
d948a870 | 186 | .TP |
dae86017 | 187 | .BR RWF_DSYNC " (since Linux 4.7)" |
1e36b3c2 | 188 | .\" commit e864f39569f4092c2b2bc72c773b6e486c7e3bd9 |
dae86017 MK |
189 | Provide a per-write equivalent of the |
190 | .B O_DSYNC | |
191 | .BR open (2) | |
192 | flag. | |
193 | This flag is meaningful only for | |
5e43063b MK |
194 | .BR pwritev2 (), |
195 | and its effect applies only to the data range written by the system call. | |
dae86017 | 196 | .TP |
d948a870 | 197 | .BR RWF_HIPRI " (since Linux 4.6)" |
3b31ec64 MK |
198 | High priority read/write. |
199 | Allows block-based filesystems to use polling of the device, | |
200 | which provides lower latency, but may use additional resources. | |
201 | (Currently, this feature is usable only on a file descriptor opened using the | |
1ae6b2c7 | 202 | .B O_DIRECT |
3b31ec64 | 203 | flag.) |
dae86017 MK |
204 | .TP |
205 | .BR RWF_SYNC " (since Linux 4.7)" | |
1e36b3c2 | 206 | .\" commit e864f39569f4092c2b2bc72c773b6e486c7e3bd9 |
dae86017 MK |
207 | Provide a per-write equivalent of the |
208 | .B O_SYNC | |
209 | .BR open (2) | |
210 | flag. | |
211 | This flag is meaningful only for | |
5e43063b MK |
212 | .BR pwritev2 (), |
213 | and its effect applies only to the data range written by the system call. | |
fe20da96 CH |
214 | .TP |
215 | .BR RWF_NOWAIT " (since Linux 4.14)" | |
954136a1 MK |
216 | .\" commit 3239d834847627b6634a4139cf1dc58f6f137a46 |
217 | .\" commit 91f9943e1c7b6638f27312d03fe71fcc67b23571 | |
fe20da96 | 218 | Do not wait for data which is not immediately available. |
954136a1 | 219 | If this flag is specified, the |
fe20da96 CH |
220 | .BR preadv2 () |
221 | system call will return instantly if it would have to read data from | |
222 | the backing storage or wait for a lock. | |
223 | If some data was successfully read, it will return the number of bytes read. | |
0a23e9aa | 224 | If no bytes were read, it will return \-1 and set |
1ae6b2c7 | 225 | .I errno |
c6688cd1 | 226 | to |
1ae6b2c7 | 227 | .B EAGAIN |
f2ec5c2b | 228 | (but see |
f09b616d | 229 | .BR BUGS ). |
954136a1 MK |
230 | Currently, this flag is meaningful only for |
231 | .BR preadv2 (). | |
7ac27e31 JB |
232 | .TP |
233 | .BR RWF_APPEND " (since Linux 4.16)" | |
234 | .\" commit e1fc742e14e01d84d9693c4aca4ab23da65811fb | |
235 | Provide a per-write equivalent of the | |
236 | .B O_APPEND | |
237 | .BR open (2) | |
238 | flag. | |
239 | This flag is meaningful only for | |
240 | .BR pwritev2 (), | |
241 | and its effect applies only to the data range written by the system call. | |
242 | The | |
243 | .I offset | |
21487837 | 244 | argument does not affect the write operation; |
a6b64be7 MK |
245 | the data is always appended to the end of the file. |
246 | However, if the | |
7ac27e31 JB |
247 | .I offset |
248 | argument is \-1, the current file offset is updated. | |
47297adb | 249 | .SH RETURN VALUE |
9d04fbe5 | 250 | On success, |
3b31ec64 | 251 | .BR readv (), |
d556548b | 252 | .BR preadv (), |
e0e3a6a3 | 253 | and |
d948a870 CH |
254 | .BR preadv2 () |
255 | return the number of bytes read; | |
3b31ec64 | 256 | .BR writev (), |
d556548b | 257 | .BR pwritev (), |
d948a870 CH |
258 | and |
259 | .BR pwritev2 () | |
e0e3a6a3 | 260 | return the number of bytes written. |
efeece04 | 261 | .PP |
120fe216 | 262 | Note that it is not an error for a successful call to transfer fewer bytes |
77548009 MK |
263 | than requested (see |
264 | .BR read (2) | |
265 | and | |
266 | .BR write (2)). | |
efeece04 | 267 | .PP |
f6a4078b | 268 | On error, \-1 is returned, and \fIerrno\fP is set to indicate the error. |
fea681da MK |
269 | .SH ERRORS |
270 | The errors are as given for | |
271 | .BR read (2) | |
272 | and | |
273 | .BR write (2). | |
e0e3a6a3 | 274 | Furthermore, |
3b31ec64 MK |
275 | .BR preadv (), |
276 | .BR preadv2 (), | |
277 | .BR pwritev (), | |
d948a870 CH |
278 | and |
279 | .BR pwritev2 () | |
e0e3a6a3 MK |
280 | can also fail for the same reasons as |
281 | .BR lseek (2). | |
840dfaf0 | 282 | Additionally, the following errors are defined: |
fea681da MK |
283 | .TP |
284 | .B EINVAL | |
285 | The sum of the | |
286 | .I iov_len | |
287 | values overflows an | |
8a1dd514 | 288 | .I ssize_t |
c13182ef | 289 | value. |
bc9ed112 MK |
290 | .TP |
291 | .B EINVAL | |
3b31ec64 MK |
292 | The vector count, |
293 | .IR iovcnt , | |
294 | is less than zero or greater than the permitted maximum. | |
295 | .TP | |
63c1260a | 296 | .B EOPNOTSUPP |
3b31ec64 | 297 | An unknown flag is specified in \fIflags\fP. |
e0e3a6a3 MK |
298 | .SH VERSIONS |
299 | .BR preadv () | |
fea681da | 300 | and |
e0e3a6a3 MK |
301 | .BR pwritev () |
302 | first appeared in Linux 2.6.30; library support was added in glibc 2.10. | |
efeece04 | 303 | .PP |
d948a870 CH |
304 | .BR preadv2 () |
305 | and | |
306 | .BR pwritev2 () | |
9b601b66 | 307 | first appeared in Linux 4.6. |
32f5f044 | 308 | Library support was added in glibc 2.26. |
47297adb | 309 | .SH CONFORMING TO |
e0e3a6a3 MK |
310 | .BR readv (), |
311 | .BR writev (): | |
9c9c8ad1 MK |
312 | POSIX.1-2001, POSIX.1-2008, |
313 | 4.4BSD (these system calls first appeared in 4.2BSD). | |
0e8cfea7 MK |
314 | .\" Linux libc5 used \fIsize_t\fP as the type of the \fIiovcnt\fP argument, |
315 | .\" and \fIint\fP as the return type. | |
fea681da MK |
316 | .\" The readv/writev system calls were buggy before Linux 1.3.40. |
317 | .\" (Says release.libc.) | |
efeece04 | 318 | .PP |
e0e3a6a3 MK |
319 | .BR preadv (), |
320 | .BR pwritev (): | |
321 | nonstandard, but present also on the modern BSDs. | |
51f5698d | 322 | .PP |
d948a870 CH |
323 | .BR preadv2 (), |
324 | .BR pwritev2 (): | |
3b31ec64 | 325 | nonstandard Linux extension. |
4fb31341 | 326 | .SH NOTES |
9c9c8ad1 | 327 | POSIX.1 allows an implementation to place a limit on |
97c1eac8 | 328 | the number of items that can be passed in |
ab44d3d6 | 329 | .IR iov . |
8a1dd514 MK |
330 | An implementation can advertise its limit by defining |
331 | .B IOV_MAX | |
332 | in | |
0daa9e92 | 333 | .I <limits.h> |
8a1dd514 MK |
334 | or at run time via the return value from |
335 | .IR sysconf(_SC_IOV_MAX) . | |
8a930bf1 MK |
336 | On modern Linux systems, the limit is 1024. |
337 | Back in Linux 2.0 days, this limit was 16. | |
def04e1c MK |
338 | .\" |
339 | .\" | |
0722a578 | 340 | .SS C library/kernel differences |
8b5857b0 MK |
341 | The raw |
342 | .BR preadv () | |
343 | and | |
344 | .BR pwritev () | |
345 | system calls have call signatures that differ slightly from that of the | |
346 | corresponding GNU C library wrapper functions shown in the SYNOPSIS. | |
347 | The final argument, | |
348 | .IR offset , | |
349 | is unpacked by the wrapper functions into two arguments in the system calls: | |
efeece04 | 350 | .PP |
8b5857b0 | 351 | .BI " unsigned long " pos_l ", unsigned long " pos |
efeece04 | 352 | .PP |
8b5857b0 MK |
353 | These arguments contain, respectively, the low order and high order 32 bits of |
354 | .IR offset . | |
0722a578 | 355 | .SS Historical C library/kernel differences |
8a930bf1 MK |
356 | To deal with the fact that |
357 | .B IOV_MAX | |
358 | was so low on early versions of Linux, | |
359 | the glibc wrapper functions for | |
360 | .BR readv () | |
361 | and | |
362 | .BR writev () | |
363 | did some extra work if they detected that the underlying kernel | |
364 | system call failed because this limit was exceeded. | |
c13182ef | 365 | In the case of |
4213c13e | 366 | .BR readv (), |
8a930bf1 | 367 | the wrapper function allocated a temporary buffer large enough |
8a1dd514 | 368 | for all of the items specified by |
ab44d3d6 | 369 | .IR iov , |
8a930bf1 | 370 | passed that buffer in a call to |
0bfa087b | 371 | .BR read (2), |
8a930bf1 | 372 | copied data from the buffer to the locations specified by the |
8a1dd514 | 373 | .I iov_base |
c13182ef | 374 | fields of the elements of |
ab44d3d6 | 375 | .IR iov , |
8a930bf1 | 376 | and then freed the buffer. |
8a1dd514 MK |
377 | The wrapper function for |
378 | .BR writev () | |
8a930bf1 | 379 | performed the analogous task using a temporary buffer and a call to |
0bfa087b | 380 | .BR write (2). |
efeece04 | 381 | .PP |
8a930bf1 MK |
382 | The need for this extra effort in the glibc wrapper functions |
383 | went away with Linux 2.2 and later. | |
384 | However, glibc continued to provide this behavior until version 2.10. | |
385 | Starting with glibc version 2.9, | |
386 | the wrapper functions provide this behavior only if the library detects | |
387 | that the system is running a Linux kernel older than version 2.6.18 | |
388 | (an arbitrarily selected kernel version). | |
389 | And since glibc 2.20 | |
390 | (which requires a minimum Linux kernel version of 2.6.32), | |
391 | the glibc wrapper functions always just directly invoke the system calls. | |
dae872dd MK |
392 | .SH BUGS |
393 | Linux 5.9 and 5.10 have a bug where | |
1ae6b2c7 | 394 | .BR preadv2 () |
dae872dd | 395 | with the |
1ae6b2c7 | 396 | .B RWF_NOWAIT |
dae872dd MK |
397 | flag may return 0 even when not at end of file. |
398 | .\" See | |
399 | .\" <https://lore.kernel.org/linux-fsdevel/fea8b16d-5a69-40f9-b123-e84dcd6e8f2e@www.fastmail.com/T/#u> | |
400 | .\" The bug was introduced in | |
401 | .\" efa8480a831 fs: RWF_NOWAIT should imply IOCB_NOIO | |
402 | .\"and fixed in | |
403 | .\" 06c0444290 mm/filemap.c: generic_file_buffered_read() now uses find_get_pages_contig | |
a14af333 | 404 | .SH EXAMPLES |
ab44d3d6 MK |
405 | The following code sample demonstrates the use of |
406 | .BR writev (): | |
efeece04 | 407 | .PP |
088a639b | 408 | .in +4n |
b8302363 | 409 | .EX |
ab44d3d6 | 410 | char *str0 = "hello "; |
d1a71985 | 411 | char *str1 = "world\en"; |
ab44d3d6 MK |
412 | struct iovec iov[2]; |
413 | ssize_t nwritten; | |
414 | ||
415 | iov[0].iov_base = str0; | |
416 | iov[0].iov_len = strlen(str0); | |
417 | iov[1].iov_base = str1; | |
418 | iov[1].iov_len = strlen(str1); | |
419 | ||
420 | nwritten = writev(STDOUT_FILENO, iov, 2); | |
b8302363 | 421 | .EE |
ab44d3d6 | 422 | .in |
47297adb | 423 | .SH SEE ALSO |
e0e3a6a3 | 424 | .BR pread (2), |
fea681da MK |
425 | .BR read (2), |
426 | .BR write (2) |