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 2015-01-22 "Linux" "Linux Programmer's Manual"
34 readv, writev, preadv, pwritev \- 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 );
51 Feature Test Macro Requirements for glibc (see
52 .BR feature_test_macros (7)):
63 buffers from the file associated with the file descriptor
65 into the buffers described by
73 buffers of data described by
75 to the file associated with the file descriptor
92 void *iov_base; /* Starting address */
93 size_t iov_len; /* Number of bytes to transfer */
100 system call works just like
102 except that multiple buffers are filled.
106 system call works just like
108 except that multiple buffers are written out.
110 Buffers are processed in array order.
118 (If there is insufficient data, then not all buffers pointed to by
123 writes out the entire contents of
129 The data transfers performed by
133 are atomic: the data written by
135 is written as a single block that is not intermingled with output
136 from writes in other processes (but see
141 is guaranteed to read a contiguous block of data from the file,
142 regardless of read operations performed in other threads or processes
143 that have file descriptors referring to the same open file description
146 .SS preadv() and pwritev()
149 system call combines the functionality of
153 It performs the same task as
155 but adds a fourth argument,
157 which specifies the file offset at which the input operation
162 system call combines the functionality of
166 It performs the same task as
168 but adds a fourth argument,
170 which specifies the file offset at which the output operation
173 The file offset is not changed by these system calls.
174 The file referred to by
176 must be capable of seeking.
182 return the number of bytes read;
186 return the number of bytes written.
187 On error, \-1 is returned, and \fIerrno\fP is set appropriately.
189 The errors are as given for
197 can also fail for the same reasons as
199 Additionally, the following error is defined:
209 The vector count \fIiovcnt\fP is less than zero or greater than the
215 first appeared in Linux 2.6.30; library support was added in glibc 2.10.
219 4.4BSD (these system calls first appeared in 4.2BSD), POSIX.1-2001.
220 .\" Linux libc5 used \fIsize_t\fP as the type of the \fIiovcnt\fP argument,
221 .\" and \fIint\fP as the return type.
222 .\" The readv/writev system calls were buggy before Linux 1.3.40.
223 .\" (Says release.libc.)
227 nonstandard, but present also on the modern BSDs.
229 POSIX.1-2001 allows an implementation to place a limit on
230 the number of items that can be passed in
232 An implementation can advertise its limit by defining
236 or at run time via the return value from
237 .IR sysconf(_SC_IOV_MAX) .
238 On modern Linux systems, the limit is 1024.
239 Back in Linux 2.0 days, this limit was 16.
242 .SS C library/kernel ABI differences
247 system calls have call signatures that differ slightly from that of the
248 corresponding GNU C library wrapper functions shown in the SYNOPSIS.
251 is unpacked by the wrapper functions into two arguments in the system calls:
253 .BI " unsigned long " pos_l ", unsigned long " pos
255 These arguments contain, respectively, the low order and high order 32 bits of
257 .SS Historical C library/kernel ABI differences
258 To deal with the fact that
260 was so low on early versions of Linux,
261 the glibc wrapper functions for
265 did some extra work if they detected that the underlying kernel
266 system call failed because this limit was exceeded.
269 the wrapper function allocated a temporary buffer large enough
270 for all of the items specified by
272 passed that buffer in a call to
274 copied data from the buffer to the locations specified by the
276 fields of the elements of
278 and then freed the buffer.
279 The wrapper function for
281 performed the analogous task using a temporary buffer and a call to
284 The need for this extra effort in the glibc wrapper functions
285 went away with Linux 2.2 and later.
286 However, glibc continued to provide this behavior until version 2.10.
287 Starting with glibc version 2.9,
288 the wrapper functions provide this behavior only if the library detects
289 that the system is running a Linux kernel older than version 2.6.18
290 (an arbitrarily selected kernel version).
292 (which requires a minimum Linux kernel version of 2.6.32),
293 the glibc wrapper functions always just directly invoke the system calls.
295 It is not advisable to mix calls to
299 which operate on file descriptors, with the functions from the stdio
300 library; the results will be undefined and probably not what you want.
302 The following code sample demonstrates the use of
307 char *str0 = "hello ";
308 char *str1 = "world\\n";
312 iov[0].iov_base = str0;
313 iov[0].iov_len = strlen(str0);
314 iov[1].iov_base = str1;
315 iov[1].iov_len = strlen(str1);
317 nwritten = writev(STDOUT_FILENO, iov, 2);
325 This page is part of release 3.79 of the Linux
328 A description of the project,
329 information about reporting bugs,
330 and the latest version of this page,
332 \%http://www.kernel.org/doc/man\-pages/.