man2/readv.2

   1 .\" Copyright (C) 2007, 2010 Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\" and Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de)
   3 .\"
   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.
   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.
  13 .\"
  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.
  21 .\"
  22 .\" Formatted or processed versions of this manual, if unaccompanied by
  23 .\" the source, must acknowledge the copyright and authors of this work.
  24 .\" %%%LICENSE_END
  25 .\"
  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
  29 .\"     add more details.
  30 .\" 2010-11-16, mtk, Added documentation of preadv() and pwritev()
  31 .\"
  32 .TH READV 2  2015-07-23 "Linux" "Linux Programmer's Manual"
  33 .SH NAME
  34 readv, writev, preadv, pwritev \- read or write data into multiple buffers
  35 .SH SYNOPSIS
  36 .nf
  37 .B #include <sys/uio.h>
  38 .sp
  39 .BI "ssize_t readv(int " fd ", const struct iovec *" iov ", int " iovcnt );
  40 .sp
  41 .BI "ssize_t writev(int " fd ", const struct iovec *" iov ", int " iovcnt );
  42 .sp
  43 .BI "ssize_t preadv(int " fd ", const struct iovec *" iov ", int " iovcnt ,
  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 );
  48 .fi
  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     Since glibc 2.19:
  58         _DEFAULT_SOURCE
  59     Glibc 2.19 and earlier:
  60         _BSD_SOURCE
  61 .SH DESCRIPTION
  62 The
  63 .BR readv ()
  64 system call reads
  65 .I iovcnt
  66 buffers from the file associated with the file descriptor
  67 .I fd
  68 into the buffers described by
  69 .I iov
  70 ("scatter input").
  71 .PP
  72 The
  73 .BR writev ()
  74 system call writes
  75 .I iovcnt
  76 buffers of data described by
  77 .I iov
  78 to the file associated with the file descriptor
  79 .I fd
  80 ("gather output").
  81 .PP
  82 The pointer
  83 .I iov
  84 points to an array of
  85 .I iovec
  86 structures,
  87 defined in
  88 .I <sys/uio.h>
  89 as:
  90 .PP
  91 .br
  92 .in +4n
  93 .nf
  94 struct iovec {
  95     void  *iov_base;    /* Starting address */
  96     size_t iov_len;     /* Number of bytes to transfer */
  97 };
  98 .fi
  99 .in
 100 .PP
 101 The
 102 .BR readv ()
 103 system call works just like
 104 .BR read (2)
 105 except that multiple buffers are filled.
 106 .PP
 107 The
 108 .BR writev ()
 109 system call works just like
 110 .BR write (2)
 111 except that multiple buffers are written out.
 112 .PP
 113 Buffers are processed in array order.
 114 This means that
 115 .BR readv ()
 116 completely fills
 117 .IR iov [0]
 118 before proceeding to
 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]
 128 before proceeding to
 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
 137 .\" Regarding atomicity, see https://bugzilla.kernel.org/show_bug.cgi?id=10596
 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
 148 (see
 149 .BR open (2)).
 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.
 181 .SH RETURN VALUE
 182 On success,
 183 .BR readv ()
 184 and
 185 .BR preadv ()
 186 return the number of bytes read;
 187 .BR writev ()
 188 and
 189 .BR pwritev ()
 190 return the number of bytes written.
 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
 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).
 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:
 211 .TP
 212 .B EINVAL
 213 The sum of the
 214 .I iov_len
 215 values overflows an
 216 .I ssize_t
 217 value.
 218 .TP
 219 .B EINVAL
 220 The vector count \fIiovcnt\fP is less than zero or greater than the
 221 permitted maximum.
 222 .SH VERSIONS
 223 .BR preadv ()
 224 and
 225 .BR pwritev ()
 226 first appeared in Linux 2.6.30; library support was added in glibc 2.10.
 227 .SH CONFORMING TO
 228 .BR readv (),
 229 .BR writev ():
 230 POSIX.1-2001, POSIX.1-2008,
 231 4.4BSD (these system calls first appeared in 4.2BSD).
 232 .\" Linux libc5 used \fIsize_t\fP as the type of the \fIiovcnt\fP argument,
 233 .\" and \fIint\fP as the return type.
 234 .\" The readv/writev system calls were buggy before Linux 1.3.40.
 235 .\" (Says release.libc.)
 236
 237 .BR preadv (),
 238 .BR pwritev ():
 239 nonstandard, but present also on the modern BSDs.
 240 .SH NOTES
 241 POSIX.1 allows an implementation to place a limit on
 242 the number of items that can be passed in
 243 .IR iov .
 244 An implementation can advertise its limit by defining
 245 .B IOV_MAX
 246 in
 247 .I <limits.h>
 248 or at run time via the return value from
 249 .IR sysconf(_SC_IOV_MAX) .
 250 On modern Linux systems, the limit is 1024.
 251 Back in Linux 2.0 days, this limit was 16.
 252 .\"
 253 .\"
 254 .SS C library/kernel differences
 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 .
 269 .SS Historical C library/kernel differences
 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.
 279 In the case of
 280 .BR readv (),
 281 the wrapper function allocated a temporary buffer large enough
 282 for all of the items specified by
 283 .IR iov ,
 284 passed that buffer in a call to
 285 .BR read (2),
 286 copied data from the buffer to the locations specified by the
 287 .I iov_base
 288 fields of the elements of
 289 .IR iov ,
 290 and then freed the buffer.
 291 The wrapper function for
 292 .BR writev ()
 293 performed the analogous task using a temporary buffer and a call to
 294 .BR write (2).
 295
 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.
 306
 307 It is not advisable to mix calls to
 308 .BR readv ()
 309 or
 310 .BR writev (),
 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.
 313 .SH EXAMPLE
 314 The following code sample demonstrates the use of
 315 .BR writev ():
 316
 317 .in +4n
 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
 332 .SH SEE ALSO
 333 .BR pread (2),
 334 .BR read (2),
 335 .BR write (2)