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  2010-11-17 "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 Or, the vector count \fIiovcnt\fP is less than zero or greater than the
 208 permitted maximum.
 209 .SH VERSIONS
 210 .BR preadv ()
 211 and
 212 .BR pwritev ()
 213 first appeared in Linux 2.6.30; library support was added in glibc 2.10.
 214 .SH CONFORMING TO
 215 .BR readv (),
 216 .BR writev ():
 217 4.4BSD (these system calls first appeared in 4.2BSD), POSIX.1-2001.
 218 Linux libc5 used \fIsize_t\fP as the type of the \fIiovcnt\fP argument,
 219 and \fIint\fP as the return type.
 220 .\" The readv/writev system calls were buggy before Linux 1.3.40.
 221 .\" (Says release.libc.)
 222
 223 .BR preadv (),
 224 .BR pwritev ():
 225 nonstandard, but present also on the modern BSDs.
 226 .SH NOTES
 227 .SS Linux notes
 228 POSIX.1-2001 allows an implementation to place a limit on
 229 the number of items that can be passed in
 230 .IR iov .
 231 An implementation can advertise its limit by defining
 232 .B IOV_MAX
 233 in
 234 .I <limits.h>
 235 or at run time via the return value from
 236 .IR sysconf(_SC_IOV_MAX) .
 237 On Linux, the limit advertised by these mechanisms is 1024,
 238 which is the true kernel limit.
 239 However, the glibc wrapper functions do some extra work if
 240 they detect that the underlying kernel system call failed because this
 241 limit was exceeded.
 242 In the case of
 243 .BR readv ().
 244 the wrapper function allocates a temporary buffer large enough
 245 for all of the items specified by
 246 .IR iov ,
 247 passes that buffer in a call to
 248 .BR read (2),
 249 copies data from the buffer to the locations specified by the
 250 .I iov_base
 251 fields of the elements of
 252 .IR iov ,
 253 and then frees the buffer.
 254 The wrapper function for
 255 .BR writev ()
 256 performs the analogous task using a temporary buffer and a call to
 257 .BR write (2).
 258 .SH BUGS
 259 It is not advisable to mix calls to
 260 .BR readv ()
 261 or
 262 .BR writev (),
 263 which operate on file descriptors, with the functions from the stdio
 264 library; the results will be undefined and probably not what you want.
 265 .SH EXAMPLE
 266 The following code sample demonstrates the use of
 267 .BR writev ():
 268
 269 .in +4n
 270 .nf
 271 char *str0 = "hello ";
 272 char *str1 = "world\\n";
 273 struct iovec iov[2];
 274 ssize_t nwritten;
 275
 276 iov[0].iov_base = str0;
 277 iov[0].iov_len = strlen(str0);
 278 iov[1].iov_base = str1;
 279 iov[1].iov_len = strlen(str1);
 280
 281 nwritten = writev(STDOUT_FILENO, iov, 2);
 282 .fi
 283 .in
 284 .SH SEE ALSO
 285 .BR pread (2),
 286 .BR read (2),
 287 .BR write (2)
 288 .SH COLOPHON
 289 This page is part of release 3.68 of the Linux
 290 .I man-pages
 291 project.
 292 A description of the project,
 293 information about reporting bugs,
 294 and the latest version of this page,
 295 can be found at
 296 \%http://www.kernel.org/doc/man\-pages/.