Debian Codegraph @

upstream/fedora-44/man2/readv.2

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