1 .\" Copyright (C) 2007, 2010 Michael Kerrisk <mtk.manpages@gmail.com>
2 .\" and Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de)
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.
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.
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
22 .\" Formatted or processed versions of this manual, if unaccompanied by
23 .\" the source, must acknowledge the copyright and authors of this work.
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
30 .\" 2010-11-16, mtk, Added documentation of preadv() and pwritev()
32 .TH READV 2 2018-04-30 "Linux" "Linux Programmer's Manual"
34 readv, writev, preadv, pwritev, preadv2, pwritev2 \- read or write data into multiple buffers
37 .B #include <sys/uio.h>
39 .BI "ssize_t readv(int " fd ", const struct iovec *" iov ", int " iovcnt );
41 .BI "ssize_t writev(int " fd ", const struct iovec *" iov ", int " iovcnt );
43 .BI "ssize_t preadv(int " fd ", const struct iovec *" iov ", int " iovcnt ,
44 .BI " off_t " offset );
46 .BI "ssize_t pwritev(int " fd ", const struct iovec *" iov ", int " iovcnt ,
47 .BI " off_t " offset );
49 .BI "ssize_t preadv2(int " fd ", const struct iovec *" iov ", int " iovcnt ,
50 .BI " off_t " offset ", int " flags );
52 .BI "ssize_t pwritev2(int " fd ", const struct iovec *" iov ", int " iovcnt ,
53 .BI " off_t " offset ", int " flags );
57 Feature Test Macro Requirements for glibc (see
58 .BR feature_test_macros (7)):
65 Glibc 2.19 and earlier:
72 buffers from the file associated with the file descriptor
74 into the buffers described by
82 buffers of data described by
84 to the file associated with the file descriptor
100 void *iov_base; /* Starting address */
101 size_t iov_len; /* Number of bytes to transfer */
108 system call works just like
110 except that multiple buffers are filled.
114 system call works just like
116 except that multiple buffers are written out.
118 Buffers are processed in array order.
126 (If there is insufficient data, then not all buffers pointed to by
131 writes out the entire contents of
137 The data transfers performed by
141 are atomic: the data written by
142 .\" Regarding atomicity, see https://bugzilla.kernel.org/show_bug.cgi?id=10596
144 is written as a single block that is not intermingled with output
145 from writes in other processes (but see
150 is guaranteed to read a contiguous block of data from the file,
151 regardless of read operations performed in other threads or processes
152 that have file descriptors referring to the same open file description
155 .SS preadv() and pwritev()
158 system call combines the functionality of
162 It performs the same task as
164 but adds a fourth argument,
166 which specifies the file offset at which the input operation
171 system call combines the functionality of
175 It performs the same task as
177 but adds a fourth argument,
179 which specifies the file offset at which the output operation
182 The file offset is not changed by these system calls.
183 The file referred to by
185 must be capable of seeking.
186 .SS preadv2() and pwritev2()
188 These system calls are similar to
192 calls, but add a fifth argument,
194 which modifies the behavior on a per-call basis.
202 argument is \-1, then the current file offset is used and updated.
206 argument contains a bitwise OR of zero or more of the following flags:
208 .BR RWF_DSYNC " (since Linux 4.7)"
209 .\" commit e864f39569f4092c2b2bc72c773b6e486c7e3bd9
210 Provide a per-write equivalent of the
214 This flag is meaningful only for
216 and its effect applies only to the data range written by the system call.
218 .BR RWF_HIPRI " (since Linux 4.6)"
219 High priority read/write.
220 Allows block-based filesystems to use polling of the device,
221 which provides lower latency, but may use additional resources.
222 (Currently, this feature is usable only on a file descriptor opened using the
226 .BR RWF_SYNC " (since Linux 4.7)"
227 .\" commit e864f39569f4092c2b2bc72c773b6e486c7e3bd9
228 Provide a per-write equivalent of the
232 This flag is meaningful only for
234 and its effect applies only to the data range written by the system call.
236 .BR RWF_NOWAIT " (since Linux 4.14)"
237 .\" commit 3239d834847627b6634a4139cf1dc58f6f137a46
238 .\" commit 91f9943e1c7b6638f27312d03fe71fcc67b23571
239 Do not wait for data which is not immediately available.
240 If this flag is specified, the
242 system call will return instantly if it would have to read data from
243 the backing storage or wait for a lock.
244 If some data was successfully read, it will return the number of bytes read.
245 If no bytes were read, it will return -1 and set
249 Currently, this flag is meaningful only for
252 .BR RWF_APPEND " (since Linux 4.16)"
253 .\" commit e1fc742e14e01d84d9693c4aca4ab23da65811fb
254 Provide a per-write equivalent of the
258 This flag is meaningful only for
260 and its effect applies only to the data range written by the system call.
263 argument does not affect the write operation;
264 the data is always appended to the end of the file.
267 argument is \-1, the current file offset is updated.
274 return the number of bytes read;
279 return the number of bytes written.
281 Note that it is not an error for a successful call to transfer fewer bytes
287 On error, \-1 is returned, and \fIerrno\fP is set appropriately.
289 The errors are as given for
299 can also fail for the same reasons as
301 Additionally, the following errors are defined:
313 is less than zero or greater than the permitted maximum.
316 An unknown flag is specified in \fIflags\fP.
321 first appeared in Linux 2.6.30; library support was added in glibc 2.10.
326 first appeared in Linux 4.6.
327 Library support was added in glibc 2.26.
331 POSIX.1-2001, POSIX.1-2008,
332 4.4BSD (these system calls first appeared in 4.2BSD).
333 .\" Linux libc5 used \fIsize_t\fP as the type of the \fIiovcnt\fP argument,
334 .\" and \fIint\fP as the return type.
335 .\" The readv/writev system calls were buggy before Linux 1.3.40.
336 .\" (Says release.libc.)
340 nonstandard, but present also on the modern BSDs.
344 nonstandard Linux extension.
346 POSIX.1 allows an implementation to place a limit on
347 the number of items that can be passed in
349 An implementation can advertise its limit by defining
353 or at run time via the return value from
354 .IR sysconf(_SC_IOV_MAX) .
355 On modern Linux systems, the limit is 1024.
356 Back in Linux 2.0 days, this limit was 16.
359 .SS C library/kernel differences
364 system calls have call signatures that differ slightly from that of the
365 corresponding GNU C library wrapper functions shown in the SYNOPSIS.
368 is unpacked by the wrapper functions into two arguments in the system calls:
370 .BI " unsigned long " pos_l ", unsigned long " pos
372 These arguments contain, respectively, the low order and high order 32 bits of
374 .SS Historical C library/kernel differences
375 To deal with the fact that
377 was so low on early versions of Linux,
378 the glibc wrapper functions for
382 did some extra work if they detected that the underlying kernel
383 system call failed because this limit was exceeded.
386 the wrapper function allocated a temporary buffer large enough
387 for all of the items specified by
389 passed that buffer in a call to
391 copied data from the buffer to the locations specified by the
393 fields of the elements of
395 and then freed the buffer.
396 The wrapper function for
398 performed the analogous task using a temporary buffer and a call to
401 The need for this extra effort in the glibc wrapper functions
402 went away with Linux 2.2 and later.
403 However, glibc continued to provide this behavior until version 2.10.
404 Starting with glibc version 2.9,
405 the wrapper functions provide this behavior only if the library detects
406 that the system is running a Linux kernel older than version 2.6.18
407 (an arbitrarily selected kernel version).
409 (which requires a minimum Linux kernel version of 2.6.32),
410 the glibc wrapper functions always just directly invoke the system calls.
412 The following code sample demonstrates the use of
417 char *str0 = "hello ";
418 char *str1 = "world\en";
422 iov[0].iov_base = str0;
423 iov[0].iov_len = strlen(str0);
424 iov[1].iov_base = str1;
425 iov[1].iov_len = strlen(str1);
427 nwritten = writev(STDOUT_FILENO, iov, 2);