]>
Commit | Line | Data |
---|---|---|
5427f5fb | 1 | .\" Copyright (C) 2007, 2010 Michael Kerrisk <mtk.manpages@gmail.com> |
f37855d1 | 2 | .\" and Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) |
fea681da | 3 | .\" |
93015253 | 4 | .\" %%%LICENSE_START(VERBATIM) |
fea681da MK |
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. | |
c13182ef | 13 | .\" |
fea681da MK |
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. | |
c13182ef | 21 | .\" |
fea681da MK |
22 | .\" Formatted or processed versions of this manual, if unaccompanied by |
23 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 24 | .\" %%%LICENSE_END |
c08df37a | 25 | .\" |
fea681da MK |
26 | .\" Modified Sat Jul 24 18:34:44 1993 by Rik Faith (faith@cs.unc.edu) |
27 | .\" Merged readv.[23], 2002-10-17, aeb | |
ab44d3d6 MK |
28 | .\" 2007-04-30 mtk, A fairly major rewrite to fix errors and |
29 | .\" add more details. | |
5427f5fb | 30 | .\" 2010-11-16, mtk, Added documentation of preadv() and pwritev() |
fea681da | 31 | .\" |
97986708 | 32 | .TH READV 2 2016-03-15 "Linux" "Linux Programmer's Manual" |
fea681da | 33 | .SH NAME |
e0e3a6a3 | 34 | readv, writev, preadv, pwritev \- read or write data into multiple buffers |
fea681da MK |
35 | .SH SYNOPSIS |
36 | .nf | |
37 | .B #include <sys/uio.h> | |
38 | .sp | |
ab44d3d6 | 39 | .BI "ssize_t readv(int " fd ", const struct iovec *" iov ", int " iovcnt ); |
fea681da | 40 | .sp |
ab44d3d6 | 41 | .BI "ssize_t writev(int " fd ", const struct iovec *" iov ", int " iovcnt ); |
e0e3a6a3 | 42 | .sp |
c5662d5d | 43 | .BI "ssize_t preadv(int " fd ", const struct iovec *" iov ", int " iovcnt , |
e0e3a6a3 MK |
44 | .BI " off_t " offset ); |
45 | .sp | |
46 | .BI "ssize_t pwritev(int " fd ", const struct iovec *" iov ", int " iovcnt , | |
47 | .BI " off_t " offset ); | |
fea681da | 48 | .fi |
e0e3a6a3 MK |
49 | .sp |
50 | .in -4n | |
51 | Feature Test Macro Requirements for glibc (see | |
52 | .BR feature_test_macros (7)): | |
53 | .in | |
54 | .sp | |
55 | .BR preadv (), | |
56 | .BR pwritev (): | |
51c612fb MK |
57 | Since glibc 2.19: |
58 | _DEFAULT_SOURCE | |
59 | Glibc 2.19 and earlier: | |
60 | _BSD_SOURCE | |
fea681da MK |
61 | .SH DESCRIPTION |
62 | The | |
8a1dd514 | 63 | .BR readv () |
e7d82451 | 64 | system call reads |
ab44d3d6 MK |
65 | .I iovcnt |
66 | buffers from the file associated with the file descriptor | |
fea681da | 67 | .I fd |
ab44d3d6 | 68 | into the buffers described by |
0daa9e92 | 69 | .I iov |
ab44d3d6 | 70 | ("scatter input"). |
fea681da MK |
71 | .PP |
72 | The | |
8a1dd514 | 73 | .BR writev () |
e7d82451 | 74 | system call writes |
ab44d3d6 MK |
75 | .I iovcnt |
76 | buffers of data described by | |
77 | .I iov | |
fea681da | 78 | to the file associated with the file descriptor |
0daa9e92 | 79 | .I fd |
ab44d3d6 | 80 | ("gather output"). |
fea681da MK |
81 | .PP |
82 | The pointer | |
ab44d3d6 | 83 | .I iov |
988db661 | 84 | points to an array of |
ab44d3d6 MK |
85 | .I iovec |
86 | structures, | |
fea681da | 87 | defined in |
8a1dd514 | 88 | .I <sys/uio.h> |
ab44d3d6 | 89 | as: |
fea681da MK |
90 | .PP |
91 | .br | |
088a639b | 92 | .in +4n |
fea681da | 93 | .nf |
fea681da | 94 | struct iovec { |
ab44d3d6 MK |
95 | void *iov_base; /* Starting address */ |
96 | size_t iov_len; /* Number of bytes to transfer */ | |
fea681da MK |
97 | }; |
98 | .fi | |
088a639b | 99 | .in |
fea681da | 100 | .PP |
fea681da | 101 | The |
8a1dd514 | 102 | .BR readv () |
e7d82451 | 103 | system call works just like |
fea681da MK |
104 | .BR read (2) |
105 | except that multiple buffers are filled. | |
106 | .PP | |
107 | The | |
8a1dd514 | 108 | .BR writev () |
e7d82451 | 109 | system call works just like |
fea681da MK |
110 | .BR write (2) |
111 | except that multiple buffers are written out. | |
ab44d3d6 MK |
112 | .PP |
113 | Buffers are processed in array order. | |
114 | This means that | |
115 | .BR readv () | |
116 | completely fills | |
117 | .IR iov [0] | |
988db661 | 118 | before proceeding to |
ab44d3d6 MK |
119 | .IR iov [1], |
120 | and so on. | |
121 | (If there is insufficient data, then not all buffers pointed to by | |
122 | .I iov | |
123 | may be filled.) | |
124 | Similarly, | |
125 | .BR writev () | |
126 | writes out the entire contents of | |
127 | .IR iov [0] | |
988db661 | 128 | before proceeding to |
ab44d3d6 MK |
129 | .IR iov [1], |
130 | and so on. | |
131 | .PP | |
132 | The data transfers performed by | |
133 | .BR readv () | |
134 | and | |
135 | .BR writev () | |
136 | are atomic: the data written by | |
6d8e9b7e | 137 | .\" Regarding atomicity, see https://bugzilla.kernel.org/show_bug.cgi?id=10596 |
ab44d3d6 MK |
138 | .BR writev () |
139 | is written as a single block that is not intermingled with output | |
140 | from writes in other processes (but see | |
141 | .BR pipe (7) | |
142 | for an exception); | |
143 | analogously, | |
144 | .BR readv () | |
145 | is guaranteed to read a contiguous block of data from the file, | |
146 | regardless of read operations performed in other threads or processes | |
147 | that have file descriptors referring to the same open file description | |
988db661 | 148 | (see |
ab44d3d6 | 149 | .BR open (2)). |
e0e3a6a3 MK |
150 | .SS preadv() and pwritev() |
151 | The | |
152 | .BR preadv () | |
153 | system call combines the functionality of | |
154 | .BR readv () | |
155 | and | |
156 | .BR pread (2). | |
157 | It performs the same task as | |
158 | .BR readv (), | |
159 | but adds a fourth argument, | |
160 | .IR offset , | |
161 | which specifies the file offset at which the input operation | |
162 | is to be performed. | |
163 | ||
164 | The | |
165 | .BR pwritev () | |
166 | system call combines the functionality of | |
167 | .BR writev () | |
168 | and | |
169 | .BR pwrite (2). | |
170 | It performs the same task as | |
171 | .BR writev (), | |
172 | but adds a fourth argument, | |
173 | .IR offset , | |
174 | which specifies the file offset at which the output operation | |
175 | is to be performed. | |
176 | ||
177 | The file offset is not changed by these system calls. | |
178 | The file referred to by | |
179 | .I fd | |
180 | must be capable of seeking. | |
47297adb | 181 | .SH RETURN VALUE |
9d04fbe5 | 182 | On success, |
8a1dd514 | 183 | .BR readv () |
e0e3a6a3 MK |
184 | and |
185 | .BR preadv () | |
186 | return the number of bytes read; | |
8a1dd514 | 187 | .BR writev () |
e0e3a6a3 MK |
188 | and |
189 | .BR pwritev () | |
190 | return the number of bytes written. | |
77548009 MK |
191 | |
192 | Note that is not an error for a successful call to transfer fewer bytes | |
193 | than requested (see | |
194 | .BR read (2) | |
195 | and | |
196 | .BR write (2)). | |
197 | ||
fea681da MK |
198 | On error, \-1 is returned, and \fIerrno\fP is set appropriately. |
199 | .SH ERRORS | |
200 | The errors are as given for | |
201 | .BR read (2) | |
202 | and | |
203 | .BR write (2). | |
e0e3a6a3 MK |
204 | Furthermore, |
205 | .BR preadv () | |
206 | and | |
207 | .BR pwritev () | |
208 | can also fail for the same reasons as | |
209 | .BR lseek (2). | |
210 | Additionally, the following error is defined: | |
fea681da MK |
211 | .TP |
212 | .B EINVAL | |
213 | The sum of the | |
214 | .I iov_len | |
215 | values overflows an | |
8a1dd514 | 216 | .I ssize_t |
c13182ef | 217 | value. |
bc9ed112 MK |
218 | .TP |
219 | .B EINVAL | |
220 | The vector count \fIiovcnt\fP is less than zero or greater than the | |
8a1dd514 | 221 | permitted maximum. |
e0e3a6a3 MK |
222 | .SH VERSIONS |
223 | .BR preadv () | |
fea681da | 224 | and |
e0e3a6a3 MK |
225 | .BR pwritev () |
226 | first appeared in Linux 2.6.30; library support was added in glibc 2.10. | |
47297adb | 227 | .SH CONFORMING TO |
e0e3a6a3 MK |
228 | .BR readv (), |
229 | .BR writev (): | |
9c9c8ad1 MK |
230 | POSIX.1-2001, POSIX.1-2008, |
231 | 4.4BSD (these system calls first appeared in 4.2BSD). | |
0e8cfea7 MK |
232 | .\" Linux libc5 used \fIsize_t\fP as the type of the \fIiovcnt\fP argument, |
233 | .\" and \fIint\fP as the return type. | |
fea681da MK |
234 | .\" The readv/writev system calls were buggy before Linux 1.3.40. |
235 | .\" (Says release.libc.) | |
e0e3a6a3 MK |
236 | |
237 | .BR preadv (), | |
238 | .BR pwritev (): | |
239 | nonstandard, but present also on the modern BSDs. | |
4fb31341 | 240 | .SH NOTES |
9c9c8ad1 | 241 | POSIX.1 allows an implementation to place a limit on |
97c1eac8 | 242 | the number of items that can be passed in |
ab44d3d6 | 243 | .IR iov . |
8a1dd514 MK |
244 | An implementation can advertise its limit by defining |
245 | .B IOV_MAX | |
246 | in | |
0daa9e92 | 247 | .I <limits.h> |
8a1dd514 MK |
248 | or at run time via the return value from |
249 | .IR sysconf(_SC_IOV_MAX) . | |
8a930bf1 MK |
250 | On modern Linux systems, the limit is 1024. |
251 | Back in Linux 2.0 days, this limit was 16. | |
def04e1c MK |
252 | .\" |
253 | .\" | |
0722a578 | 254 | .SS C library/kernel differences |
8b5857b0 MK |
255 | The raw |
256 | .BR preadv () | |
257 | and | |
258 | .BR pwritev () | |
259 | system calls have call signatures that differ slightly from that of the | |
260 | corresponding GNU C library wrapper functions shown in the SYNOPSIS. | |
261 | The final argument, | |
262 | .IR offset , | |
263 | is unpacked by the wrapper functions into two arguments in the system calls: | |
264 | ||
265 | .BI " unsigned long " pos_l ", unsigned long " pos | |
266 | ||
267 | These arguments contain, respectively, the low order and high order 32 bits of | |
268 | .IR offset . | |
0722a578 | 269 | .SS Historical C library/kernel differences |
8a930bf1 MK |
270 | To deal with the fact that |
271 | .B IOV_MAX | |
272 | was so low on early versions of Linux, | |
273 | the glibc wrapper functions for | |
274 | .BR readv () | |
275 | and | |
276 | .BR writev () | |
277 | did some extra work if they detected that the underlying kernel | |
278 | system call failed because this limit was exceeded. | |
c13182ef | 279 | In the case of |
4213c13e | 280 | .BR readv (), |
8a930bf1 | 281 | the wrapper function allocated a temporary buffer large enough |
8a1dd514 | 282 | for all of the items specified by |
ab44d3d6 | 283 | .IR iov , |
8a930bf1 | 284 | passed that buffer in a call to |
0bfa087b | 285 | .BR read (2), |
8a930bf1 | 286 | copied data from the buffer to the locations specified by the |
8a1dd514 | 287 | .I iov_base |
c13182ef | 288 | fields of the elements of |
ab44d3d6 | 289 | .IR iov , |
8a930bf1 | 290 | and then freed the buffer. |
8a1dd514 MK |
291 | The wrapper function for |
292 | .BR writev () | |
8a930bf1 | 293 | performed the analogous task using a temporary buffer and a call to |
0bfa087b | 294 | .BR write (2). |
771e13d4 | 295 | |
8a930bf1 MK |
296 | The need for this extra effort in the glibc wrapper functions |
297 | went away with Linux 2.2 and later. | |
298 | However, glibc continued to provide this behavior until version 2.10. | |
299 | Starting with glibc version 2.9, | |
300 | the wrapper functions provide this behavior only if the library detects | |
301 | that the system is running a Linux kernel older than version 2.6.18 | |
302 | (an arbitrarily selected kernel version). | |
303 | And since glibc 2.20 | |
304 | (which requires a minimum Linux kernel version of 2.6.32), | |
305 | the glibc wrapper functions always just directly invoke the system calls. | |
7b0d1eaa | 306 | |
e7d82451 | 307 | It is not advisable to mix calls to |
8a1dd514 | 308 | .BR readv () |
fea681da | 309 | or |
8a1dd514 | 310 | .BR writev (), |
fea681da MK |
311 | which operate on file descriptors, with the functions from the stdio |
312 | library; the results will be undefined and probably not what you want. | |
ab44d3d6 MK |
313 | .SH EXAMPLE |
314 | The following code sample demonstrates the use of | |
315 | .BR writev (): | |
316 | ||
088a639b | 317 | .in +4n |
ab44d3d6 MK |
318 | .nf |
319 | char *str0 = "hello "; | |
320 | char *str1 = "world\\n"; | |
321 | struct iovec iov[2]; | |
322 | ssize_t nwritten; | |
323 | ||
324 | iov[0].iov_base = str0; | |
325 | iov[0].iov_len = strlen(str0); | |
326 | iov[1].iov_base = str1; | |
327 | iov[1].iov_len = strlen(str1); | |
328 | ||
329 | nwritten = writev(STDOUT_FILENO, iov, 2); | |
330 | .fi | |
331 | .in | |
47297adb | 332 | .SH SEE ALSO |
e0e3a6a3 | 333 | .BR pread (2), |
fea681da MK |
334 | .BR read (2), |
335 | .BR write (2) |