AIO_READ(2)

名称
aio_read - ファイルからの非同期読取り (REALTIME)

ライブラリ
libc

書式
<time.h> <aio.h> int aio_read(struct aiocb *iocb)

解説
aio_read() 関数は、呼び出しプロセスに 記述子 iocb->aio_fildes のオフセット iocb->aio_offset で始まる iocb->aio_nbytes を、 iocb->aio_buf が指すバッファに 読取れるようにします。 呼び出しは、読取り要求が記述子に待ち行列として入れられ るとただちに戻ります。 呼び出しが戻った時点で読取りは完了していることもありますし、 完了していないこともあります。

_POSIX_PRIORITIZED_IO が定義されており、 しかも記述子がこれをサポートしている場合に 待ち行列に入れられている操作は、呼び出しプロセスの優先順位から iocb->aio_reqprio を減じたものに等しい優先順位でサブミットされます。

iocb->aio_lio_opcode は aio_read() 呼び出しによって無視されます。

iocb ポインタは、進行中に待ち行列に入れられた戻りステータスまたは エラーステータスを判定するために、 aio_return() と aio_error() の引数として後に使用される可能性があります。

要求が待ち行列に入れられない場合 (一般には無効な引数のために)、 呼び出しは要求を待ち行列に入れずに戻ります。

要求が正常に待ち行列に入れられると、コンテキストとして要求の間に iocb->aio_offset の値が修正される可能性があるので、 この値は要求が待ち行列に入れられた後は参照してはなりません。

制限
iocb が指す非同期入出力制御ブロック構造体、およびその構造体の iocb->aio_buf メンバが参照するバッファは、操作が完了するまで有効である必要があります。 このため、これらのオブジェクトについての自動 (スタック) 変数の 使用は推奨されません。

カーネルへの正しくないコンテキスト情報の引き渡しを回避するために、 非同期入出力制御バッファ iocb は aio_read() 呼び出しの前にゼロにする必要があります。

要求が待ち行列に入れられた後、要求が完了するまでは 非同期入出力制御ブロック構造体またはバッファ内容の修正は許されていません。

iocb->aio_offset 内のファイルオフセットが、 iocb->aio_fildes の最大オフセットを越えている場合は入出力は行われません。

戻り値

診断
なし。

エラー
aio_read() は次の場合に失敗します。

[EAGAIN]
    システムリソースの限界のために要求は待ち行列に入れられませんでした。

[ENOSYS]
    aio_read() 呼び出しがサポートされていません。

以降の条件は、 aio_read() 呼び出しが行なわれたときに同期的に検出されることもありますし、 その後いつでも非同期的に検出されることもあります。 これらが呼び出し時に検出された場合、 aio_read() は -1 を返し、 errno を適切に設定します。 そうでない場合は、 aio_return() 関数を呼び出し、-1 を返し、 errno に返されている実際の値を判定するために aio_error() を呼び出す必要があります。

[EBADF]
    iocb->aio_fildes が無効です。

[EINVAL]
    オフセット iocb->aio_offset が有効でないか、 iocb->aio_reqprio によって指定される優先順位が 有効な優先順位でないか、または iocb->aio_nbytes によって指定されるバイト数が有効でありません。

[EOVERFLOW]
    ファイルは正規のファイルであり、 iocb->aio_nbytes はゼロより大きくて iocb->aio_offset 内の開始オフセットはファイルの末尾の前にあるものの、 iocb->aio_fildes オフセット最大にあるかまたはそれを越えています。

要求が正常に待ち行列に入れられたものの、 後でキャンセルされるかエラーが発生した場合、 aio_return() 関数によって返された値が read(2) 呼び出しごとによるものであり、 aio_error() 関数によって返される値が read(2) 呼び出しから返されたエラーの 1 つであるか、または次の 1 つです。

[EBADF]
    iocb->aio_fildes が読取りについては無効です。

[ECANCELED]
    要求は aio_cancel() の呼び出しによって明示的にキャンセルされました。

[EINVAL]
    オフセット iocb->aio_offset は無効です。

規格
aio_read() 呼び出しは p1003.2 に準拠しています。

歴史
aio_read は FreeBSD 3.0 ではじめて登場しました。

作者
このマニュアルページは Terry Lambert <terry@whistle.com> が作成しました。

バグ
iocb->aio_offset の値は無視されます。 iocb->_aiocb_private 内の無効な情報はカーネルを混乱させる可能性があります。