-
Notifications
You must be signed in to change notification settings - Fork 0
/
readv.html
433 lines (333 loc) · 14.1 KB
/
readv.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
<!-- Creator : groff version 1.22.4 -->
<!-- CreationDate: Wed Jan 29 11:25:44 2020 -->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta name="generator" content="groff -Thtml, see www.gnu.org">
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<meta name="Content-Style" content="text/css">
<style type="text/css">
p { margin-top: 0; margin-bottom: 0; vertical-align: top }
pre { margin-top: 0; margin-bottom: 0; vertical-align: top }
table { margin-top: 0; margin-bottom: 0; vertical-align: top }
h1 { text-align: center }
</style>
<title>READV</title>
</head>
<body>
<h1 align="center">READV</h1>
<a href="#NAME">NAME</a><br>
<a href="#SYNOPSIS">SYNOPSIS</a><br>
<a href="#DESCRIPTION">DESCRIPTION</a><br>
<a href="#RETURN VALUE">RETURN VALUE</a><br>
<a href="#ERRORS">ERRORS</a><br>
<a href="#VERSIONS">VERSIONS</a><br>
<a href="#CONFORMING TO">CONFORMING TO</a><br>
<a href="#NOTES">NOTES</a><br>
<a href="#EXAMPLE">EXAMPLE</a><br>
<a href="#SEE ALSO">SEE ALSO</a><br>
<a href="#COLOPHON">COLOPHON</a><br>
<hr>
<h2>NAME
<a name="NAME"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">readv, writev,
preadv, pwritev, preadv2, pwritev2 - read or write data into
multiple buffers</p>
<h2>SYNOPSIS
<a name="SYNOPSIS"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em"><b>#include
<sys/uio.h></b></p>
<p style="margin-left:11%; margin-top: 1em"><b>ssize_t
readv(int</b> <i>fd</i><b>, const struct iovec
*</b><i>iov</i><b>, int</b> <i>iovcnt</i><b>);</b></p>
<p style="margin-left:11%; margin-top: 1em"><b>ssize_t
writev(int</b> <i>fd</i><b>, const struct iovec
*</b><i>iov</i><b>, int</b> <i>iovcnt</i><b>);</b></p>
<p style="margin-left:11%; margin-top: 1em"><b>ssize_t
preadv(int</b> <i>fd</i><b>, const struct iovec
*</b><i>iov</i><b>, int</b> <i>iovcnt</i><b>, <br>
off_t</b> <i>offset</i><b>);</b></p>
<p style="margin-left:11%; margin-top: 1em"><b>ssize_t
pwritev(int</b> <i>fd</i><b>, const struct iovec
*</b><i>iov</i><b>, int</b> <i>iovcnt</i><b>, <br>
off_t</b> <i>offset</i><b>);</b></p>
<p style="margin-left:11%; margin-top: 1em"><b>ssize_t
preadv2(int</b> <i>fd</i><b>, const struct iovec
*</b><i>iov</i><b>, int</b> <i>iovcnt</i><b>, <br>
off_t</b> <i>offset</i><b>, int</b>
<i>flags</i><b>);</b></p>
<p style="margin-left:11%; margin-top: 1em"><b>ssize_t
pwritev2(int</b> <i>fd</i><b>, const struct iovec
*</b><i>iov</i><b>, int</b> <i>iovcnt</i><b>, <br>
off_t</b> <i>offset</i><b>, int</b>
<i>flags</i><b>);</b></p>
<p style="margin-left:5%; margin-top: 1em">Feature Test
Macro Requirements for glibc (see
<b>feature_test_macros</b>(7)):</p>
<p style="margin-left:11%; margin-top: 1em"><b>preadv</b>(),
<b>pwritev</b>(): <br>
Since glibc 2.19: <br>
_DEFAULT_SOURCE <br>
Glibc 2.19 and earlier: <br>
_BSD_SOURCE</p>
<h2>DESCRIPTION
<a name="DESCRIPTION"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">The
<b>readv</b>() system call reads <i>iovcnt</i> buffers from
the file associated with the file descriptor <i>fd</i> into
the buffers described by <i>iov</i> ("scatter
input").</p>
<p style="margin-left:11%; margin-top: 1em">The
<b>writev</b>() system call writes <i>iovcnt</i> buffers of
data described by <i>iov</i> to the file associated with the
file descriptor <i>fd</i> ("gather output").</p>
<p style="margin-left:11%; margin-top: 1em">The pointer
<i>iov</i> points to an array of <i>iovec</i> structures,
defined in <i><sys/uio.h></i> as:</p>
<p style="margin-left:17%; margin-top: 1em">struct iovec {
<br>
void *iov_base; /* Starting address */ <br>
size_t iov_len; /* Number of bytes to transfer */ <br>
};</p>
<p style="margin-left:11%; margin-top: 1em">The
<b>readv</b>() system call works just like <b>read</b>(2)
except that multiple buffers are filled.</p>
<p style="margin-left:11%; margin-top: 1em">The
<b>writev</b>() system call works just like <b>write</b>(2)
except that multiple buffers are written out.</p>
<p style="margin-left:11%; margin-top: 1em">Buffers are
processed in array order. This means that <b>readv</b>()
completely fills <i>iov</i>[0] before proceeding to
<i>iov</i>[1], and so on. (If there is insufficient data,
then not all buffers pointed to by <i>iov</i> may be
filled.) Similarly, <b>writev</b>() writes out the entire
contents of <i>iov</i>[0] before proceeding to
<i>iov</i>[1], and so on.</p>
<p style="margin-left:11%; margin-top: 1em">The data
transfers performed by <b>readv</b>() and <b>writev</b>()
are atomic: the data written by <b>writev</b>() is written
as a single block that is not intermingled with output from
writes in other processes (but see <b>pipe</b>(7) for an
exception); analogously, <b>readv</b>() is guaranteed to
read a contiguous block of data from the file, regardless of
read operations performed in other threads or processes that
have file descriptors referring to the same open file
description (see <b>open</b>(2)).</p>
<p style="margin-left:11%; margin-top: 1em"><b>preadv() and
pwritev()</b> <br>
The <b>preadv</b>() system call combines the functionality
of <b>readv</b>() and <b>pread</b>(2). It performs the same
task as <b>readv</b>(), but adds a fourth argument,
<i>offset</i>, which specifies the file offset at which the
input operation is to be performed.</p>
<p style="margin-left:11%; margin-top: 1em">The
<b>pwritev</b>() system call combines the functionality of
<b>writev</b>() and <b>pwrite</b>(2). It performs the same
task as <b>writev</b>(), but adds a fourth argument,
<i>offset</i>, which specifies the file offset at which the
output operation is to be performed.</p>
<p style="margin-left:11%; margin-top: 1em">The file offset
is not changed by these system calls. The file referred to
by <i>fd</i> must be capable of seeking.</p>
<p style="margin-left:11%; margin-top: 1em"><b>preadv2()
and pwritev2()</b> <br>
These system calls are similar to <b>preadv</b>() and
<b>pwritev</b>() calls, but add a fifth argument,
<i>flags</i>, which modifies the behavior on a per-call
basis.</p>
<p style="margin-left:11%; margin-top: 1em">Unlike
<b>preadv</b>() and <b>pwritev</b>(), if the <i>offset</i>
argument is -1, then the current file offset is used and
updated.</p>
<p style="margin-left:11%; margin-top: 1em">The
<i>flags</i> argument contains a bitwise OR of zero or more
of the following flags: <b><br>
RWF_DSYNC</b> (since Linux 4.7)</p>
<p style="margin-left:22%;">Provide a per-write equivalent
of the <b>O_DSYNC open</b>(2) flag. This flag is meaningful
only for <b>pwritev2</b>(), and its effect applies only to
the data range written by the system call.</p>
<p style="margin-left:11%;"><b>RWF_HIPRI</b> (since Linux
4.6)</p>
<p style="margin-left:22%;">High priority read/write.
Allows block-based filesystems to use polling of the device,
which provides lower latency, but may use additional
resources. (Currently, this feature is usable only on a file
descriptor opened using the <b>O_DIRECT</b> flag.)</p>
<p style="margin-left:11%;"><b>RWF_SYNC</b> (since Linux
4.7)</p>
<p style="margin-left:22%;">Provide a per-write equivalent
of the <b>O_SYNC open</b>(2) flag. This flag is meaningful
only for <b>pwritev2</b>(), and its effect applies only to
the data range written by the system call.</p>
<p style="margin-left:11%;"><b>RWF_NOWAIT</b> (since Linux
4.14)</p>
<p style="margin-left:22%;">Do not wait for data which is
not immediately available. If this flag is specified, the
<b>preadv2</b>() system call will return instantly if it
would have to read data from the backing storage or wait for
a lock. If some data was successfully read, it will return
the number of bytes read. If no bytes were read, it will
return -1 and set <i>errno</i> to <b>EAGAIN</b>. Currently,
this flag is meaningful only for <b>preadv2</b>().</p>
<p style="margin-left:11%;"><b>RWF_APPEND</b> (since Linux
4.16)</p>
<p style="margin-left:22%;">Provide a per-write equivalent
of the <b>O_APPEND open</b>(2) flag. This flag is meaningful
only for <b>pwritev2</b>(), and its effect applies only to
the data range written by the system call. The <i>offset</i>
argument does not affect the write operation; the data is
always appended to the end of the file. However, if the
<i>offset</i> argument is -1, the current file offset is
updated.</p>
<h2>RETURN VALUE
<a name="RETURN VALUE"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">On success,
<b>readv</b>(), <b>preadv</b>() and <b>preadv2</b>() return
the number of bytes read; <b>writev</b>(), <b>pwritev</b>()
and <b>pwritev2</b>() return the number of bytes
written.</p>
<p style="margin-left:11%; margin-top: 1em">Note that it is
not an error for a successful call to transfer fewer bytes
than requested (see <b>read</b>(2) and <b>write</b>(2)).</p>
<p style="margin-left:11%; margin-top: 1em">On error, -1 is
returned, and <i>errno</i> is set appropriately.</p>
<h2>ERRORS
<a name="ERRORS"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">The errors are
as given for <b>read</b>(2) and <b>write</b>(2).
Furthermore, <b>preadv</b>(), <b>preadv2</b>(),
<b>pwritev</b>(), and <b>pwritev2</b>() can also fail for
the same reasons as <b>lseek</b>(2). Additionally, the
following errors are defined:</p>
<table width="100%" border="0" rules="none" frame="void"
cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="11%"></td>
<td width="9%">
<p><b>EINVAL</b></p></td>
<td width="2%"></td>
<td width="78%">
<p>The sum of the <i>iov_len</i> values overflows an
<i>ssize_t</i> value.</p></td></tr>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="9%">
<p><b>EINVAL</b></p></td>
<td width="2%"></td>
<td width="78%">
<p>The vector count, <i>iovcnt</i>, is less than zero or
greater than the permitted maximum.</p></td></tr>
</table>
<p style="margin-left:11%;"><b>EOPNOTSUPP</b></p>
<p style="margin-left:22%;">An unknown flag is specified in
<i>flags</i>.</p>
<h2>VERSIONS
<a name="VERSIONS"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em"><b>preadv</b>()
and <b>pwritev</b>() first appeared in Linux 2.6.30; library
support was added in glibc 2.10.</p>
<p style="margin-left:11%; margin-top: 1em"><b>preadv2</b>()
and <b>pwritev2</b>() first appeared in Linux 4.6. Library
support was added in glibc 2.26.</p>
<h2>CONFORMING TO
<a name="CONFORMING TO"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em"><b>readv</b>(),
<b>writev</b>(): POSIX.1-2001, POSIX.1-2008, 4.4BSD (these
system calls first appeared in 4.2BSD).</p>
<p style="margin-left:11%; margin-top: 1em"><b>preadv</b>(),
<b>pwritev</b>(): nonstandard, but present also on the
modern BSDs.</p>
<p style="margin-left:11%; margin-top: 1em"><b>preadv2</b>(),
<b>pwritev2</b>(): nonstandard Linux extension.</p>
<h2>NOTES
<a name="NOTES"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">POSIX.1 allows
an implementation to place a limit on the number of items
that can be passed in <i>iov</i>. An implementation can
advertise its limit by defining <b>IOV_MAX</b> in
<i><limits.h></i> or at run time via the return value
from <i>sysconf(_SC_IOV_MAX)</i>. On modern Linux systems,
the limit is 1024. Back in Linux 2.0 days, this limit was
16.</p>
<p style="margin-left:11%; margin-top: 1em"><b>C
library/kernel differences</b> <br>
The raw <b>preadv</b>() and <b>pwritev</b>() system calls
have call signatures that differ slightly from that of the
corresponding GNU C library wrapper functions shown in the
SYNOPSIS. The final argument, <i>offset</i>, is unpacked by
the wrapper functions into two arguments in the system
calls:</p>
<p style="margin-left:11%; margin-top: 1em"><b>unsigned
long</b> <i>pos_l</i><b>, unsigned long</b> <i>pos</i></p>
<p style="margin-left:11%; margin-top: 1em">These arguments
contain, respectively, the low order and high order 32 bits
of <i>offset</i>.</p>
<p style="margin-left:11%; margin-top: 1em"><b>Historical C
library/kernel differences</b> <br>
To deal with the fact that <b>IOV_MAX</b> was so low on
early versions of Linux, the glibc wrapper functions for
<b>readv</b>() and <b>writev</b>() did some extra work if
they detected that the underlying kernel system call failed
because this limit was exceeded. In the case of
<b>readv</b>(), the wrapper function allocated a temporary
buffer large enough for all of the items specified by
<i>iov</i>, passed that buffer in a call to <b>read</b>(2),
copied data from the buffer to the locations specified by
the <i>iov_base</i> fields of the elements of <i>iov</i>,
and then freed the buffer. The wrapper function for
<b>writev</b>() performed the analogous task using a
temporary buffer and a call to <b>write</b>(2).</p>
<p style="margin-left:11%; margin-top: 1em">The need for
this extra effort in the glibc wrapper functions went away
with Linux 2.2 and later. However, glibc continued to
provide this behavior until version 2.10. Starting with
glibc version 2.9, the wrapper functions provide this
behavior only if the library detects that the system is
running a Linux kernel older than version 2.6.18 (an
arbitrarily selected kernel version). And since glibc 2.20
(which requires a minimum Linux kernel version of 2.6.32),
the glibc wrapper functions always just directly invoke the
system calls.</p>
<h2>EXAMPLE
<a name="EXAMPLE"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">The following
code sample demonstrates the use of <b>writev</b>():</p>
<p style="margin-left:17%; margin-top: 1em">char *str0 =
"hello "; <br>
char *str1 = "world\n"; <br>
struct iovec iov[2]; <br>
ssize_t nwritten;</p>
<p style="margin-left:17%; margin-top: 1em">iov[0].iov_base
= str0; <br>
iov[0].iov_len = strlen(str0); <br>
iov[1].iov_base = str1; <br>
iov[1].iov_len = strlen(str1);</p>
<p style="margin-left:17%; margin-top: 1em">nwritten =
writev(STDOUT_FILENO, iov, 2);</p>
<h2>SEE ALSO
<a name="SEE ALSO"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em"><b>pread</b>(2),
<b>read</b>(2), <b>write</b>(2)</p>
<h2>COLOPHON
<a name="COLOPHON"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">This page is
part of release 5.02 of the Linux <i>man-pages</i> project.
A description of the project, information about reporting
bugs, and the latest version of this page, can be found at
https://www.kernel.org/doc/man-pages/.</p>
<hr>
</body>
</html>