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