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