]>
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 | .\" |
8392a3b3 | 32 | .TH READV 2 2015-01-22 "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 (): | |
57 | _BSD_SOURCE | |
fea681da MK |
58 | .SH DESCRIPTION |
59 | The | |
8a1dd514 | 60 | .BR readv () |
e7d82451 | 61 | system call reads |
ab44d3d6 MK |
62 | .I iovcnt |
63 | buffers from the file associated with the file descriptor | |
fea681da | 64 | .I fd |
ab44d3d6 | 65 | into the buffers described by |
0daa9e92 | 66 | .I iov |
ab44d3d6 | 67 | ("scatter input"). |
fea681da MK |
68 | .PP |
69 | The | |
8a1dd514 | 70 | .BR writev () |
e7d82451 | 71 | system call writes |
ab44d3d6 MK |
72 | .I iovcnt |
73 | buffers of data described by | |
74 | .I iov | |
fea681da | 75 | to the file associated with the file descriptor |
0daa9e92 | 76 | .I fd |
ab44d3d6 | 77 | ("gather output"). |
fea681da MK |
78 | .PP |
79 | The pointer | |
ab44d3d6 | 80 | .I iov |
988db661 | 81 | points to an array of |
ab44d3d6 MK |
82 | .I iovec |
83 | structures, | |
fea681da | 84 | defined in |
8a1dd514 | 85 | .I <sys/uio.h> |
ab44d3d6 | 86 | as: |
fea681da MK |
87 | .PP |
88 | .br | |
088a639b | 89 | .in +4n |
fea681da | 90 | .nf |
fea681da | 91 | struct iovec { |
ab44d3d6 MK |
92 | void *iov_base; /* Starting address */ |
93 | size_t iov_len; /* Number of bytes to transfer */ | |
fea681da MK |
94 | }; |
95 | .fi | |
088a639b | 96 | .in |
fea681da | 97 | .PP |
fea681da | 98 | The |
8a1dd514 | 99 | .BR readv () |
e7d82451 | 100 | system call works just like |
fea681da MK |
101 | .BR read (2) |
102 | except that multiple buffers are filled. | |
103 | .PP | |
104 | The | |
8a1dd514 | 105 | .BR writev () |
e7d82451 | 106 | system call works just like |
fea681da MK |
107 | .BR write (2) |
108 | except that multiple buffers are written out. | |
ab44d3d6 MK |
109 | .PP |
110 | Buffers are processed in array order. | |
111 | This means that | |
112 | .BR readv () | |
113 | completely fills | |
114 | .IR iov [0] | |
988db661 | 115 | before proceeding to |
ab44d3d6 MK |
116 | .IR iov [1], |
117 | and so on. | |
118 | (If there is insufficient data, then not all buffers pointed to by | |
119 | .I iov | |
120 | may be filled.) | |
121 | Similarly, | |
122 | .BR writev () | |
123 | writes out the entire contents of | |
124 | .IR iov [0] | |
988db661 | 125 | before proceeding to |
ab44d3d6 MK |
126 | .IR iov [1], |
127 | and so on. | |
128 | .PP | |
129 | The data transfers performed by | |
130 | .BR readv () | |
131 | and | |
132 | .BR writev () | |
133 | are atomic: the data written by | |
134 | .BR writev () | |
135 | is written as a single block that is not intermingled with output | |
136 | from writes in other processes (but see | |
137 | .BR pipe (7) | |
138 | for an exception); | |
139 | analogously, | |
140 | .BR readv () | |
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 | |
988db661 | 144 | (see |
ab44d3d6 | 145 | .BR open (2)). |
e0e3a6a3 MK |
146 | .SS preadv() and pwritev() |
147 | The | |
148 | .BR preadv () | |
149 | system call combines the functionality of | |
150 | .BR readv () | |
151 | and | |
152 | .BR pread (2). | |
153 | It performs the same task as | |
154 | .BR readv (), | |
155 | but adds a fourth argument, | |
156 | .IR offset , | |
157 | which specifies the file offset at which the input operation | |
158 | is to be performed. | |
159 | ||
160 | The | |
161 | .BR pwritev () | |
162 | system call combines the functionality of | |
163 | .BR writev () | |
164 | and | |
165 | .BR pwrite (2). | |
166 | It performs the same task as | |
167 | .BR writev (), | |
168 | but adds a fourth argument, | |
169 | .IR offset , | |
170 | which specifies the file offset at which the output operation | |
171 | is to be performed. | |
172 | ||
173 | The file offset is not changed by these system calls. | |
174 | The file referred to by | |
175 | .I fd | |
176 | must be capable of seeking. | |
47297adb | 177 | .SH RETURN VALUE |
9d04fbe5 | 178 | On success, |
8a1dd514 | 179 | .BR readv () |
e0e3a6a3 MK |
180 | and |
181 | .BR preadv () | |
182 | return the number of bytes read; | |
8a1dd514 | 183 | .BR writev () |
e0e3a6a3 MK |
184 | and |
185 | .BR pwritev () | |
186 | return the number of bytes written. | |
fea681da MK |
187 | On error, \-1 is returned, and \fIerrno\fP is set appropriately. |
188 | .SH ERRORS | |
189 | The errors are as given for | |
190 | .BR read (2) | |
191 | and | |
192 | .BR write (2). | |
e0e3a6a3 MK |
193 | Furthermore, |
194 | .BR preadv () | |
195 | and | |
196 | .BR pwritev () | |
197 | can also fail for the same reasons as | |
198 | .BR lseek (2). | |
199 | Additionally, the following error is defined: | |
fea681da MK |
200 | .TP |
201 | .B EINVAL | |
202 | The sum of the | |
203 | .I iov_len | |
204 | values overflows an | |
8a1dd514 | 205 | .I ssize_t |
c13182ef | 206 | value. |
bc9ed112 MK |
207 | .TP |
208 | .B EINVAL | |
209 | The vector count \fIiovcnt\fP is less than zero or greater than the | |
8a1dd514 | 210 | permitted maximum. |
e0e3a6a3 MK |
211 | .SH VERSIONS |
212 | .BR preadv () | |
fea681da | 213 | and |
e0e3a6a3 MK |
214 | .BR pwritev () |
215 | first appeared in Linux 2.6.30; library support was added in glibc 2.10. | |
47297adb | 216 | .SH CONFORMING TO |
e0e3a6a3 MK |
217 | .BR readv (), |
218 | .BR writev (): | |
e7d82451 | 219 | 4.4BSD (these system calls first appeared in 4.2BSD), POSIX.1-2001. |
0e8cfea7 MK |
220 | .\" Linux libc5 used \fIsize_t\fP as the type of the \fIiovcnt\fP argument, |
221 | .\" and \fIint\fP as the return type. | |
fea681da MK |
222 | .\" The readv/writev system calls were buggy before Linux 1.3.40. |
223 | .\" (Says release.libc.) | |
e0e3a6a3 MK |
224 | |
225 | .BR preadv (), | |
226 | .BR pwritev (): | |
227 | nonstandard, but present also on the modern BSDs. | |
4fb31341 | 228 | .SH NOTES |
c13182ef | 229 | POSIX.1-2001 allows an implementation to place a limit on |
97c1eac8 | 230 | the number of items that can be passed in |
ab44d3d6 | 231 | .IR iov . |
8a1dd514 MK |
232 | An implementation can advertise its limit by defining |
233 | .B IOV_MAX | |
234 | in | |
0daa9e92 | 235 | .I <limits.h> |
8a1dd514 MK |
236 | or at run time via the return value from |
237 | .IR sysconf(_SC_IOV_MAX) . | |
8a930bf1 MK |
238 | On modern Linux systems, the limit is 1024. |
239 | Back in Linux 2.0 days, this limit was 16. | |
240 | \" | |
8b5857b0 | 241 | \" |
0722a578 | 242 | .SS C library/kernel differences |
8b5857b0 MK |
243 | The raw |
244 | .BR preadv () | |
245 | and | |
246 | .BR pwritev () | |
247 | system calls have call signatures that differ slightly from that of the | |
248 | corresponding GNU C library wrapper functions shown in the SYNOPSIS. | |
249 | The final argument, | |
250 | .IR offset , | |
251 | is unpacked by the wrapper functions into two arguments in the system calls: | |
252 | ||
253 | .BI " unsigned long " pos_l ", unsigned long " pos | |
254 | ||
255 | These arguments contain, respectively, the low order and high order 32 bits of | |
256 | .IR offset . | |
0722a578 | 257 | .SS Historical C library/kernel differences |
8a930bf1 MK |
258 | To deal with the fact that |
259 | .B IOV_MAX | |
260 | was so low on early versions of Linux, | |
261 | the glibc wrapper functions for | |
262 | .BR readv () | |
263 | and | |
264 | .BR writev () | |
265 | did some extra work if they detected that the underlying kernel | |
266 | system call failed because this limit was exceeded. | |
c13182ef | 267 | In the case of |
4213c13e | 268 | .BR readv (), |
8a930bf1 | 269 | the wrapper function allocated a temporary buffer large enough |
8a1dd514 | 270 | for all of the items specified by |
ab44d3d6 | 271 | .IR iov , |
8a930bf1 | 272 | passed that buffer in a call to |
0bfa087b | 273 | .BR read (2), |
8a930bf1 | 274 | copied data from the buffer to the locations specified by the |
8a1dd514 | 275 | .I iov_base |
c13182ef | 276 | fields of the elements of |
ab44d3d6 | 277 | .IR iov , |
8a930bf1 | 278 | and then freed the buffer. |
8a1dd514 MK |
279 | The wrapper function for |
280 | .BR writev () | |
8a930bf1 | 281 | performed the analogous task using a temporary buffer and a call to |
0bfa087b | 282 | .BR write (2). |
771e13d4 | 283 | |
8a930bf1 MK |
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). | |
291 | And since glibc 2.20 | |
292 | (which requires a minimum Linux kernel version of 2.6.32), | |
293 | the glibc wrapper functions always just directly invoke the system calls. | |
fea681da | 294 | .SH BUGS |
e7d82451 | 295 | It is not advisable to mix calls to |
8a1dd514 | 296 | .BR readv () |
fea681da | 297 | or |
8a1dd514 | 298 | .BR writev (), |
fea681da MK |
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. | |
ab44d3d6 MK |
301 | .SH EXAMPLE |
302 | The following code sample demonstrates the use of | |
303 | .BR writev (): | |
304 | ||
088a639b | 305 | .in +4n |
ab44d3d6 MK |
306 | .nf |
307 | char *str0 = "hello "; | |
308 | char *str1 = "world\\n"; | |
309 | struct iovec iov[2]; | |
310 | ssize_t nwritten; | |
311 | ||
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); | |
316 | ||
317 | nwritten = writev(STDOUT_FILENO, iov, 2); | |
318 | .fi | |
319 | .in | |
47297adb | 320 | .SH SEE ALSO |
e0e3a6a3 | 321 | .BR pread (2), |
fea681da MK |
322 | .BR read (2), |
323 | .BR write (2) |