Debian Codegraph @

upstream/debian-trixie/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 2024-06-15 "Linux man-pages 6.9.1"
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 .SH RETURN VALUE
241 On success,
242 .BR readv (),
243 .BR preadv (),
244 and
245 .BR preadv2 ()
246 return the number of bytes read;
247 .BR writev (),
248 .BR pwritev (),
249 and
250 .BR pwritev2 ()
251 return the number of bytes written.
252 .P
253 Note that it is not an error for a successful call to transfer fewer bytes
254 than requested (see
255 .BR read (2)
256 and
257 .BR write (2)).
258 .P
259 On error, \-1 is returned, and \fIerrno\fP is set to indicate the error.
260 .SH ERRORS
261 The errors are as given for
262 .BR read (2)
263 and
264 .BR write (2).
265 Furthermore,
266 .BR preadv (),
267 .BR preadv2 (),
268 .BR pwritev (),
269 and
270 .BR pwritev2 ()
271 can also fail for the same reasons as
272 .BR lseek (2).
273 Additionally, the following errors are defined:
274 .TP
275 .B EINVAL
276 The sum of the
277 .I iov_len
278 values overflows an
279 .I ssize_t
280 value.
281 .TP
282 .B EINVAL
283 The vector count,
284 .IR iovcnt ,
285 is less than zero or greater than the permitted maximum.
286 .TP
287 .B EOPNOTSUPP
288 An unknown flag is specified in \fIflags\fP.
289 .SH VERSIONS
290 .SS C library/kernel differences
291 The raw
292 .BR preadv ()
293 and
294 .BR pwritev ()
295 system calls have call signatures that differ slightly from that of the
296 corresponding GNU C library wrapper functions shown in the SYNOPSIS.
297 The final argument,
298 .IR offset ,
299 is unpacked by the wrapper functions into two arguments in the system calls:
300 .P
301 .BI " unsigned long " pos_l ", unsigned long " pos
302 .P
303 These arguments contain, respectively, the low order and high order 32 bits of
304 .IR offset .
305 .SH STANDARDS
306 .TP
307 .BR readv ()
308 .TQ
309 .BR writev ()
310 POSIX.1-2008.
311 .TP
312 .BR preadv ()
313 .TQ
314 .BR pwritev ()
315 BSD.
316 .TP
317 .BR preadv2 ()
318 .TQ
319 .BR pwritev2 ()
320 Linux.
321 .SH HISTORY
322 .TP
323 .BR readv ()
324 .TQ
325 .BR writev ()
326 POSIX.1-2001,
327 4.4BSD (first appeared in 4.2BSD).
328 .\" Linux libc5 used \fIsize_t\fP as the type of the \fIiovcnt\fP argument,
329 .\" and \fIint\fP as the return type.
330 .\" The readv/writev system calls were buggy before Linux 1.3.40.
331 .\" (Says release.libc.)
332 .P
333 .BR preadv (),
334 .BR pwritev ():
335 Linux 2.6.30,
336 glibc 2.10.
337 .P
338 .BR preadv2 (),
339 .BR pwritev2 ():
340 Linux 4.6,
341 glibc 2.26.
342 .SS Historical C library/kernel differences
343 To deal with the fact that
344 .B IOV_MAX
345 was so low on early versions of Linux,
346 the glibc wrapper functions for
347 .BR readv ()
348 and
349 .BR writev ()
350 did some extra work if they detected that the underlying kernel
351 system call failed because this limit was exceeded.
352 In the case of
353 .BR readv (),
354 the wrapper function allocated a temporary buffer large enough
355 for all of the items specified by
356 .IR iov ,
357 passed that buffer in a call to
358 .BR read (2),
359 copied data from the buffer to the locations specified by the
360 .I iov_base
361 fields of the elements of
362 .IR iov ,
363 and then freed the buffer.
364 The wrapper function for
365 .BR writev ()
366 performed the analogous task using a temporary buffer and a call to
367 .BR write (2).
368 .P
369 The need for this extra effort in the glibc wrapper functions
370 went away with Linux 2.2 and later.
371 However, glibc continued to provide this behavior until glibc 2.10.
372 Starting with glibc 2.9,
373 the wrapper functions provide this behavior only if the library detects
374 that the system is running a Linux kernel older than Linux 2.6.18
375 (an arbitrarily selected kernel version).
376 And since glibc 2.20
377 (which requires a minimum of Linux 2.6.32),
378 the glibc wrapper functions always just directly invoke the system calls.
379 .SH NOTES
380 POSIX.1 allows an implementation to place a limit on
381 the number of items that can be passed in
382 .IR iov .
383 An implementation can advertise its limit by defining
384 .B IOV_MAX
385 in
386 .I <limits.h>
387 or at run time via the return value from
388 .IR sysconf(_SC_IOV_MAX) .
389 On modern Linux systems, the limit is 1024.
390 Back in Linux 2.0 days, this limit was 16.
391 .\"
392 .\"
393 .SH BUGS
394 Linux 5.9 and Linux 5.10 have a bug where
395 .BR preadv2 ()
396 with the
397 .B RWF_NOWAIT
398 flag may return 0 even when not at end of file.
399 .\" See
400 .\" <https://lore.kernel.org/linux-fsdevel/[email protected]/T/#u>
401 .\" The bug was introduced in
402 .\" efa8480a831 fs: RWF_NOWAIT should imply IOCB_NOIO
403 .\"and fixed in
404 .\" 06c0444290 mm/filemap.c: generic_file_buffered_read() now uses find_get_pages_contig
405 .SH EXAMPLES
406 The following code sample demonstrates the use of
407 .BR writev ():
408 .P
409 .in +4n
410 .EX
411 char *str0 = "hello ";
412 char *str1 = "world\[rs]n";
413 ssize_t nwritten;
414 struct iovec iov[2];
415 \&
416 iov[0].iov_base = str0;
417 iov[0].iov_len = strlen(str0);
418 iov[1].iov_base = str1;
419 iov[1].iov_len = strlen(str1);
420 \&
421 nwritten = writev(STDOUT_FILENO, iov, 2);
422 .EE
423 .in
424 .SH SEE ALSO
425 .BR pread (2),
426 .BR read (2),
427 .BR write (2)