Debian Codegraph @

upstream/debian-unstable/man2/readv.2

raw
1 .\" Copyright 1993, Thomas Koenig <[email protected]>
2 .\" Copyright 2007-2010, Michael Kerrisk <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH readv 2 2026-02-22 "Linux man-pages 6.18"
8 .SH NAME
9 readv, writev, preadv, pwritev, preadv2, pwritev2 \-
10 read or write data into multiple buffers
11 .SH LIBRARY
12 Standard C library
13 .RI ( libc ,\~ \-lc )
14 .SH SYNOPSIS
15 .nf
16 .B #include <sys/uio.h>
17 .P
18 .BI "ssize_t readv(int " fd ", const struct iovec *" iov ", int " iovcnt );
19 .BI "ssize_t writev(int " fd ", const struct iovec *" iov ", int " iovcnt );
20 .P
21 .BI "ssize_t preadv(int " fd ", const struct iovec *" iov ", int " iovcnt ,
22 .BI " off_t " offset );
23 .BI "ssize_t pwritev(int " fd ", const struct iovec *" iov ", int " iovcnt ,
24 .BI " off_t " offset );
25 .P
26 .BI "ssize_t preadv2(int " fd ", const struct iovec *" iov ", int " iovcnt ,
27 .BI " off_t " offset ", int " flags );
28 .BI "ssize_t pwritev2(int " fd ", const struct iovec *" iov ", int " iovcnt ,
29 .BI " off_t " offset ", int " flags );
30 .fi
31 .P
32 .RS -4
33 Feature Test Macro Requirements for glibc (see
34 .BR feature_test_macros (7)):
35 .RE
36 .P
37 .BR preadv (),
38 .BR pwritev ():
39 .nf
40 Since glibc 2.19:
41 _DEFAULT_SOURCE
42 glibc 2.19 and earlier:
43 _BSD_SOURCE
44 .fi
45 .SH DESCRIPTION
46 The
47 .BR readv ()
48 system call reads
49 .I iovcnt
50 buffers from the file associated with the file descriptor
51 .I fd
52 into the buffers described by
53 .I iov
54 ("scatter input").
55 .P
56 The
57 .BR writev ()
58 system call writes
59 .I iovcnt
60 buffers of data described by
61 .I iov
62 to the file associated with the file descriptor
63 .I fd
64 ("gather output").
65 .P
66 The pointer
67 .I iov
68 points to an array of
69 .I iovec
70 structures,
71 described in
72 .BR iovec (3type).
73 .P
74 The
75 .BR readv ()
76 system call works just like
77 .BR read (2)
78 except that multiple buffers are filled.
79 .P
80 The
81 .BR writev ()
82 system call works just like
83 .BR write (2)
84 except that multiple buffers are written out.
85 .P
86 Buffers are processed in array order.
87 This means that
88 .BR readv ()
89 completely fills
90 .I iov[0]
91 before proceeding to
92 .IR iov[1] ,
93 and so on.
94 (If there is insufficient data, then not all buffers pointed to by
95 .I iov
96 may be filled.)
97 Similarly,
98 .BR writev ()
99 writes out the entire contents of
100 .I iov[0]
101 before proceeding to
102 .IR iov[1] ,
103 and so on.
104 .P
105 The data transfers performed by
106 .BR readv ()
107 and
108 .BR writev ()
109 are atomic: the data written by
110 .\" Regarding atomicity, see https://bugzilla.kernel.org/show_bug.cgi?id=10596
111 .BR writev ()
112 is written as a single block that is not intermingled with output
113 from writes in other processes;
114 analogously,
115 .BR readv ()
116 is guaranteed to read a contiguous block of data from the file,
117 regardless of read operations performed in other threads or processes
118 that have file descriptors referring to the same open file description
119 (see
120 .BR open (2)).
121 .SS preadv() and pwritev()
122 The
123 .BR preadv ()
124 system call combines the functionality of
125 .BR readv ()
126 and
127 .BR pread (2).
128 It performs the same task as
129 .BR readv (),
130 but adds a fourth argument,
131 .IR offset ,
132 which specifies the file offset at which the input operation
133 is to be performed.
134 .P
135 The
136 .BR pwritev ()
137 system call combines the functionality of
138 .BR writev ()
139 and
140 .BR pwrite (2).
141 It performs the same task as
142 .BR writev (),
143 but adds a fourth argument,
144 .IR offset ,
145 which specifies the file offset at which the output operation
146 is to be performed.
147 .P
148 The file offset is not changed by these system calls.
149 The file referred to by
150 .I fd
151 must be capable of seeking.
152 .SS preadv2() and pwritev2()
153 These system calls are similar to
154 .BR preadv ()
155 and
156 .BR pwritev ()
157 calls, but add a fifth argument,
158 .IR flags ,
159 which modifies the behavior on a per-call basis.
160 .P
161 Unlike
162 .BR preadv ()
163 and
164 .BR pwritev (),
165 if the
166 .I offset
167 argument is \-1, then the current file offset is used and updated.
168 .P
169 The
170 .I flags
171 argument contains a bitwise OR of zero or more of the following flags:
172 .TP
173 .BR RWF_DSYNC " (since Linux 4.7)"
174 .\" commit e864f39569f4092c2b2bc72c773b6e486c7e3bd9
175 Provide a per-write equivalent of the
176 .B O_DSYNC
177 .BR open (2)
178 flag.
179 This flag is meaningful only for
180 .BR pwritev2 (),
181 and its effect applies only to the data range written by the system call.
182 .TP
183 .BR RWF_HIPRI " (since Linux 4.6)"
184 High priority read/write.
185 Allows block-based filesystems to use polling of the device,
186 which provides lower latency, but may use additional resources.
187 (Currently, this feature is usable only on a file descriptor opened using the
188 .B O_DIRECT
189 flag.)
190 .TP
191 .BR RWF_SYNC " (since Linux 4.7)"
192 .\" commit e864f39569f4092c2b2bc72c773b6e486c7e3bd9
193 Provide a per-write equivalent of the
194 .B O_SYNC
195 .BR open (2)
196 flag.
197 This flag is meaningful only for
198 .BR pwritev2 (),
199 and its effect applies only to the data range written by the system call.
200 .TP
201 .BR RWF_NOWAIT " (since Linux 4.14)"
202 .\" commit 3239d834847627b6634a4139cf1dc58f6f137a46
203 .\" commit 91f9943e1c7b6638f27312d03fe71fcc67b23571
204 Do not wait for data which is not immediately available.
205 If this flag is specified, the
206 .BR preadv2 ()
207 system call will return instantly if it would have to read data from
208 the backing storage or wait for a lock.
209 If some data was successfully read, it will return the number of bytes read.
210 If no bytes were read, it will return \-1 and set
211 .I errno
212 to
213 .B EAGAIN
214 (but see
215 .BR BUGS ).
216 Currently, this flag is meaningful only for
217 .BR preadv2 ().
218 .TP
219 .BR RWF_APPEND " (since Linux 4.16)"
220 .\" commit e1fc742e14e01d84d9693c4aca4ab23da65811fb
221 Provide a per-write equivalent of the
222 .B O_APPEND
223 .BR open (2)
224 flag.
225 This flag is meaningful only for
226 .BR pwritev2 (),
227 and its effect applies only to the data range written by the system call.
228 The
229 .I offset
230 argument does not affect the write operation;
231 the data is always appended to the end of the file.
232 However, if the
233 .I offset
234 argument is \-1, the current file offset is updated.
235 .TP
236 .BR RWF_NOAPPEND " (since Linux 6.9)"
237 Do not honor the
238 .B O_APPEND
239 .BR open (2)
240 flag.
241 This flag is meaningful only for
242 .BR pwritev2 ().
243 Historically,
244 Linux honored
245 .B O_APPEND
246 flag if set and ignored the offset argument,
247 which is a bug.
248 For
249 .BR pwritev2 (),
250 the
251 .I offset
252 argument is honored as expected if
253 .B RWF_NOAPPEND
254 flag is set,
255 the same as if
256 .B O_APPEND
257 flag were not set.
258 .TP
259 .BR RWF_ATOMIC " (since Linux 6.11)"
260 Requires that
261 writes to regular files in block-based filesystems
262 be issued with torn-write protection.
263 Torn-write protection means that
264 for a power or any other hardware failure,
265 all or none of the data from the write will be stored,
266 but never a mix of old and new data.
267 This flag is meaningful only for
268 .BR pwritev2 (),
269 and its effect applies only to
270 the data range written by the system call.
271 The total write length must be power-of-2
272 and must be sized in the range
273 .RI [ stx_atomic_write_unit_min ,
274 .IR stx_atomic_write_unit_max ].
275 The write must be at a naturally-aligned offset within the file
276 with respect to the total write length.
277 For example,
278 a write of length 32KiB at a file offset of 32KiB is permitted,
279 however a write of length 32KiB at a file offset of 48KiB is not permitted.
280 The upper limit of
281 .I iovcnt
282 for
283 .BR pwritev2 ()
284 is given by the value in
285 .I stx_atomic_write_segments_max.
286 Torn-write protection only works with
287 .B O_DIRECT
288 flag,
289 that is,
290 buffered writes are not supported.
291 To guarantee consistency from the write
292 between a file's in-core state
293 with the storage device,
294 .B O_SYNC
295 or
296 .B O_DSYNC
297 must be specified for
298 .BR open (2).
299 The same synchronized I/O guarantees as described in
300 .BR open (2)
301 are provided when these flags
302 or their equivalent flags and system calls are used
303 (e.g., if
304 .B RWF_SYNC
305 is specified for
306 .BR pwritev2 ()).
307 .TP
308 .BR RWF_DONTCACHE " (since Linux 6.14)"
309 Reads or writes to a regular file
310 will prune instantiated page cache content
311 when the operation completes.
312 This is different than normal buffered I/O,
313 where the data usually remains in cache
314 until such time that it gets reclaimed
315 due to memory pressure.
316 If ranges of the read or written I/O
317 were already in cache before this read or write,
318 then those ranges will not be pruned at I/O completion time.
319 .IP
320 Additionally,
321 any range dirtied by a write operation with
322 .B RWF_DONTCACHE
323 set will get kicked off for writeback.
324 This is similar to calling
325 .BR sync_file_range (2)
326 with
327 .I SYNC_FILE_RANGE_WRITE
328 to start writeback on the given range.
329 .B RWF_DONTCACHE
330 is a hint, or best effort,
331 where no hard guarantees are given on the state of the page cache
332 once the operation completes.
333 .IP
334 If used on a file system or block device
335 that doesn't support it,
336 it will return \-1, and
337 .I errno
338 will be set to
339 .BR EOPNOTSUPP .
340 .SH RETURN VALUE
341 On success,
342 .BR readv (),
343 .BR preadv (),
344 and
345 .BR preadv2 ()
346 return the number of bytes read;
347 .BR writev (),
348 .BR pwritev (),
349 and
350 .BR pwritev2 ()
351 return the number of bytes written.
352 .P
353 Note that it is not an error for a successful call to transfer fewer bytes
354 than requested (see
355 .BR read (2)
356 and
357 .BR write (2)).
358 .P
359 On error, \-1 is returned, and
360 .I errno
361 is set to indicate the error.
362 .SH ERRORS
363 The errors are as given for
364 .BR read (2)
365 and
366 .BR write (2).
367 Furthermore,
368 .BR preadv (),
369 .BR preadv2 (),
370 .BR pwritev (),
371 and
372 .BR pwritev2 ()
373 can also fail for the same reasons as
374 .BR lseek (2).
375 Additionally, the following errors are defined:
376 .TP
377 .B EINVAL
378 The sum of the
379 .I iov_len
380 values overflows an
381 .I ssize_t
382 value.
383 .TP
384 .B EINVAL
385 If
386 .B RWF_ATOMIC
387 is specified,
388 the combination of the sum of the
389 .I iov_len
390 values and the
391 .I offset
392 value does not comply with the length and offset torn-write protection rules.
393 .TP
394 .B EINVAL
395 The vector count,
396 .IR iovcnt ,
397 is less than zero or greater than the permitted maximum.
398 If
399 .B RWF_ATOMIC
400 is specified,
401 this maximum is given by the
402 .I stx_atomic_write_segments_max
403 value from
404 .I statx.
405 .TP
406 .B EOPNOTSUPP
407 .B RWF_DONTCACHE
408 was set in
409 .I flags
410 and the file doesn't support it.
411 .TP
412 .B EOPNOTSUPP
413 An unknown flag is specified in
414 .IR flags .
415 .SH VERSIONS
416 .SS C library/kernel differences
417 The raw
418 .BR preadv ()
419 and
420 .BR pwritev ()
421 system calls have call signatures that differ slightly from that of the
422 corresponding GNU C library wrapper functions shown in the SYNOPSIS.
423 The final argument,
424 .IR offset ,
425 is unpacked by the wrapper functions into two arguments in the system calls:
426 .P
427 .BI " unsigned long " pos_l ", unsigned long " pos
428 .P
429 These arguments contain, respectively, the low order and high order 32 bits of
430 .IR offset .
431 .SH STANDARDS
432 .TP
433 .BR readv ()
434 .TQ
435 .BR writev ()
436 POSIX.1-2024.
437 .TP
438 .BR preadv ()
439 .TQ
440 .BR pwritev ()
441 BSD.
442 .TP
443 .BR preadv2 ()
444 .TQ
445 .BR pwritev2 ()
446 Linux.
447 .SH HISTORY
448 .TP
449 .BR readv ()
450 .TQ
451 .BR writev ()
452 POSIX.1-2001,
453 4.4BSD (first appeared in 4.2BSD).
454 .\" Linux libc5 used
455 .\" .I size_t
456 .\" as the type of the
457 .\" .I iovcnt
458 .\" argument,
459 .\" and
460 .\" .I int
461 .\" as the return type.
462 .\" The readv/writev system calls were buggy before Linux 1.3.40.
463 .\" (Says release.libc.)
464 .TP
465 .BR preadv ()
466 .TQ
467 .BR pwritev ()
468 Linux 2.6.30,
469 glibc 2.10.
470 .TP
471 .BR preadv2 ()
472 .TQ
473 .BR pwritev2 ()
474 Linux 4.6,
475 glibc 2.26.
476 .SS Historical C library/kernel differences
477 To deal with the fact that
478 .B IOV_MAX
479 was so low on early versions of Linux,
480 the glibc wrapper functions for
481 .BR readv ()
482 and
483 .BR writev ()
484 did some extra work if they detected that the underlying kernel
485 system call failed because this limit was exceeded.
486 In the case of
487 .BR readv (),
488 the wrapper function allocated a temporary buffer large enough
489 for all of the items specified by
490 .IR iov ,
491 passed that buffer in a call to
492 .BR read (2),
493 copied data from the buffer to the locations specified by the
494 .I iov_base
495 fields of the elements of
496 .IR iov ,
497 and then freed the buffer.
498 The wrapper function for
499 .BR writev ()
500 performed the analogous task using a temporary buffer and a call to
501 .BR write (2).
502 .P
503 The need for this extra effort in the glibc wrapper functions
504 went away with Linux 2.2 and later.
505 However, glibc continued to provide this behavior until glibc 2.10.
506 Starting with glibc 2.9,
507 the wrapper functions provide this behavior only if the library detects
508 that the system is running a Linux kernel older than Linux 2.6.18
509 (an arbitrarily selected kernel version).
510 And since glibc 2.20
511 (which requires a minimum of Linux 2.6.32),
512 the glibc wrapper functions always just directly invoke the system calls.
513 .SH NOTES
514 POSIX.1 allows an implementation to place a limit on
515 the number of items that can be passed in
516 .IR iov .
517 An implementation can advertise its limit by defining
518 .B IOV_MAX
519 in
520 .I <limits.h>
521 or at run time via the return value from
522 .IR sysconf(_SC_IOV_MAX) .
523 On modern Linux systems, the limit is 1024.
524 Back in Linux 2.0 days, this limit was 16.
525 .\"
526 .\"
527 .SH BUGS
528 Linux 5.9 and Linux 5.10 have a bug where
529 .BR preadv2 ()
530 with the
531 .B RWF_NOWAIT
532 flag may return 0 even when not at end of file.
533 .\" See
534 .\" <https://lore.kernel.org/linux-fsdevel/[email protected]/T/#u>
535 .\" The bug was introduced in
536 .\" efa8480a831 fs: RWF_NOWAIT should imply IOCB_NOIO
537 .\"and fixed in
538 .\" 06c0444290 mm/filemap.c: generic_file_buffered_read() now uses find_get_pages_contig
539 .SH EXAMPLES
540 The following code sample demonstrates the use of
541 .BR writev ():
542 .P
543 .in +4n
544 .EX
545 char *str0 = "hello ";
546 char *str1 = "world\[rs]n";
547 ssize_t nwritten;
548 struct iovec iov[2];
549 \&
550 iov[0].iov_base = str0;
551 iov[0].iov_len = strlen(str0);
552 iov[1].iov_base = str1;
553 iov[1].iov_len = strlen(str1);
554 \&
555 nwritten = writev(STDOUT_FILENO, iov, 2);
556 .EE
557 .in
558 .SH SEE ALSO
559 .BR pread (2),
560 .BR read (2),
561 .BR write (2)