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