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  2018-04-30 "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 .in +4n
  98 .EX
  99 struct iovec {
 100     void  *iov_base;    /* Starting address */
 101     size_t iov_len;     /* Number of bytes to transfer */
 102 };
 103 .EE
 104 .in
 105 .PP
 106 The
 107 .BR readv ()
 108 system call works just like
 109 .BR read (2)
 110 except that multiple buffers are filled.
 111 .PP
 112 The
 113 .BR writev ()
 114 system call works just like
 115 .BR write (2)
 116 except that multiple buffers are written out.
 117 .PP
 118 Buffers are processed in array order.
 119 This means that
 120 .BR readv ()
 121 completely fills
 122 .IR iov [0]
 123 before proceeding to
 124 .IR iov [1],
 125 and so on.
 126 (If there is insufficient data, then not all buffers pointed to by
 127 .I iov
 128 may be filled.)
 129 Similarly,
 130 .BR writev ()
 131 writes out the entire contents of
 132 .IR iov [0]
 133 before proceeding to
 134 .IR iov [1],
 135 and so on.
 136 .PP
 137 The data transfers performed by
 138 .BR readv ()
 139 and
 140 .BR writev ()
 141 are atomic: the data written by
 142 .\" Regarding atomicity, see https://bugzilla.kernel.org/show_bug.cgi?id=10596
 143 .BR writev ()
 144 is written as a single block that is not intermingled with output
 145 from writes in other processes (but see
 146 .BR pipe (7)
 147 for an exception);
 148 analogously,
 149 .BR readv ()
 150 is guaranteed to read a contiguous block of data from the file,
 151 regardless of read operations performed in other threads or processes
 152 that have file descriptors referring to the same open file description
 153 (see
 154 .BR open (2)).
 155 .SS preadv() and pwritev()
 156 The
 157 .BR preadv ()
 158 system call combines the functionality of
 159 .BR readv ()
 160 and
 161 .BR pread (2).
 162 It performs the same task as
 163 .BR readv (),
 164 but adds a fourth argument,
 165 .IR offset ,
 166 which specifies the file offset at which the input operation
 167 is to be performed.
 168 .PP
 169 The
 170 .BR pwritev ()
 171 system call combines the functionality of
 172 .BR writev ()
 173 and
 174 .BR pwrite (2).
 175 It performs the same task as
 176 .BR writev (),
 177 but adds a fourth argument,
 178 .IR offset ,
 179 which specifies the file offset at which the output operation
 180 is to be performed.
 181 .PP
 182 The file offset is not changed by these system calls.
 183 The file referred to by
 184 .I fd
 185 must be capable of seeking.
 186 .SS preadv2() and pwritev2()
 187 .PP
 188 These system calls are similar to
 189 .BR preadv ()
 190 and
 191 .BR pwritev ()
 192 calls, but add a fifth argument,
 193 .IR flags ,
 194 which modifies the behavior on a per-call basis.
 195 .PP
 196 Unlike
 197 .BR preadv ()
 198 and
 199 .BR pwritev (),
 200 if the
 201 .I offset
 202 argument is \-1, then the current file offset is used and updated.
 203 .PP
 204 The
 205 .I flags
 206 argument contains a bitwise OR of zero or more of the following flags:
 207 .TP
 208 .BR RWF_DSYNC " (since Linux 4.7)"
 209 .\" commit e864f39569f4092c2b2bc72c773b6e486c7e3bd9
 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 .TP
 218 .BR RWF_HIPRI " (since Linux 4.6)"
 219 High priority read/write.
 220 Allows block-based filesystems to use polling of the device,
 221 which provides lower latency, but may use additional resources.
 222 (Currently, this feature is usable only on a file descriptor opened using the
 223 .BR O_DIRECT
 224 flag.)
 225 .TP
 226 .BR RWF_SYNC " (since Linux 4.7)"
 227 .\" commit e864f39569f4092c2b2bc72c773b6e486c7e3bd9
 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 .TP
 236 .BR RWF_NOWAIT " (since Linux 4.14)"
 237 .\" commit 3239d834847627b6634a4139cf1dc58f6f137a46
 238 .\" commit 91f9943e1c7b6638f27312d03fe71fcc67b23571
 239 Do not wait for data which is not immediately available.
 240 If this flag is specified, the
 241 .BR preadv2 ()
 242 system call will return instantly if it would have to read data from
 243 the backing storage or wait for a lock.
 244 If some data was successfully read, it will return the number of bytes read.
 245 If no bytes were read, it will return -1 and set
 246 .IR errno
 247 to
 248 .BR EAGAIN .
 249 Currently, this flag is meaningful only for
 250 .BR preadv2 ().
 251 .TP
 252 .BR RWF_APPEND " (since Linux 4.16)"
 253 .\" commit e1fc742e14e01d84d9693c4aca4ab23da65811fb
 254 Provide a per-write equivalent of the
 255 .B O_APPEND
 256 .BR open (2)
 257 flag.
 258 This flag is meaningful only for
 259 .BR pwritev2 (),
 260 and its effect applies only to the data range written by the system call.
 261 The
 262 .I offset
 263 argument does not affect the write operation;
 264 the data is always appended to the end of the file.
 265 However, if the
 266 .I offset
 267 argument is \-1, the current file offset is updated.
 268 .SH RETURN VALUE
 269 On success,
 270 .BR readv (),
 271 .BR preadv ()
 272 and
 273 .BR preadv2 ()
 274 return the number of bytes read;
 275 .BR writev (),
 276 .BR pwritev ()
 277 and
 278 .BR pwritev2 ()
 279 return the number of bytes written.
 280 .PP
 281 Note that it is not an error for a successful call to transfer fewer bytes
 282 than requested (see
 283 .BR read (2)
 284 and
 285 .BR write (2)).
 286 .PP
 287 On error, \-1 is returned, and \fIerrno\fP is set appropriately.
 288 .SH ERRORS
 289 The errors are as given for
 290 .BR read (2)
 291 and
 292 .BR write (2).
 293 Furthermore,
 294 .BR preadv (),
 295 .BR preadv2 (),
 296 .BR pwritev (),
 297 and
 298 .BR pwritev2 ()
 299 can also fail for the same reasons as
 300 .BR lseek (2).
 301 Additionally, the following errors are defined:
 302 .TP
 303 .B EINVAL
 304 The sum of the
 305 .I iov_len
 306 values overflows an
 307 .I ssize_t
 308 value.
 309 .TP
 310 .B EINVAL
 311 The vector count,
 312 .IR iovcnt ,
 313 is less than zero or greater than the permitted maximum.
 314 .TP
 315 .B EOPNOTSUPP
 316 An unknown flag is specified in \fIflags\fP.
 317 .SH VERSIONS
 318 .BR preadv ()
 319 and
 320 .BR pwritev ()
 321 first appeared in Linux 2.6.30; library support was added in glibc 2.10.
 322 .PP
 323 .BR preadv2 ()
 324 and
 325 .BR pwritev2 ()
 326 first appeared in Linux 4.6.
 327 Library support was added in glibc 2.26.
 328 .SH CONFORMING TO
 329 .BR readv (),
 330 .BR writev ():
 331 POSIX.1-2001, POSIX.1-2008,
 332 4.4BSD (these system calls first appeared in 4.2BSD).
 333 .\" Linux libc5 used \fIsize_t\fP as the type of the \fIiovcnt\fP argument,
 334 .\" and \fIint\fP as the return type.
 335 .\" The readv/writev system calls were buggy before Linux 1.3.40.
 336 .\" (Says release.libc.)
 337 .PP
 338 .BR preadv (),
 339 .BR pwritev ():
 340 nonstandard, but present also on the modern BSDs.
 341 .PP
 342 .BR preadv2 (),
 343 .BR pwritev2 ():
 344 nonstandard Linux extension.
 345 .SH NOTES
 346 POSIX.1 allows an implementation to place a limit on
 347 the number of items that can be passed in
 348 .IR iov .
 349 An implementation can advertise its limit by defining
 350 .B IOV_MAX
 351 in
 352 .I <limits.h>
 353 or at run time via the return value from
 354 .IR sysconf(_SC_IOV_MAX) .
 355 On modern Linux systems, the limit is 1024.
 356 Back in Linux 2.0 days, this limit was 16.
 357 .\"
 358 .\"
 359 .SS C library/kernel differences
 360 The raw
 361 .BR preadv ()
 362 and
 363 .BR pwritev ()
 364 system calls have call signatures that differ slightly from that of the
 365 corresponding GNU C library wrapper functions shown in the SYNOPSIS.
 366 The final argument,
 367 .IR offset ,
 368 is unpacked by the wrapper functions into two arguments in the system calls:
 369 .PP
 370 .BI "    unsigned long " pos_l ", unsigned long " pos
 371 .PP
 372 These arguments contain, respectively, the low order and high order 32 bits of
 373 .IR offset .
 374 .SS Historical C library/kernel differences
 375 To deal with the fact that
 376 .B IOV_MAX
 377 was so low on early versions of Linux,
 378 the glibc wrapper functions for
 379 .BR readv ()
 380 and
 381 .BR writev ()
 382 did some extra work if they detected that the underlying kernel
 383 system call failed because this limit was exceeded.
 384 In the case of
 385 .BR readv (),
 386 the wrapper function allocated a temporary buffer large enough
 387 for all of the items specified by
 388 .IR iov ,
 389 passed that buffer in a call to
 390 .BR read (2),
 391 copied data from the buffer to the locations specified by the
 392 .I iov_base
 393 fields of the elements of
 394 .IR iov ,
 395 and then freed the buffer.
 396 The wrapper function for
 397 .BR writev ()
 398 performed the analogous task using a temporary buffer and a call to
 399 .BR write (2).
 400 .PP
 401 The need for this extra effort in the glibc wrapper functions
 402 went away with Linux 2.2 and later.
 403 However, glibc continued to provide this behavior until version 2.10.
 404 Starting with glibc version 2.9,
 405 the wrapper functions provide this behavior only if the library detects
 406 that the system is running a Linux kernel older than version 2.6.18
 407 (an arbitrarily selected kernel version).
 408 And since glibc 2.20
 409 (which requires a minimum Linux kernel version of 2.6.32),
 410 the glibc wrapper functions always just directly invoke the system calls.
 411 .SH EXAMPLE
 412 The following code sample demonstrates the use of
 413 .BR writev ():
 414 .PP
 415 .in +4n
 416 .EX
 417 char *str0 = "hello ";
 418 char *str1 = "world\en";
 419 struct iovec iov[2];
 420 ssize_t nwritten;
 421
 422 iov[0].iov_base = str0;
 423 iov[0].iov_len = strlen(str0);
 424 iov[1].iov_base = str1;
 425 iov[1].iov_len = strlen(str1);
 426
 427 nwritten = writev(STDOUT_FILENO, iov, 2);
 428 .EE
 429 .in
 430 .SH SEE ALSO
 431 .BR pread (2),
 432 .BR read (2),
 433 .BR write (2)