AIO_WRITE(2)

名称
aio_write - ファイルへの非同期書込み (REALTIME)

ライブラリ
libc

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

解説
aio_write() 関数によって、呼び出し元プロセスは iocb->aio_buf が指すバッファから記述子 iocb->aio_fildes に iocb->aio_nbytes を書き込めます。書込み要求が記述子への待ち行列に入れられてしまうと ただちに呼び出しは戻ります。 呼び出しが戻った時点で書込みは完了している可能性も完了していない 可能性もあります。無効な引数のためなどにより 要求を待ち行列に入れられない場合は、 呼び出しは要求を待ち行列に入れずに戻ります。

iocb->aio_fildes 用に O_APPEND が設定されている場合、 aio_write() 操作は呼び出しが行なわれたのと同じ順序で ファイルの末尾に追加されます。 O_APPEND がファイル記述子用に設定されていない場合、書込み操作はファイルの先頭に iocb->aio_offset を加えた絶対位置で行われます。

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

iocb ポインタは待ち行列に入れられた操作の戻り値、またはエラー状態を 判定するために、 aio_return() および aio_error() への引数として使用できます。

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

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

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

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

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

戻り値

エラー
aio_write() 関数は次の場合に処理を失敗します:

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

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

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

[EBADF]
    iocb->aio_fildes が無効であるか、書込みには開かれていません。

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

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

[EBADF]
    iocb->aio_fildes は書込みについては無効です。

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

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

規格
aio_write() は p1003.2 標準に準拠しています。

歴史
aio_write 関数は FreeBSD 3.0 ではじめて登場しました。

作者
このマニュアルページは Wes Peters <wes@softweyr.com> が作成しました。

バグ
非同期入出力操作はこのバージョンではキャンセルできません。 iocb->_aiocb_private 内の誤った情報はカーネルを混乱させる可能性があります。