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 2010-11-17 "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:
207 Or, the vector count \fIiovcnt\fP is less than zero or greater than the
213 first appeared in Linux 2.6.30; library support was added in glibc 2.10.
217 4.4BSD (these system calls first appeared in 4.2BSD), POSIX.1-2001.
218 Linux libc5 used \fIsize_t\fP as the type of the \fIiovcnt\fP argument,
219 and \fIint\fP as the return type.
220 .\" The readv/writev system calls were buggy before Linux 1.3.40.
221 .\" (Says release.libc.)
225 nonstandard, but present also on the modern BSDs.
228 POSIX.1-2001 allows an implementation to place a limit on
229 the number of items that can be passed in
231 An implementation can advertise its limit by defining
235 or at run time via the return value from
236 .IR sysconf(_SC_IOV_MAX) .
237 On Linux, the limit advertised by these mechanisms is 1024,
238 which is the true kernel limit.
239 However, the glibc wrapper functions do some extra work if
240 they detect that the underlying kernel system call failed because this
244 the wrapper function allocates a temporary buffer large enough
245 for all of the items specified by
247 passes that buffer in a call to
249 copies data from the buffer to the locations specified by the
251 fields of the elements of
253 and then frees the buffer.
254 The wrapper function for
256 performs the analogous task using a temporary buffer and a call to
259 It is not advisable to mix calls to
263 which operate on file descriptors, with the functions from the stdio
264 library; the results will be undefined and probably not what you want.
266 The following code sample demonstrates the use of
271 char *str0 = "hello ";
272 char *str1 = "world\\n";
276 iov[0].iov_base = str0;
277 iov[0].iov_len = strlen(str0);
278 iov[1].iov_base = str1;
279 iov[1].iov_len = strlen(str1);
281 nwritten = writev(STDOUT_FILENO, iov, 2);
289 This page is part of release 3.67 of the Linux
292 A description of the project,
293 information about reporting bugs,
294 and the latest version of this page,
296 \%http://www.kernel.org/doc/man\-pages/.