original/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-01-22 "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 _BSD_SOURCE
  58 .SH DESCRIPTION
  59 The
  60 .BR readv ()
  61 system call reads
  62 .I iovcnt
  63 buffers from the file associated with the file descriptor
  64 .I fd
  65 into the buffers described by
  66 .I iov
  67 ("scatter input").
  68 .PP
  69 The
  70 .BR writev ()
  71 system call writes
  72 .I iovcnt
  73 buffers of data described by
  74 .I iov
  75 to the file associated with the file descriptor
  76 .I fd
  77 ("gather output").
  78 .PP
  79 The pointer
  80 .I iov
  81 points to an array of
  82 .I iovec
  83 structures,
  84 defined in
  85 .I <sys/uio.h>
  86 as:
  87 .PP
  88 .br
  89 .in +4n
  90 .nf
  91 struct iovec {
  92     void  *iov_base;    /* Starting address */
  93     size_t iov_len;     /* Number of bytes to transfer */
  94 };
  95 .fi
  96 .in
  97 .PP
  98 The
  99 .BR readv ()
 100 system call works just like
 101 .BR read (2)
 102 except that multiple buffers are filled.
 103 .PP
 104 The
 105 .BR writev ()
 106 system call works just like
 107 .BR write (2)
 108 except that multiple buffers are written out.
 109 .PP
 110 Buffers are processed in array order.
 111 This means that
 112 .BR readv ()
 113 completely fills
 114 .IR iov [0]
 115 before proceeding to
 116 .IR iov [1],
 117 and so on.
 118 (If there is insufficient data, then not all buffers pointed to by
 119 .I iov
 120 may be filled.)
 121 Similarly,
 122 .BR writev ()
 123 writes out the entire contents of
 124 .IR iov [0]
 125 before proceeding to
 126 .IR iov [1],
 127 and so on.
 128 .PP
 129 The data transfers performed by
 130 .BR readv ()
 131 and
 132 .BR writev ()
 133 are atomic: the data written by
 134 .BR writev ()
 135 is written as a single block that is not intermingled with output
 136 from writes in other processes (but see
 137 .BR pipe (7)
 138 for an exception);
 139 analogously,
 140 .BR readv ()
 141 is guaranteed to read a contiguous block of data from the file,
 142 regardless of read operations performed in other threads or processes
 143 that have file descriptors referring to the same open file description
 144 (see
 145 .BR open (2)).
 146 .SS preadv() and pwritev()
 147 The
 148 .BR preadv ()
 149 system call combines the functionality of
 150 .BR readv ()
 151 and
 152 .BR pread (2).
 153 It performs the same task as
 154 .BR readv (),
 155 but adds a fourth argument,
 156 .IR offset ,
 157 which specifies the file offset at which the input operation
 158 is to be performed.
 159
 160 The
 161 .BR pwritev ()
 162 system call combines the functionality of
 163 .BR writev ()
 164 and
 165 .BR pwrite (2).
 166 It performs the same task as
 167 .BR writev (),
 168 but adds a fourth argument,
 169 .IR offset ,
 170 which specifies the file offset at which the output operation
 171 is to be performed.
 172
 173 The file offset is not changed by these system calls.
 174 The file referred to by
 175 .I fd
 176 must be capable of seeking.
 177 .SH RETURN VALUE
 178 On success,
 179 .BR readv ()
 180 and
 181 .BR preadv ()
 182 return the number of bytes read;
 183 .BR writev ()
 184 and
 185 .BR pwritev ()
 186 return the number of bytes written.
 187 On error, \-1 is returned, and \fIerrno\fP is set appropriately.
 188 .SH ERRORS
 189 The errors are as given for
 190 .BR read (2)
 191 and
 192 .BR write (2).
 193 Furthermore,
 194 .BR preadv ()
 195 and
 196 .BR pwritev ()
 197 can also fail for the same reasons as
 198 .BR lseek (2).
 199 Additionally, the following error is defined:
 200 .TP
 201 .B EINVAL
 202 The sum of the
 203 .I iov_len
 204 values overflows an
 205 .I ssize_t
 206 value.
 207 .TP
 208 .B EINVAL
 209 The vector count \fIiovcnt\fP is less than zero or greater than the
 210 permitted maximum.
 211 .SH VERSIONS
 212 .BR preadv ()
 213 and
 214 .BR pwritev ()
 215 first appeared in Linux 2.6.30; library support was added in glibc 2.10.
 216 .SH CONFORMING TO
 217 .BR readv (),
 218 .BR writev ():
 219 4.4BSD (these system calls first appeared in 4.2BSD), POSIX.1-2001.
 220 .\" Linux libc5 used \fIsize_t\fP as the type of the \fIiovcnt\fP argument,
 221 .\" and \fIint\fP as the return type.
 222 .\" The readv/writev system calls were buggy before Linux 1.3.40.
 223 .\" (Says release.libc.)
 224
 225 .BR preadv (),
 226 .BR pwritev ():
 227 nonstandard, but present also on the modern BSDs.
 228 .SH NOTES
 229 POSIX.1-2001 allows an implementation to place a limit on
 230 the number of items that can be passed in
 231 .IR iov .
 232 An implementation can advertise its limit by defining
 233 .B IOV_MAX
 234 in
 235 .I <limits.h>
 236 or at run time via the return value from
 237 .IR sysconf(_SC_IOV_MAX) .
 238 On modern Linux systems, the limit is 1024.
 239 Back in Linux 2.0 days, this limit was 16.
 240 \"
 241 \"
 242 .SS C library/kernel ABI differences
 243 The raw
 244 .BR preadv ()
 245 and
 246 .BR pwritev ()
 247 system calls have call signatures that differ slightly from that of the
 248 corresponding GNU C library wrapper functions shown in the SYNOPSIS.
 249 The final argument,
 250 .IR offset ,
 251 is unpacked by the wrapper functions into two arguments in the system calls:
 252
 253 .BI "    unsigned long " pos_l ", unsigned long " pos
 254
 255 These arguments contain, respectively, the low order and high order 32 bits of
 256 .IR offset .
 257 .SS Historical C library/kernel ABI differences
 258 To deal with the fact that
 259 .B IOV_MAX
 260 was so low on early versions of Linux,
 261 the glibc wrapper functions for
 262 .BR readv ()
 263 and
 264 .BR writev ()
 265 did some extra work if they detected that the underlying kernel
 266 system call failed because this limit was exceeded.
 267 In the case of
 268 .BR readv (),
 269 the wrapper function allocated a temporary buffer large enough
 270 for all of the items specified by
 271 .IR iov ,
 272 passed that buffer in a call to
 273 .BR read (2),
 274 copied data from the buffer to the locations specified by the
 275 .I iov_base
 276 fields of the elements of
 277 .IR iov ,
 278 and then freed the buffer.
 279 The wrapper function for
 280 .BR writev ()
 281 performed the analogous task using a temporary buffer and a call to
 282 .BR write (2).
 283
 284 The need for this extra effort in the glibc wrapper functions
 285 went away with Linux 2.2 and later.
 286 However, glibc continued to provide this behavior until version 2.10.
 287 Starting with glibc version 2.9,
 288 the wrapper functions provide this behavior only if the library detects
 289 that the system is running a Linux kernel older than version 2.6.18
 290 (an arbitrarily selected kernel version).
 291 And since glibc 2.20
 292 (which requires a minimum Linux kernel version of 2.6.32),
 293 the glibc wrapper functions always just directly invoke the system calls.
 294 .SH BUGS
 295 It is not advisable to mix calls to
 296 .BR readv ()
 297 or
 298 .BR writev (),
 299 which operate on file descriptors, with the functions from the stdio
 300 library; the results will be undefined and probably not what you want.
 301 .SH EXAMPLE
 302 The following code sample demonstrates the use of
 303 .BR writev ():
 304
 305 .in +4n
 306 .nf
 307 char *str0 = "hello ";
 308 char *str1 = "world\\n";
 309 struct iovec iov[2];
 310 ssize_t nwritten;
 311
 312 iov[0].iov_base = str0;
 313 iov[0].iov_len = strlen(str0);
 314 iov[1].iov_base = str1;
 315 iov[1].iov_len = strlen(str1);
 316
 317 nwritten = writev(STDOUT_FILENO, iov, 2);
 318 .fi
 319 .in
 320 .SH SEE ALSO
 321 .BR pread (2),
 322 .BR read (2),
 323 .BR write (2)
 324 .SH COLOPHON
 325 This page is part of release 3.78 of the Linux
 326 .I man-pages
 327 project.
 328 A description of the project,
 329 information about reporting bugs,
 330 and the latest version of this page,
 331 can be found at
 332 \%http://www.kernel.org/doc/man\-pages/.