.\" Copyright (c) 1998 Terry Lambert
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" %FreeBSD: src/lib/libc/sys/aio_read.2,v 1.6.2.3 2001/07/22 12:06:49 dd Exp %
.\"
.\" $FreeBSD: doc/ja_JP.eucJP/man/man2/aio_read.2,v 1.5 2001/05/14 01:08:20 horikawa Exp $
.Dd November 17, 1998
.Dt AIO_READ 2
.Os
.Sh 名称
.Nm aio_read
.Nd ファイルからの非同期読取り (REALTIME)
.Sh ライブラリ
.Lb libc
.Sh 書式
.Fd #include <time.h>
.Fd #include <aio.h>
.Ft int
.Fn aio_read "struct aiocb *iocb"
.Sh 解説
.Fn aio_read
関数は、呼び出しプロセスに
記述子
.Fa iocb->aio_fildes
のオフセット
.Fa iocb->aio_offset
で始まる
.Fa iocb->aio_nbytes
を、
.Fa iocb->aio_buf
が指すバッファに
読取れるようにします。
呼び出しは、読取り要求が記述子に待ち行列として入れられ
るとただちに戻ります。
呼び出しが戻った時点で読取りは完了していることもありますし、
完了していないこともあります。
.Pp
_POSIX_PRIORITIZED_IO が定義されており、
しかも記述子がこれをサポートしている場合に
待ち行列に入れられている操作は、呼び出しプロセスの優先順位から
.Fa iocb->aio_reqprio
を減じたものに等しい優先順位でサブミットされます。
.Pp
.Fa iocb->aio_lio_opcode
は
.Fn aio_read
呼び出しによって無視されます。
.Pp
.Fa iocb
ポインタは、進行中に待ち行列に入れられた戻りステータスまたは
エラーステータスを判定するために、
.Fn aio_return
と
.Fn aio_error
の引数として後に使用される可能性があります。
.Pp
要求が待ち行列に入れられない場合 (一般には無効な引数のために)、
呼び出しは要求を待ち行列に入れずに戻ります。
.Pp
要求が正常に待ち行列に入れられると、コンテキストとして要求の間に
.Fa iocb->aio_offset
の値が修正される可能性があるので、
この値は要求が待ち行列に入れられた後は参照してはなりません。
.Sh 制限
.Fa iocb
が指す非同期入出力制御ブロック構造体、およびその構造体の
.Fa iocb->aio_buf
メンバが参照するバッファは、操作が完了するまで有効である必要があります。
このため、これらのオブジェクトについての自動 (スタック) 変数の
使用は推奨されません。
.Pp
カーネルへの正しくないコンテキスト情報の引き渡しを回避するために、
非同期入出力制御バッファ
.Fa iocb
は
.Fn aio_read
呼び出しの前にゼロにする必要があります。
.Pp
要求が待ち行列に入れられた後、要求が完了するまでは
非同期入出力制御ブロック構造体またはバッファ内容の修正は許されていません。
.Pp
.Fa iocb->aio_offset
内のファイルオフセットが、
.Fa iocb->aio_fildes
の最大オフセットを越えている場合は入出力は行われません。
.Sh 戻り値
.\".Rv -std aio_read
.Fn aio_read
関数は、成功すると値 0 を返します。それ以外の場合は値 -1 が
返され、エラーを示すグローバル変数
.Fa errno
が設定されます。
.Sh 診断
なし。
.Sh エラー
.Fn aio_read
は次の場合に失敗します。
.Bl -tag -width Er
.It Bq Er EAGAIN
システムリソースの限界のために要求は待ち行列に入れられませんでした。
.It Bq Er ENOSYS
.Fn aio_read
呼び出しがサポートされていません。
.El
.Pp
以降の条件は、
.Fn aio_read
呼び出しが行なわれたときに同期的に検出されることもありますし、
その後いつでも非同期的に検出されることもあります。
これらが呼び出し時に検出された場合、
.Fn aio_read
は -1 を返し、
.Va errno
を適切に設定します。
そうでない場合は、
.Fn aio_return
関数を呼び出し、-1 を返し、
.Va errno
に返されている実際の値を判定するために
.Fn aio_error
を呼び出す必要があります。
.Pp
.Bl -tag -width Er
.It Bq Er EBADF
.Ar iocb->aio_fildes
が無効です。
.It Bq Er EINVAL
オフセット
.Fa iocb->aio_offset
が有効でないか、
.Fa iocb->aio_reqprio
によって指定される優先順位が
有効な優先順位でないか、または
.Fa iocb->aio_nbytes
によって指定されるバイト数が有効でありません。
.It Bq Er EOVERFLOW
ファイルは正規のファイルであり、
.Fa iocb->aio_nbytes
はゼロより大きくて
.Fa iocb->aio_offset
内の開始オフセットはファイルの末尾の前にあるものの、
.Fa iocb->aio_fildes
オフセット最大にあるかまたはそれを越えています。
.El
.Pp
要求が正常に待ち行列に入れられたものの、
後でキャンセルされるかエラーが発生した場合、
.Fn aio_return
関数によって返された値が
.Xr read 2
呼び出しごとによるものであり、
.Fn aio_error
関数によって返される値が
.Xr read 2
呼び出しから返されたエラーの 1 つであるか、または次の 1 つです。
.Bl -tag -width Er
.It Bq Er EBADF
.Fa iocb->aio_fildes
が読取りについては無効です。
.It Bq Er ECANCELED
要求は
.Fn aio_cancel
の呼び出しによって明示的にキャンセルされました。
.It Bq Er EINVAL
オフセット
.Fa iocb->aio_offset
は無効です。
.El
.Sh 規格
.Fn aio_read
呼び出しは
.St -p1003.2
に準拠しています。
.Sh 歴史
.Nm
は
.Fx 3.0
ではじめて登場しました。
.Sh 作者
このマニュアルページは
.An Terry Lambert Aq terry@whistle.com
が作成しました。
.Sh バグ
.Fa iocb->aio_offset
の値は無視されます。
.Fa iocb->_aiocb_private
内の無効な情報はカーネルを混乱させる可能性があります。
