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  2017-07-13 "Linux" "Linux Programmer's Manual"
  33 .SH NAME
  34 readv, writev, preadv, pwritev, preadv2, pwritev2 \- read or write data into multiple buffers
  35 .SH SYNOPSIS
  36 .nf
  37 .B #include <sys/uio.h>
  38 .PP
  39 .BI "ssize_t readv(int " fd ", const struct iovec *" iov ", int " iovcnt );
  40 .PP
  41 .BI "ssize_t writev(int " fd ", const struct iovec *" iov ", int " iovcnt );
  42 .PP
  43 .BI "ssize_t preadv(int " fd ", const struct iovec *" iov ", int " iovcnt ,
  44 .BI "               off_t " offset );
  45 .PP
  46 .BI "ssize_t pwritev(int " fd ", const struct iovec *" iov ", int " iovcnt ,
  47 .BI "                off_t " offset );
  48 .PP
  49 .BI "ssize_t preadv2(int " fd ", const struct iovec *" iov ", int " iovcnt ,
  50 .BI "                off_t " offset ", int " flags );
  51 .PP
  52 .BI "ssize_t pwritev2(int " fd ", const struct iovec *" iov ", int " iovcnt ,
  53 .BI "                 off_t " offset ", int " flags );
  54 .fi
  55 .PP
  56 .in -4n
  57 Feature Test Macro Requirements for glibc (see
  58 .BR feature_test_macros (7)):
  59 .in
  60 .PP
  61 .BR preadv (),
  62 .BR pwritev ():
  63     Since glibc 2.19:
  64         _DEFAULT_SOURCE
  65     Glibc 2.19 and earlier:
  66         _BSD_SOURCE
  67 .SH DESCRIPTION
  68 The
  69 .BR readv ()
  70 system call reads
  71 .I iovcnt
  72 buffers from the file associated with the file descriptor
  73 .I fd
  74 into the buffers described by
  75 .I iov
  76 ("scatter input").
  77 .PP
  78 The
  79 .BR writev ()
  80 system call writes
  81 .I iovcnt
  82 buffers of data described by
  83 .I iov
  84 to the file associated with the file descriptor
  85 .I fd
  86 ("gather output").
  87 .PP
  88 The pointer
  89 .I iov
  90 points to an array of
  91 .I iovec
  92 structures,
  93 defined in
  94 .I <sys/uio.h>
  95 as:
  96 .PP
  97 .br
  98 .in +4n
  99 .nf
 100 struct iovec {
 101     void  *iov_base;    /* Starting address */
 102     size_t iov_len;     /* Number of bytes to transfer */
 103 };
 104 .fi
 105 .in
 106 .PP
 107 The
 108 .BR readv ()
 109 system call works just like
 110 .BR read (2)
 111 except that multiple buffers are filled.
 112 .PP
 113 The
 114 .BR writev ()
 115 system call works just like
 116 .BR write (2)
 117 except that multiple buffers are written out.
 118 .PP
 119 Buffers are processed in array order.
 120 This means that
 121 .BR readv ()
 122 completely fills
 123 .IR iov [0]
 124 before proceeding to
 125 .IR iov [1],
 126 and so on.
 127 (If there is insufficient data, then not all buffers pointed to by
 128 .I iov
 129 may be filled.)
 130 Similarly,
 131 .BR writev ()
 132 writes out the entire contents of
 133 .IR iov [0]
 134 before proceeding to
 135 .IR iov [1],
 136 and so on.
 137 .PP
 138 The data transfers performed by
 139 .BR readv ()
 140 and
 141 .BR writev ()
 142 are atomic: the data written by
 143 .\" Regarding atomicity, see https://bugzilla.kernel.org/show_bug.cgi?id=10596
 144 .BR writev ()
 145 is written as a single block that is not intermingled with output
 146 from writes in other processes (but see
 147 .BR pipe (7)
 148 for an exception);
 149 analogously,
 150 .BR readv ()
 151 is guaranteed to read a contiguous block of data from the file,
 152 regardless of read operations performed in other threads or processes
 153 that have file descriptors referring to the same open file description
 154 (see
 155 .BR open (2)).
 156 .SS preadv() and pwritev()
 157 The
 158 .BR preadv ()
 159 system call combines the functionality of
 160 .BR readv ()
 161 and
 162 .BR pread (2).
 163 It performs the same task as
 164 .BR readv (),
 165 but adds a fourth argument,
 166 .IR offset ,
 167 which specifies the file offset at which the input operation
 168 is to be performed.
 169
 170 The
 171 .BR pwritev ()
 172 system call combines the functionality of
 173 .BR writev ()
 174 and
 175 .BR pwrite (2).
 176 It performs the same task as
 177 .BR writev (),
 178 but adds a fourth argument,
 179 .IR offset ,
 180 which specifies the file offset at which the output operation
 181 is to be performed.
 182
 183 The file offset is not changed by these system calls.
 184 The file referred to by
 185 .I fd
 186 must be capable of seeking.
 187 .SS preadv2() and pwritev2()
 188
 189 These system calls are similar to
 190 .BR preadv ()
 191 and
 192 .BR pwritev ()
 193 calls, but add a fifth argument,
 194 .IR flags ,
 195 which modifies the behavior on a per-call basis.
 196
 197 Unlike
 198 .BR preadv ()
 199 and
 200 .BR pwritev (),
 201 if the
 202 .I offset
 203 argument is \-1, then the current file offset is used and updated.
 204
 205 The
 206 .I flags
 207 argument contains a bitwise OR of zero or more of the following flags:
 208 .TP
 209 .BR RWF_DSYNC " (since Linux 4.7)"
 210 Provide a per-write equivalent of the
 211 .B O_DSYNC
 212 .BR open (2)
 213 flag.
 214 This flag is meaningful only for
 215 .BR pwritev2 (),
 216 and its effect applies only to the data range written by the system call.
 217 .\" commit e864f39569f4092c2b2bc72c773b6e486c7e3bd9
 218 .TP
 219 .BR RWF_HIPRI " (since Linux 4.6)"
 220 High priority read/write.
 221 Allows block-based filesystems to use polling of the device,
 222 which provides lower latency, but may use additional resources.
 223 (Currently, this feature is usable only on a file descriptor opened using the
 224 .BR O_DIRECT
 225 flag.)
 226 .TP
 227 .BR RWF_SYNC " (since Linux 4.7)"
 228 Provide a per-write equivalent of the
 229 .B O_SYNC
 230 .BR open (2)
 231 flag.
 232 This flag is meaningful only for
 233 .BR pwritev2 (),
 234 and its effect applies only to the data range written by the system call.
 235 .\" commit e864f39569f4092c2b2bc72c773b6e486c7e3bd9
 236 .SH RETURN VALUE
 237 On success,
 238 .BR readv (),
 239 .BR preadv ()
 240 and
 241 .BR preadv2 ()
 242 return the number of bytes read;
 243 .BR writev (),
 244 .BR pwritev ()
 245 and
 246 .BR pwritev2 ()
 247 return the number of bytes written.
 248
 249 Note that it is not an error for a successful call to transfer fewer bytes
 250 than requested (see
 251 .BR read (2)
 252 and
 253 .BR write (2)).
 254
 255 On error, \-1 is returned, and \fIerrno\fP is set appropriately.
 256 .SH ERRORS
 257 The errors are as given for
 258 .BR read (2)
 259 and
 260 .BR write (2).
 261 Furthermore,
 262 .BR preadv (),
 263 .BR preadv2 (),
 264 .BR pwritev (),
 265 and
 266 .BR pwritev2 ()
 267 can also fail for the same reasons as
 268 .BR lseek (2).
 269 Additionally, the following errors are defined:
 270 .TP
 271 .B EINVAL
 272 The sum of the
 273 .I iov_len
 274 values overflows an
 275 .I ssize_t
 276 value.
 277 .TP
 278 .B EINVAL
 279 The vector count,
 280 .IR iovcnt ,
 281 is less than zero or greater than the permitted maximum.
 282 .TP
 283 .B EINVAL
 284 An unknown flag is specified in \fIflags\fP.
 285 .SH VERSIONS
 286 .BR preadv ()
 287 and
 288 .BR pwritev ()
 289 first appeared in Linux 2.6.30; library support was added in glibc 2.10.
 290
 291 .BR preadv2 ()
 292 and
 293 .BR pwritev2 ()
 294 first appeared in Linux 4.6.
 295 Library support was added in glibc 2.26.
 296 .SH CONFORMING TO
 297 .BR readv (),
 298 .BR writev ():
 299 POSIX.1-2001, POSIX.1-2008,
 300 4.4BSD (these system calls first appeared in 4.2BSD).
 301 .\" Linux libc5 used \fIsize_t\fP as the type of the \fIiovcnt\fP argument,
 302 .\" and \fIint\fP as the return type.
 303 .\" The readv/writev system calls were buggy before Linux 1.3.40.
 304 .\" (Says release.libc.)
 305
 306 .BR preadv (),
 307 .BR pwritev ():
 308 nonstandard, but present also on the modern BSDs.
 309 .sp
 310 .BR preadv2 (),
 311 .BR pwritev2 ():
 312 nonstandard Linux extension.
 313 .SH NOTES
 314 POSIX.1 allows an implementation to place a limit on
 315 the number of items that can be passed in
 316 .IR iov .
 317 An implementation can advertise its limit by defining
 318 .B IOV_MAX
 319 in
 320 .I <limits.h>
 321 or at run time via the return value from
 322 .IR sysconf(_SC_IOV_MAX) .
 323 On modern Linux systems, the limit is 1024.
 324 Back in Linux 2.0 days, this limit was 16.
 325 .\"
 326 .\"
 327 .SS C library/kernel differences
 328 The raw
 329 .BR preadv ()
 330 and
 331 .BR pwritev ()
 332 system calls have call signatures that differ slightly from that of the
 333 corresponding GNU C library wrapper functions shown in the SYNOPSIS.
 334 The final argument,
 335 .IR offset ,
 336 is unpacked by the wrapper functions into two arguments in the system calls:
 337
 338 .BI "    unsigned long " pos_l ", unsigned long " pos
 339
 340 These arguments contain, respectively, the low order and high order 32 bits of
 341 .IR offset .
 342 .SS Historical C library/kernel differences
 343 To deal with the fact that
 344 .B IOV_MAX
 345 was so low on early versions of Linux,
 346 the glibc wrapper functions for
 347 .BR readv ()
 348 and
 349 .BR writev ()
 350 did some extra work if they detected that the underlying kernel
 351 system call failed because this limit was exceeded.
 352 In the case of
 353 .BR readv (),
 354 the wrapper function allocated a temporary buffer large enough
 355 for all of the items specified by
 356 .IR iov ,
 357 passed that buffer in a call to
 358 .BR read (2),
 359 copied data from the buffer to the locations specified by the
 360 .I iov_base
 361 fields of the elements of
 362 .IR iov ,
 363 and then freed the buffer.
 364 The wrapper function for
 365 .BR writev ()
 366 performed the analogous task using a temporary buffer and a call to
 367 .BR write (2).
 368
 369 The need for this extra effort in the glibc wrapper functions
 370 went away with Linux 2.2 and later.
 371 However, glibc continued to provide this behavior until version 2.10.
 372 Starting with glibc version 2.9,
 373 the wrapper functions provide this behavior only if the library detects
 374 that the system is running a Linux kernel older than version 2.6.18
 375 (an arbitrarily selected kernel version).
 376 And since glibc 2.20
 377 (which requires a minimum Linux kernel version of 2.6.32),
 378 the glibc wrapper functions always just directly invoke the system calls.
 379 .SH EXAMPLE
 380 The following code sample demonstrates the use of
 381 .BR writev ():
 382
 383 .in +4n
 384 .nf
 385 char *str0 = "hello ";
 386 char *str1 = "world\\n";
 387 struct iovec iov[2];
 388 ssize_t nwritten;
 389
 390 iov[0].iov_base = str0;
 391 iov[0].iov_len = strlen(str0);
 392 iov[1].iov_base = str1;
 393 iov[1].iov_len = strlen(str1);
 394
 395 nwritten = writev(STDOUT_FILENO, iov, 2);
 396 .fi
 397 .in
 398 .SH SEE ALSO
 399 .BR pread (2),
 400 .BR read (2),
 401 .BR write (2)