kevent(2) FreeBSD 一般コマンドマニュアル

kevent

前のページ 上に戻る 次のページ

kevent




書式

     #include <sys/types.h>
     #include <sys/event.h>
     #include <sys/time.h>

     int
     kqueue(void);

     int
     kevent(int kq, const struct kevent *changelist, int nchanges,
             struct kevent *eventlist, int nevents,
             const struct timespec *timeout);

     EV_SET(&kev, ident, filter, flags, fflags, data, udata);


解説

     kqueue() は、フィルタと呼ばれる小さなカーネルコードの実行結果に基づき、イ
     ベントの発生やある状態の成立をユーザに通知する一般的な方法を提供します。
     kevent は (ident, filter) のペアによって識別されます。ここで、ident は識
     別子、filter はフィルタを表します。 1 つの kqueue には、同じ kevent が複
     数存在することはできません。

     フィルタは、kevent の初期登録時に以前から存在した状態を検出するために実行
     されます。また、あるイベントが評価のためにフィルタに渡されるたびに実行さ
     れます。状態を報告すべきとフィルタが決定した場合には、その kevent はユー
     ザが回収できるように kqueue に置かれます。

     ユーザが kqueue から kevent を回収しようとしたときにも、フィルタが実行さ
     れます。フィルタの実行により、そのイベントをトリガした状態が成立していな
     いことが示された場合には、その kevent は kqueue から削除され、ユーザに渡
     されません。

     フィルタをトリガするイベントが複数ある場合でも、 kqueue の中に kevent が
     複数置かれるわけではありません。代わりに、フィルタは複数のイベントを単一
     の kevent 構造体へ集めます。ファイル記述子に対する close() の呼び出しは、
     その記述子を参照しているあらゆる kevent を削除します。

     kqueue() は新規のカーネルイベントキューを生成して記述子を返します。キュー
     は fork(2) で生成された子プロセスには継承されません。しかしながら、 RFFDG
     フラグなしで rfork(2) が呼び出された場合には、記述子テーブルが共有され、2
     つのプロセス間で kqueue の共有が可能になります。

     kevent() は、キューにイベントを登録し、保留中のあらゆるイベントをユーザに
     返すために使用されます。 changelistkevent 構造体の配列へのポインタで
     す。この構造体は <sys/event.h> で定義されています。保留中のイベントをキュ
     ーから読み込む前に、 changelist に含まれている全ての変更を適用します。
     nchangeschangelist の大きさを与えます。 eventlist は kevent 構造体の
     配列へのポインタです。 neventseventlist の大きさを決定します。
     timeout が NULL でないポインタの場合には、timespec 構造体であると解釈され
     て、イベントを待つ最大待ち時間を指定します。 timeout が NULL ポインタの場
     合には、 kevent() は無期限に待ちます。ポーリングの効果を得るためには、
     };

     struct kevent のフィールドは以下の通りです。

     ident      このイベントを識別するために使用される値です。厳密な解釈は結び
                付けられたフィルタにより決定されますが、普通はファイル記述子と
                して解釈されます。

     filter     このイベントを処理するために使用されるカーネルフィルタを識別し
                ます。あらかじめ定義されたシステムフィルタは後述してあります。

     flags      イベント発生時に実行するべきアクションです。

     fflags     フィルタ固有のフラグです。

     data       フィルタ固有のデータの値です。

     udata      変更されずにカーネルを通して渡される不透明なユーザー定義の値で
                す。

     flags フィールドは以下の値を含むことができます。

     EV_ADD         イベントを kqueue に追加します。既存のイベントを再び追加す
                    ると、元のイベントのパラメータが変更されます。重複するエン
                    トリができるわけではありません。イベントを追加する
                    と、EV_DISABLE フラグによって上書きされない限りは自動的に
                    有効にされます。

     EV_ENABLE      イベントがトリガされた場合に、 kevent() がそのイベントを返
                    すことを許可します。

     EV_DISABLE     イベントを無効にします。これにより kevent() はそのイベント
                    を返さなくなります。フィルタ自身は無効にされません。

     EV_DELETE      kqueue からイベントを削除します。ファイル記述子に結び付け
                    られているイベントは、その記述子の最後のクローズ時に自動的
                    に削除されます。

     EV_ONESHOT     フィルタが最初トリガされたときにのみ、イベントが返るように
                    します。ユーザがイベントを kqueue から回収した後で、そのイ
                    ベントは削除されます。

     EV_CLEAR       ユーザがイベントを回収した後に、その状態をリセットします。
                    これは現在の状態ではなく、状態の変化を報告するフィルタに有
                    用です。幾つかのフィルタは内部でこのフラグを自動的にセット
                    しているかもしれないことに注意してください。

     EV_EOF         そのフィルタ固有の EOF 状態であることをを示すために、フィ
                    ルタがこのフラグをセットすることがあります。

     EV_ERROR       後述の 戻り値を参照してください。

                        に戻ります。フィルタを追加するときに、 fflags に
                        NOTE_LOWAT を設定し data に新しい最低基準値を指定する
                        ことにより、この値を、フィルタごとの最低基準値で上書き
                        することが可能です。戻るときには、 data にはソケット
                        バッファの中のバイト数が入っています。

                        ソケットの読み込み側が切断された場合には、フィルタは
                        flags に EV_EOF も設定します。ここでエラーが起きた場合
                        には、 fflags にソケットエラーを返します。ソケットバッ
                        ファの中に保留中のデータが残っていても、 (接続が切れた
                        ことを示す) EOF が返されることがあります。

                    v ノード
                        ファイルポインタがファイルの最後 (EOF) でないときに戻
                        ります。 data は現在位置からファイルの最後 (EOF) まで
                        のオフセットが入っています。この値は負であるかもしれま
                        せん。

                    FIFO とパイプ
                        読み込むべきデータがあるときに戻ります。 data には有効
                        なバイト数が入っています。

                        最後の書き込み側が切断したときに、フィルタは flags に
                        EV_EOF をセットします。 EV_CLEAR を渡すことで、このフ
                        ラグをクリアすることができ、フィルタはデータが読み込め
                        るようになるのを戻らずに再び待ちます。

     EVFILT_WRITE   識別子に記述子を引数として取ります。その記述子が書き込み可
                    能になるたびに戻ります。ソケット、パイプおよび FIFO では、
                    data には書き込みバッファの残り領域の大きさが入っていま
                    す。読み込み側が切断したときに、フィルタは EV_EOF をセット
                    します。 FIFO の場合、EV_CLEAR を使いこれをクリアすること
                    ができます。このフィルタは vnode をサポートしていないこと
                    に注意してください。

                    ソケットの場合、最低基準値およびソケットエラーの取り扱いは
                    EVFULT_READ の場合と同じです。

     EVFILT_AIO     非同期入出力リクエストの sigevent 部分の、
                    sigev_notify_kqueue にはイベントを付加する kqueue の記述子
                    を入れ、 sigev_value には udata の値を入れ、 sigev_notify
                    には SIGEV_EVENT を入れて、非同期入出力リクエストを埋めま
                    す。 aio_* 関数が呼び出されたとき、そのイベントは指定され
                    た kqueue に登録されます。aio_* 関数が返した aiocb 構造体
                    を ident 引数にセットします。このフィルタは aio_error と同
                    様の条件で戻ります。

                    別の方法として、 ident に kqueue 記述子を入れて kevent 構
                    造体を初期化し、そのアドレスを非同期リクエストの
                    aio_lio_opcode フィールドに置くことも可能です。しかしなが
                    ら、このアプローチは 64 ビットポインタのアーキテクチャでは
                    動作しないでしょうし、あてにするべきではありません。

                    NOTE_ATTRIB    記述子が参照するファイルの属性が変更されま
                                   した。

                    NOTE_LINK      ファイルのリンク数が変更されました。

                    NOTE_RENAME    記述子が参照するファイルがリネームされまし
                                   た。

                    NOTE_REVOKE    ファイルへのアクセスが revoke(2) によって無
                                   効にされたか、もしくは、下位層のファイルシ
                                   ステムがマウントされていません。

                    戻るときに、 fflags にフィルタをトリガしたイベントが入って
                    います。

     EVFILT_PROC    監視するプロセス ID を識別子に、監視するイベントを fflags
                    に引数として取ります。要求されたイベントを 1 つ以上プロセ
                    スが実行するときに戻ります。あるプロセスが他のプロセスを正
                    常に見ることができる場合には、イベントをそのプロセスに結び
                    付けることができます。監視するイベントを次に示します。

                    NOTE_EXIT        プロセスが終了しました。

                    NOTE_FORK        プロセスが fork() を呼びました。

                    NOTE_EXEC        プロセスが execve(2) または類似の呼び出し
                                     により、新規のプロセスを実行しました。

                    NOTE_TRACK       fork() の呼び出しを越えて、プロセスを追跡
                                     します。親プロセスは fflags フィールドに
                                     NOTE_TRACK をセットして戻り、一方、子プロ
                                     セスは fflags に NOTE_CHILD を data に親
                                     プロセスの PID をセットし戻ります。

                    NOTE_TRACKERR    このフラグは、システムが子プロセスへのイ
                                     ベントを結び付けることができなかったとき
                                     に戻ります。通常、これは資源の制限により
                                     生じます。

                    戻るときに、 fflags はフィルタをトリガしたイベントが入って
                    います。

     EVFILT_SIGNAL  監視するシグナル番号を識別子に引数として取ります。与えられ
                    たシグナルがプロセスに配送されたときに戻ります。これは
                    signal() および sigaction() の仕組みと共存し、低い優先順位
                    を持っています。たとえそのシグナルが SIG_IGN とマークされ
                    ていたとしても、フィルタはプロセスに配送されようとしたシグ
                    ナル全てを記録します。通常のシグナル配送処理の後に、イベン
                    ト通知が発生します。 data には kevent() を最後に呼び出して
                    からのシグナル発生の回数が返ります。このフィルタは内部で自
                    動的に EV_CLEAR フラグをセットします。

     kqueue() 関数は以下の場合に失敗します。

     [ENOMEM]           カーネルがカーネルキューのための十分なメモリの割り当て
                        に失敗しました。

     [EMFILE]           プロセスの記述子テーブルが満杯です。

     [ENFILE]           システムファイルテーブルが満杯です。

     kevent() 関数は以下の場合に失敗します。

     [EACCES]           プロセスがフィルタを登録する権限を持っていません。

     [EFAULT]           kevent 構造体の読み込みまたは書き込みでエラーがありま
                        した。

     [EBADF]            指定された記述子が有効ではありません。

     [EINTR]            時間切れ前や、戻るための何らかのイベントが kqueue に置
                        かれる前に、シグナルが配送されました。

     [EINVAL]           指定されたタイムリミットまたはフィルタが無効です。

     [ENOENT]           修正または削除されるべきイベントが見つかりません。

     [ENOMEM]           イベント登録のためのメモリがありません。

     [ESRCH]            結び付けるために指定したプロセスが存在しません。


関連項目

     aio_error(2), aio_read(2), aio_return(2), poll(2), read(2), select(2),
     sigaction(2), write(2), signal(3)


歴史

     kqueue() および kevent() 関数は FreeBSD 4.1 で初めて登場しました。


作者

     kqueue() システムと、このマニュアルページは Jonathan Lemon
     <jlemon@FreeBSD.org> が書きました。


バグ

     現在は、UFS ファイルシステムに属さない vnode(9) を監視することができませ
     ん。

FreeBSD 4.4                     April 14, 2000                     FreeBSD 4.4

ABELNET VPSサービス