draft/man2/readv.2

   1 .\" Hey Emacs! This file is -*- nroff -*- source.
   2 .\"
   3 .\" Copyright (C) 2007 Michael Kerrisk <mtk.manpages@gmail.com>
   4 .\" and Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de)
   5 .\"
   6 .\" Permission is granted to make and distribute verbatim copies of this
   7 .\" manual provided the copyright notice and this permission notice are
   8 .\" preserved on all copies.
   9 .\"
  10 .\" Permission is granted to copy and distribute modified versions of this
  11 .\" manual under the conditions for verbatim copying, provided that the
  12 .\" entire resulting derived work is distributed under the terms of a
  13 .\" permission notice identical to this one.
  14 .\"
  15 .\" Since the Linux kernel and libraries are constantly changing, this
  16 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  17 .\" responsibility for errors or omissions, or for damages resulting from
  18 .\" the use of the information contained herein.  The author(s) may not
  19 .\" have taken the same level of care in the production of this manual,
  20 .\" which is licensed free of charge, as they might when working
  21 .\" professionally.
  22 .\"
  23 .\" Formatted or processed versions of this manual, if unaccompanied by
  24 .\" the source, must acknowledge the copyright and authors of this work.
  25 .\" License.
  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 .\"
  31 .\" 1996-04-12 Tom Bjorkholm <tomb@mydata.se>
  32 .\"            First version written
  33 .\" Modified Tue Oct 22 17:41:07 1996 by Eric S. Raymond <esr@thyrsus.com>
  34 .\"
  35 .\" Japanese Version Copyright (c) 1997-1999 HANATAKA Shinya
  36 .\"         all rights reserved.
  37 .\" Translated 1997-02-23, HANATAKA Shinya <hanataka@abyss.rim.or.jp>
  38 .\" Updated 1999-04-03, HANATAKA Shinya
  39 .\" Updated 2003-01-14, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
  40 .\" Updated 2005-10-07, Akihiro MOTOKI
  41 .\" Updated 2007-06-01, Akihiro MOTOKI, LDP v2.50
  42 .\"
  43 .\"WORD:        vector                  ベクタ (vector)
  44 .\"WORD:        file descriptor         ファイルディスクリプタ
  45 .\"WORD:        buffer                  バッファ
  46 .\"
  47 .TH READV 2  2002-10-17 "Linux" "Linux Programmer's Manual"
  48 .\"O .SH NAME
  49 .\"O readv, writev \- read or write data into multiple buffers
  50 .SH 名前
  51 readv, writev \- 複数のバッファへの読み書きを行なう
  52 .\"O .SH SYNOPSIS
  53 .SH 書式
  54 .nf
  55 .B #include <sys/uio.h>
  56 .sp
  57 .BI "ssize_t readv(int " fd ", const struct iovec *" iov ", int " iovcnt );
  58 .sp
  59 .BI "ssize_t writev(int " fd ", const struct iovec *" iov ", int " iovcnt );
  60 .fi
  61 .\"O .SH DESCRIPTION
  62 .SH 説明
  63 .\"O The
  64 .\"O .BR readv ()
  65 .\"O function reads
  66 .\"O .I iovcnt
  67 .\"O buffers from the file associated with the file descriptor
  68 .\"O .I fd
  69 .\"O into the buffers described by
  70 .\"O .I iov
  71 .\"O ("scatter input").
  72 .BR readv ()
  73 関数は、ファイルディスクリプタ
  74 .I fd
  75 に関連付けられたファイルから、
  76 .I iovcnt
  77 個のバッファ分のデータを読み込み、
  78 .I iov
  79 で指定されたバッファに格納する
  80 ("scatter input";「ばらまき入力」)。
  81 .PP
  82 .\"O The
  83 .\"O .BR writev ()
  84 .\"O function writes at most
  85 .\"O .I iovcnt
  86 .\"O buffers described by
  87 .\"O .I iov
  88 .\"O to the file associated with the file descriptor
  89 .\"O .I fd
  90 .\"O ("gather output").
  91 .BR writev ()
  92 関数は、
  93 .I iov
  94 で指定されたバッファから最大
  95 .I iovcnt
  96 個のバッファ分のデータを取り出し、
  97 ファイルディスクリプタ
  98 .I fd
  99 に関連付けられたファイルに書き込む
 100 ("gather output";「かき集め出力」)。
 101 .PP
 102 .\"O The pointer
 103 .\"O .I iov
 104 .\"O points to an array of
 105 .\"O .I iovec
 106 .\"O structures,
 107 .\"O defined in
 108 .\"O .I <sys/uio.h>
 109 .\"O as:
 110 ポインタ
 111 .I iov
 112 は
 113 .I iovec
 114 構造体の配列へのポインタである。
 115 .I iovec
 116 構造体は
 117 .I <sys/uio.h>
 118 で以下のように定義されている:
 119 .PP
 120 .br
 121 .in +4n
 122 .nf
 123 struct iovec {
 124     void  *iov_base;    /* Starting address */
 125     size_t iov_len;     /* Number of bytes to transfer */
 126 };
 127 .fi
 128 .in
 129 .PP
 130 .\"O The
 131 .\"O .BR readv ()
 132 .\"O function works just like
 133 .\"O .BR read (2)
 134 .\"O except that multiple buffers are filled.
 135 .BR readv ()
 136 関数は、複数のバッファにデータを読み込む点を除いて
 137 .BR read (2)
 138 と全く同様の動作を行う。
 139 .PP
 140 .\"O The
 141 .\"O .BR writev ()
 142 .\"O function works just like
 143 .\"O .BR write (2)
 144 .\"O except that multiple buffers are written out.
 145 .BR writev ()
 146 関数は、複数のバッファのデータを書き出す点以外は
 147 .BR write (2)
 148 と全く同様の動作を行う。
 149 .PP
 150 .\"O Buffers are processed in array order.
 151 .\"O This means that
 152 .\"O .BR readv ()
 153 .\"O completely fills
 154 .\"O .IR iov [0]
 155 .\"O before proceeding to
 156 .\"O .IR iov [1],
 157 .\"O and so on.
 158 .\"O (If there is insufficient data, then not all buffers pointed to by
 159 .\"O .I iov
 160 .\"O may be filled.)
 161 .\"O Similarly,
 162 .\"O .BR writev ()
 163 .\"O writes out the entire contents of
 164 .\"O .IR iov [0]
 165 .\"O before proceeding to
 166 .\"O .IR iov [1],
 167 .\"O and so on.
 168 バッファは配列の順序で処理される。これは、
 169 .BR readv ()
 170 が
 171 .IR iov [0]
 172 が完全に一杯になるまでデータを詰めてから、
 173 .IR iov [1]
 174 などに進むことを意味する
 175 (データが十分ない場合は、
 176 .I iov
 177 が指すバッファのいずれも一杯にならない)。
 178 同様に、
 179 .BR writev ()
 180 は
 181 .IR iov [0]
 182 の内容を全部書き出してから
 183 .IR iov [1]
 184 などに進む。
 185 .PP
 186 .\"O The data transfers performed by
 187 .\"O .BR readv ()
 188 .\"O and
 189 .\"O .BR writev ()
 190 .\"O are atomic: the data written by
 191 .\"O .BR writev ()
 192 .\"O is written as a single block that is not intermingled with output
 193 .\"O from writes in other processes (but see
 194 .\"O .BR pipe (7)
 195 .\"O for an exception);
 196 .\"O analogously,
 197 .\"O .BR readv ()
 198 .\"O is guaranteed to read a contiguous block of data from the file,
 199 .\"O regardless of read operations performed in other threads or processes
 200 .\"O that have file descriptors referring to the same open file description
 201 .\"O (see
 202 .\"O .BR open (2)).
 203 .BR readv ()
 204 と
 205 .BR writev ()
 206 によるデータ転送は atomic に行われる。つまり、
 207 .BR writev ()
 208 によるデータ書き込みは一つのブロックとして行われ、他のプロセスの
 209 write による書き込みと混ざり合うことはない
 210 (例外に関しては
 211 .BR pipe (7)
 212 を参照のこと)。同様に、
 213 .BR readv ()
 214 はファイルから連続するデータブロックが読み出すことが保証され、
 215 同じファイル記述 (file description;
 216 .BR open (2)
 217 参照) を参照するファイルディスクリプタを持つ他のスレッドやプロセスが
 218 実行した read 操作の影響を受けることはない。
 219 .\"O .SH "RETURN VALUE"
 220 .SH 返り値
 221 .\"O On success, the
 222 .\"O .BR readv ()
 223 .\"O function returns the number of bytes read; the
 224 .\"O .BR writev ()
 225 .\"O function returns the number of bytes written.
 226 .\"O On error, \-1 is returned, and \fIerrno\fP is set appropriately.
 227 成功した場合、
 228 .BR readv ()
 229 関数は読み込んだバイト数を返し、
 230 .BR writev ()
 231 関数は書き込んだバイト数を返す。
 232 エラーの場合 \-1 を返し、\fIerrno\fP を適切に設定する。
 233 .\"O .SH ERRORS
 234 .SH エラー
 235 .\"O The errors are as given for
 236 .\"O .BR read (2)
 237 .\"O and
 238 .\"O .BR write (2).
 239 .BR read (2)
 240 や
 241 .BR write (2)
 242 と同じエラーが定義されている。
 243 .\"O Additionally the following error is defined:
 244 さらに以下のエラーが定義されている:
 245 .TP
 246 .B EINVAL
 247 .\"O The sum of the
 248 .\"O .I iov_len
 249 .\"O values overflows an
 250 .\"O .I ssize_t
 251 .\"O value.
 252 .\"O Or, the vector count \fIiovcnt\fP is less than zero or greater than the
 253 .\"O permitted maximum.
 254 .I iov_len
 255 の合計が
 256 .I ssize_t
 257 の範囲をオーバーフローした。もしくは、
 258 ベクタ数 \fIiovcnt\fP が 0 より小さいか許可された最大値よりも大きかった。
 259 .\"O .SH "CONFORMING TO"
 260 .SH 準拠
 261 .\"O 4.4BSD (the
 262 .\"O .BR readv ()
 263 .\"O and
 264 .\"O .BR writev ()
 265 .\"O functions first appeared in 4.2BSD), POSIX.1-2001.
 266 .\"O Linux libc5 used \fIsize_t\fP as the type of the \fIiovcnt\fP argument,
 267 .\"O and \fIint\fP as return type for these functions.
 268 .\"O .\" The readv/writev system calls were buggy before Linux 1.3.40.
 269 .\"O .\" (Says release.libc.)
 270 4.4BSD
 271 .RB ( readv ()
 272 と
 273 .BR writev ()
 274 関数は 4.2BSD で最初に現われた)、POSIX.1-2001。
 275 Linux libc5 では \fIiovcnt\fP 引き数の型として \fIsize_t\fP を、
 276 これらの関数の返り値として \fIint\fP を使用していた。
 277 .\" readv/writev システムコールは Linux 1.3.40 以前はバグだらけであった
 278 .\" (と release.libc に書かれている)。
 279 .\"O .SH NOTES
 280 .\"O .SS Linux Notes
 281 .SH 注意
 282 .SS "Linux での注意"
 283 .\"O POSIX.1-2001 allows an implementation to place a limit on
 284 .\"O the number of items that can be passed in
 285 .\"O .IR iov .
 286 .\"O An implementation can advertise its limit by defining
 287 .\"O .B IOV_MAX
 288 .\"O in
 289 .\"O .IR <limits.h>
 290 .\"O or at run time via the return value from
 291 .\"O .IR sysconf(_SC_IOV_MAX) .
 292 .\"O On Linux, the limit advertised by these mechanisms is 1024,
 293 .\"O which is the true kernel limit.
 294 POSIX.1-2001 では、
 295 .I iov
 296 で渡すことができる要素数に上限を設ける実装が認められている。
 297 実装は、
 298 .I <limits.h>
 299 の
 300 .B IOV_MAX
 301 を定義することや、実行時に
 302 .I sysconf(_SC_IOV_MAX)
 303 の返り値経由で、この上限を広告することができる。
 304 Linux では、この仕組みにより広告される上限は 1024 であり、
 305 この値はカーネルでの上限そのものである。
 306 .\"O However, the glibc wrapper functions do some extra work if
 307 .\"O they detect that the underlying kernel system call failed because this
 308 .\"O limit was exceeded.
 309 .\"O In the case of
 310 .\"O .BR readv ()
 311 .\"O the wrapper function allocates a temporary buffer large enough
 312 .\"O for all of the items specified by
 313 .\"O .IR iov ,
 314 .\"O passes that buffer in a call to
 315 .\"O .BR read (2),
 316 .\"O copies data from the buffer to the locations specified by the
 317 .\"O .I iov_base
 318 .\"O fields of the elements of
 319 .\"O .IR iov ,
 320 .\"O and then frees the buffer.
 321 .\"O The wrapper function for
 322 .\"O .BR writev ()
 323 .\"O performs the analogous task using a temporary buffer and a call to
 324 .\"O .BR write (2).
 325 一方で、glibc のラッパー関数は、その関数の内部で呼ばれるカーネル・
 326 システムコールがこの上限を超過して失敗したことを検出すると、
 327 追加の動作をする。
 328 .BR readv ()
 329 の場合、ラッパー関数は
 330 .I iov
 331 で指定された全ての要素を格納できる大きさの一時バッファを割り当て、
 332 .BR read (2)
 333 を呼び出す際にそのバッファを渡し、
 334 そのバッファのデータを
 335 .I iov
 336 の各要素の
 337 .I iov_base
 338 フィールドが指定する場所にコピーしてから、
 339 そのバッファを解放する。
 340 .BR writev ()
 341 のラッパー関数も、同じように一時バッファを使って
 342 .BR write (2)
 343 を呼び出す。
 344 .\"O .SH BUGS
 345 .SH バグ
 346 .\"O It is not advisable to mix calls to functions like
 347 .\"O .BR readv ()
 348 .\"O or
 349 .\"O .BR writev (),
 350 .\"O which operate on file descriptors, with the functions from the stdio
 351 .\"O library; the results will be undefined and probably not what you want.
 352 .BR readv ()
 353 や
 354 .BR writev ()
 355 のようなファイルディスクリプタに対する操作を行う関数と、
 356 標準入出力ライブラリの関数をごちゃまぜにして呼ぶのはお薦めしない。
 357 どんな結果になるかは定義されておらず、
 358 おそらく欲しい結果は得られないだろう。
 359 .\"O .SH EXAMPLE
 360 .SH 例
 361 .\"O The following code sample demonstrates the use of
 362 .\"O .BR writev ():
 363 以下のサンプルコードは
 364 .BR writev ()
 365 の使用方法を示すものである。
 366
 367 .in +4n
 368 .nf
 369 char *str0 = "hello ";
 370 char *str1 = "world\\n";
 371 struct iovec iov[2];
 372 ssize_t nwritten;
 373
 374 iov[0].iov_base = str0;
 375 iov[0].iov_len = strlen(str0);
 376 iov[1].iov_base = str1;
 377 iov[1].iov_len = strlen(str1);
 378
 379 nwritten = writev(STDOUT_FILENO, iov, 2);
 380 .fi
 381 .in
 382 .\"O .SH "SEE ALSO"
 383 .SH 関連項目
 384 .BR read (2),
 385 .BR write (2)