release/man3/lio_listio.3

   1 .\" Copyright (C) 2010, Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\"
   3 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
   4 .\" This is free documentation; you can redistribute it and/or
   5 .\" modify it under the terms of the GNU General Public License as
   6 .\" published by the Free Software Foundation; either version 2 of
   7 .\" the License, or (at your option) any later version.
   8 .\"
   9 .\" The GNU General Public License's references to "object code"
  10 .\" and "executables" are to be interpreted as the output of any
  11 .\" document formatting or typesetting system, including
  12 .\" intermediate and printed output.
  13 .\"
  14 .\" This manual is distributed in the hope that it will be useful,
  15 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  16 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17 .\" GNU General Public License for more details.
  18 .\"
  19 .\" You should have received a copy of the GNU General Public
  20 .\" License along with this manual; if not, see
  21 .\" <http://www.gnu.org/licenses/>.
  22 .\" %%%LICENSE_END
  23 .\"
  24 .\"*******************************************************************
  25 .\"
  26 .\" This file was generated with po4a. Translate the source file.
  27 .\"
  28 .\"*******************************************************************
  29 .\"
  30 .\" Japanese Version Copyright (c) 2012  Akihiro MOTOKI
  31 .\"         all rights reserved.
  32 .\" Translated 2012-05-05, Akihiro MOTOKI <amotoki@gmail.com>
  33 .\" Updated 2012-05-29, Akihiro MOTOKI <amotoki@gmail.com>
  34 .\"
  35 .TH LIO_LISTIO 3 2012\-05\-08 "" "Linux Programmer's Manual"
  36 .SH 名前
  37 lio_listio \- リストの I/O リクエストを開始する
  38 .SH 書式
  39 .nf
  40 \fB#include <aio.h>\fP
  41
  42 \fBint lio_listio(int \fP\fImode\fP\fB, struct aiocb *const \fP\fIaiocb_list\fP\fB[],\fP
  43 \fB               int \fP\fInitems\fP\fB, struct sigevent *\fP\fIsevp\fP\fB);\fP
  44
  45 \fI\-lrt\fP でリンクする。
  46 .fi
  47 .SH 説明
  48 \fBlio_listio\fP() 関数は、配列 \fIaiocb_list\fP で指定された I/O 操作の
  49 リストをそれぞれ開始する。
  50
  51 \fImode\fP 引き数には以下のいずれかの値を指定する。
  52 .TP  12
  53 \fBLIO_WAIT\fP
  54 全ての操作が完了するまで、呼び出しは停止 (block) する。
  55 \fIsevp\fP 引き数は無視される。
  56 .TP
  57 \fBLIO_NOWAIT\fP
  58 I/O 操作は処理を行うためのキューに入れられ、呼び出しは直ちに返る。
  59 全ての I/O 操作が完了すると、 \fIsevp\fP 引き数で指定した非同期通知が
  60 行われる。詳細は \fBsigevent\fP(7) を参照。\fIsevp\fP が NULL の場合、
  61 非同期通知は行われない。
  62 .PP
  63 \fIaiocb_list\fP 引き数は、I/O 操作を指定する \fIaiocb\fP 構造体へのポインタ
  64 の配列である。指定された操作の実行順序は規定されていない。
  65 \fInitems\fP 引き数は、配列 \fIaiocb_list\fP の大きさを指定する。
  66 \fIaiocb_list\fP 内のヌルポインタは無視される。
  67
  68 \fIaiocb_list\fP の各制御ブロックでは、
  69 \fIaio_lio_opcode\fP フィールドで開始する I/O 操作を指定する。
  70 \fIaio_lio_opcode\fP には以下の値が指定できる。
  71 .TP  10
  72 \fBLIO_READ\fP
  73 読み出し操作を開始する。操作はキューに入れられ、
  74 この制御ブロックを指定して \fBaio_read\fP(3) の呼び出しが行われる。
  75 .TP
  76 \fBLIO_WRITE\fP
  77 書き込み操作を開始する。操作はキューに入れられ、
  78 この制御ブロックを指定して \fBaio_write\fP(3) の呼び出しが行われる。
  79 .TP
  80 \fBLIO_NOP\fP
  81 この制御ブロックを無視する。
  82 .PP
  83 各制御ブロックの残りのフィールドは、
  84 \fBaio_read\fP(3) や \fBaio_write\fP(3) の場合と同じ意味を持つ。
  85 各制御ブロックの \fIaio_sigevent\fP フィールドは、
  86 個々の I/O 操作で通知方法を指定するのに使用される
  87 (\fBsigevent\fP(7) 参照)。
  88 .SH 返り値
  89 \fImode\fP が \fBLIO_NOWAIT\fP の場合、 \fBlio_listio\fP() は全ての操作が
  90 正常にキューに入れられた場合に 0 を返す。
  91 そうでない場合は、\-1 が返り、 \fIerrno\fP にエラーを示す値が設定される。
  92
  93 \fImode\fP が \fBLIO_WAIT\fP の場合、 \fBlio_listio\fP() は全ての操作が
  94 正常に完了した場合に 0 を返す。
  95 そうでない場合は、\-1 が返り、 \fIerrno\fP にエラーを示す値が設定される。
  96
  97 \fBlio_listio\fP() の返り値から得られる情報は、関数呼び出し自体に関する
  98 ものだけであり、個々の I/O 操作に関する情報は得られない。
  99 個々の I/O 操作は失敗することがあるが、これにより他の I/O 操作が完了
 100 しなくなるといったことはない。 \fBaio_error\fP(3) を使うと、
 101 \fIaiocb_list\fP の個々の I/O 操作のステータスを知ることができる。
 102 ある I/O 操作が完了すると、その終了ステータスは\fBaio_return\fP(3) を使う
 103 ことで取得できる。個々の I/O 操作は \fBaio_read\fP(3) や \fBaio_write\fP(3)
 104 に書かれている理由で失敗する場合がある。
 105 .SH エラー
 106 \fBlio_listio\fP() 関数は以下の理由で失敗する。
 107 .TP
 108 \fBEAGAIN\fP
 109 リソースが足りない。
 110 .TP
 111 \fBEAGAIN\fP
 112 .\" Doesn't happen in glibc(?)
 113 \fInitems\fP で指定された数の I/O 操作を行うと、
 114 非同期 I/O 操作の数が上限 \fBAIO_MAX\fP を超えてしまう状況であった。
 115 .TP
 116 \fBEINVAL\fP
 117 .\" Doesn't happen in glibc(?)
 118 \fImode\fP が不正であるか、
 119 \fInitems\fP が上限 \fBAIO_LISTIO_MAX\fP を超えている。
 120 .TP
 121 \fBEINTR\fP
 122 \fImode\fP が \fBLIO_WAIT\fP で、全ての I/O 操作が完了する前にシグナルが
 123 捕捉された (非同期 I/O の完了通知に使用されるシグナルの場合もこれに
 124 該当する)。
 125 .TP
 126 \fBEIO\fP
 127 .\" e.g., ioa_reqprio or aio_lio_opcode was invalid
 128 \fIaiocb_list\fP で指定された操作の中に失敗したものがあった。
 129 アプリケーションは、 \fBaio_return\fP(3) を使用して、
 130 個々の操作のステータスを確認することができる。
 131 .PP
 132 \fBlio_listio\fP がエラー \fBEAGAIN\fP, \fBEINTR\fP, \fBEIO\fP で失敗した場合、
 133 \fIaiocb_list\fP で指定した操作のいくつかは開始されていることがある。
 134 \fBlio_listio\fP が他の理由で失敗した場合には、
 135 どの I/O 操作も開始されていない。
 136 .SH バージョン
 137 The \fBlio_listio\fP() 関数は glibc 2.1 以降で利用できる。
 138 .SH 準拠
 139 POSIX.1\-2001, POSIX.1\-2008.
 140 .SH 注意
 141 .\" or the control block of the operation
 142 使用前に制御ブロックを 0 で埋めるのは良い考えである。
 143 I/O 操作の実行中は制御ブロックを変更してはならない。データの読み書き先
 144 のバッファ領域に I/O 操作の実行中にアクセスしてはならない。さもないと、
 145 どのような結果になるか分からない。また、関係するメモリ領域も有効な状態
 146 のままにしておかなければならない。
 147
 148 同じ \fIaiocb\fP 構造体を指定して同時に複数の I/O 操作を行った場合、
 149 どのような結果になるかは不定である。
 150 .SH 関連項目
 151 \fBaio_cancel\fP(3), \fBaio_error\fP(3), \fBaio_fsync\fP(3), \fBaio_return\fP(3),
 152 \fBaio_suspend\fP(3), \fBaio_write\fP(3), \fBaio\fP(7)
 153 .SH この文書について
 154 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.65 の一部
 155 である。プロジェクトの説明とバグ報告に関する情報は
 156 http://www.kernel.org/doc/man\-pages/ に書かれている。