]>
Commit | Line | Data |
---|---|---|
c11b1abf | 1 | .\" Copyright (C) 2007 Michael Kerrisk <mtk.manpages@gmail.com> |
ab44d3d6 | 2 | .\" and (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) |
fea681da MK |
3 | .\" |
4 | .\" Permission is granted to make and distribute verbatim copies of this | |
5 | .\" manual provided the copyright notice and this permission notice are | |
6 | .\" preserved on all copies. | |
7 | .\" | |
8 | .\" Permission is granted to copy and distribute modified versions of this | |
9 | .\" manual under the conditions for verbatim copying, provided that the | |
10 | .\" entire resulting derived work is distributed under the terms of a | |
11 | .\" permission notice identical to this one. | |
c13182ef | 12 | .\" |
fea681da MK |
13 | .\" Since the Linux kernel and libraries are constantly changing, this |
14 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
15 | .\" responsibility for errors or omissions, or for damages resulting from | |
16 | .\" the use of the information contained herein. The author(s) may not | |
17 | .\" have taken the same level of care in the production of this manual, | |
18 | .\" which is licensed free of charge, as they might when working | |
19 | .\" professionally. | |
c13182ef | 20 | .\" |
fea681da MK |
21 | .\" Formatted or processed versions of this manual, if unaccompanied by |
22 | .\" the source, must acknowledge the copyright and authors of this work. | |
23 | .\" License. | |
24 | .\" Modified Sat Jul 24 18:34:44 1993 by Rik Faith (faith@cs.unc.edu) | |
25 | .\" Merged readv.[23], 2002-10-17, aeb | |
ab44d3d6 MK |
26 | .\" 2007-04-30 mtk, A fairly major rewrite to fix errors and |
27 | .\" add more details. | |
fea681da | 28 | .\" |
f67f9e20 | 29 | .TH READV 2 2002-10-17 "Linux" "Linux Programmer's Manual" |
fea681da MK |
30 | .SH NAME |
31 | readv, writev \- read or write data into multiple buffers | |
32 | .SH SYNOPSIS | |
33 | .nf | |
34 | .B #include <sys/uio.h> | |
35 | .sp | |
ab44d3d6 | 36 | .BI "ssize_t readv(int " fd ", const struct iovec *" iov ", int " iovcnt ); |
fea681da | 37 | .sp |
ab44d3d6 | 38 | .BI "ssize_t writev(int " fd ", const struct iovec *" iov ", int " iovcnt ); |
fea681da MK |
39 | .fi |
40 | .SH DESCRIPTION | |
41 | The | |
8a1dd514 | 42 | .BR readv () |
fea681da | 43 | function reads |
ab44d3d6 MK |
44 | .I iovcnt |
45 | buffers from the file associated with the file descriptor | |
fea681da | 46 | .I fd |
ab44d3d6 | 47 | into the buffers described by |
988db661 | 48 | .IR iov |
ab44d3d6 | 49 | ("scatter input"). |
fea681da MK |
50 | .PP |
51 | The | |
8a1dd514 | 52 | .BR writev () |
ab44d3d6 MK |
53 | function writes |
54 | .I iovcnt | |
55 | buffers of data described by | |
56 | .I iov | |
fea681da | 57 | to the file associated with the file descriptor |
988db661 | 58 | .IR fd |
ab44d3d6 | 59 | ("gather output"). |
fea681da MK |
60 | .PP |
61 | The pointer | |
ab44d3d6 | 62 | .I iov |
988db661 | 63 | points to an array of |
ab44d3d6 MK |
64 | .I iovec |
65 | structures, | |
fea681da | 66 | defined in |
8a1dd514 | 67 | .I <sys/uio.h> |
ab44d3d6 | 68 | as: |
fea681da MK |
69 | .PP |
70 | .br | |
8a1dd514 | 71 | .in +0.25in |
fea681da | 72 | .nf |
fea681da | 73 | struct iovec { |
ab44d3d6 MK |
74 | void *iov_base; /* Starting address */ |
75 | size_t iov_len; /* Number of bytes to transfer */ | |
fea681da MK |
76 | }; |
77 | .fi | |
8a1dd514 | 78 | .in 0.25in |
fea681da | 79 | .PP |
fea681da | 80 | The |
8a1dd514 | 81 | .BR readv () |
fea681da MK |
82 | function works just like |
83 | .BR read (2) | |
84 | except that multiple buffers are filled. | |
85 | .PP | |
86 | The | |
8a1dd514 | 87 | .BR writev () |
fea681da MK |
88 | function works just like |
89 | .BR write (2) | |
90 | except that multiple buffers are written out. | |
ab44d3d6 MK |
91 | .PP |
92 | Buffers are processed in array order. | |
93 | This means that | |
94 | .BR readv () | |
95 | completely fills | |
96 | .IR iov [0] | |
988db661 | 97 | before proceeding to |
ab44d3d6 MK |
98 | .IR iov [1], |
99 | and so on. | |
100 | (If there is insufficient data, then not all buffers pointed to by | |
101 | .I iov | |
102 | may be filled.) | |
103 | Similarly, | |
104 | .BR writev () | |
105 | writes out the entire contents of | |
106 | .IR iov [0] | |
988db661 | 107 | before proceeding to |
ab44d3d6 MK |
108 | .IR iov [1], |
109 | and so on. | |
110 | .PP | |
111 | The data transfers performed by | |
112 | .BR readv () | |
113 | and | |
114 | .BR writev () | |
115 | are atomic: the data written by | |
116 | .BR writev () | |
117 | is written as a single block that is not intermingled with output | |
118 | from writes in other processes (but see | |
119 | .BR pipe (7) | |
120 | for an exception); | |
121 | analogously, | |
122 | .BR readv () | |
123 | is guaranteed to read a contiguous block of data from the file, | |
124 | regardless of read operations performed in other threads or processes | |
125 | that have file descriptors referring to the same open file description | |
988db661 | 126 | (see |
ab44d3d6 | 127 | .BR open (2)). |
fea681da MK |
128 | .SH "RETURN VALUE" |
129 | On success, the | |
8a1dd514 | 130 | .BR readv () |
fea681da | 131 | function returns the number of bytes read; the |
8a1dd514 | 132 | .BR writev () |
fea681da MK |
133 | function returns the number of bytes written. |
134 | On error, \-1 is returned, and \fIerrno\fP is set appropriately. | |
135 | .SH ERRORS | |
136 | The errors are as given for | |
137 | .BR read (2) | |
138 | and | |
139 | .BR write (2). | |
8a1dd514 | 140 | Additionally the following error is defined: |
fea681da MK |
141 | .TP |
142 | .B EINVAL | |
143 | The sum of the | |
144 | .I iov_len | |
145 | values overflows an | |
8a1dd514 | 146 | .I ssize_t |
c13182ef | 147 | value. |
a8d55537 | 148 | Or, the vector count \fIiovcnt\fP is less than zero or greater than the |
8a1dd514 | 149 | permitted maximum. |
fea681da MK |
150 | .SH "CONFORMING TO" |
151 | 4.4BSD (the | |
8a1dd514 | 152 | .BR readv () |
fea681da | 153 | and |
8a1dd514 | 154 | .BR writev () |
97c1eac8 | 155 | functions first appeared in 4.2BSD), POSIX.1-2001. |
a8d55537 | 156 | Linux libc5 used \fIsize_t\fP as the type of the \fIiovcnt\fP parameter, |
9ff08aad | 157 | and \fIint\fP as return type for these functions. |
fea681da MK |
158 | .\" The readv/writev system calls were buggy before Linux 1.3.40. |
159 | .\" (Says release.libc.) | |
4fb31341 MK |
160 | .SH NOTES |
161 | .SS Linux Notes | |
c13182ef | 162 | POSIX.1-2001 allows an implementation to place a limit on |
97c1eac8 | 163 | the number of items that can be passed in |
ab44d3d6 | 164 | .IR iov . |
8a1dd514 MK |
165 | An implementation can advertise its limit by defining |
166 | .B IOV_MAX | |
167 | in | |
168 | .IR <limits.h> | |
169 | or at run time via the return value from | |
170 | .IR sysconf(_SC_IOV_MAX) . | |
171 | On Linux, the limit advertised by these mechanisms is 1024, | |
172 | which is the true kernel limit. | |
173 | However, the glibc wrapper functions do some extra work if | |
174 | they detect that the underlying kernel system call failed because this | |
c13182ef MK |
175 | limit was exceeded. |
176 | In the case of | |
8a1dd514 | 177 | .BR readv () |
c13182ef | 178 | the wrapper function allocates a temporary buffer large enough |
8a1dd514 | 179 | for all of the items specified by |
ab44d3d6 | 180 | .IR iov , |
c13182ef | 181 | passes that buffer in a call to |
0bfa087b | 182 | .BR read (2), |
8a1dd514 MK |
183 | copies data from the buffer to the locations specified by the |
184 | .I iov_base | |
c13182ef | 185 | fields of the elements of |
ab44d3d6 | 186 | .IR iov , |
8a1dd514 MK |
187 | and then frees the buffer. |
188 | The wrapper function for | |
189 | .BR writev () | |
190 | performs the analogous task using a temporary buffer and a call to | |
0bfa087b | 191 | .BR write (2). |
fea681da MK |
192 | .SH BUGS |
193 | It is not advisable to mix calls to functions like | |
8a1dd514 | 194 | .BR readv () |
fea681da | 195 | or |
8a1dd514 | 196 | .BR writev (), |
fea681da MK |
197 | which operate on file descriptors, with the functions from the stdio |
198 | library; the results will be undefined and probably not what you want. | |
ab44d3d6 MK |
199 | .SH EXAMPLE |
200 | The following code sample demonstrates the use of | |
201 | .BR writev (): | |
202 | ||
203 | .in +0.5i | |
204 | .nf | |
205 | char *str0 = "hello "; | |
206 | char *str1 = "world\\n"; | |
207 | struct iovec iov[2]; | |
208 | ssize_t nwritten; | |
209 | ||
210 | iov[0].iov_base = str0; | |
211 | iov[0].iov_len = strlen(str0); | |
212 | iov[1].iov_base = str1; | |
213 | iov[1].iov_len = strlen(str1); | |
214 | ||
215 | nwritten = writev(STDOUT_FILENO, iov, 2); | |
216 | .fi | |
217 | .in | |
fea681da MK |
218 | .SH "SEE ALSO" |
219 | .BR read (2), | |
220 | .BR write (2) |