manページ  — KQUEUE

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

kevent() システムコールは、キューにイベントを登録し、保留中のあらゆるイベントを ユーザに返すために使用されます。 changelist 引数は kevent 構造体の配列へのポインタです。 この構造体は <sys/event.h> で定義されています。 保留中のイベントをキューから読み取る前に、 changelist に含まれている全ての変更を適用します。 nchanges 引数は changelist の大きさを与えます。 eventlist 引数は kevent 構造体の配列へのポインタです。 nevents 引数は eventlist の大きさを決定します。 nevents が 0 の時には、 select(2) とは違って、たとえ timeout がある場合でも kevent() はすぐに戻ります。 timeout が NULL でないポインタの場合には、timespec 構造体であると解釈されて、 イベントを待つ最大待ち時間を指定します。 timeout が NULL ポインタの場合には、 kevent() は無期限に待ちます。 ポーリングの効果を得るためには、 timeout 引数に、0 を示す timespec 構造体を指す非 NULL のポインタを与えるべきです。 changelist と eventlist 用に同じ配列を使うことができます。

EV_SET() マクロは kevent 構造体の初期化を簡単にするために用意されています。

kevent 構造体は次のように定義されています:

struct kevent {
        uintptr_t ident;        /* このイベントの識別子 */
        short     filter;       /* イベントのフィルタ */
        u_short   flags;        /* kqueue のアクションフラグ */
        u_int     fflags;       /* フィルタフラグ値 */
        intptr_t  data;         /* フィルタデータ値 */
        void      *udata;       /* 不透明なユーザデータ識別子 */
};

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	後述の 戻り値 を参照してください。

あらかじめ定義されたシステムフィルタを次に示します。 引数は kevent 構造体の fflags および data フィールドを経由してやりとりすることができます。

EVFILT_READ	識別子に記述子を引数として取ります。 読取り可能なデータがあるときに戻ります。 このフィルタの振舞いは、その記述子の型により少し異なります。

ソケット	事前に listen() に渡されたソケットの場合、保留中の次の接続があるときに戻ります。 data には listen のバックログ (backlog) の大きさが入っています。 その他のソケット記述子の場合、ソケットバッファの SO_RCVLOWAT の値を基準にして、読み取るデータがあるときに戻ります。 フィルタを追加するときに、 fflags に NOTE_LOWAT を設定し data に新しい最低基準値を指定することにより、 この値を、 フィルタごとの最低基準値で上書きすることが可能です。 戻るときには、 data には読取り可能なプロトコルデータのバイト数が入っています。 ソケットの読取り側が切断された場合には、フィルタは flags に EV_EOF も設定します。 ここでエラーが起きた場合には、 fflags にソケットエラーを返します。 ソケットバッファの中に保留中のデータが残っていても、 (接続が切れたことを示す) EOF が返されることがあります。
vnode	ファイルポインタがファイルの最後 (EOF) でないときに戻ります。 data は現在位置からファイルの最後 (EOF) までのオフセットが入っています。 この値は負であるかもしれません。
FIFO とパイプ
	読み取るべきデータがあるときに戻ります。 data には有効なバイト数が入っています。 最後の書込み側が切断したときに、フィルタは flags に EV_EOF をセットします。 EV_CLEAR を渡すことで、このフラグをクリアすることができ、 フィルタはデータが読み取るようになるのを戻らずに再び待ちます。
BPF デバイス
	BPF バッファが一杯になったとき、BPF タイムアウトが満了したとき、 または BPF の "直接モード" が有効で読み込むべきデータがあるときに、戻ります。 このときの data には利用可能なバイト数が入ります。

EVFILT_WRITE
	識別子に記述子を引数として取ります。 その記述子が書込み可能になるたびに戻ります。 ソケット、パイプおよび FIFO では、 data には書込みバッファの残り領域の大きさが入っています。 読取り側が切断したときに、フィルタは EV_EOF をセットします。 FIFO の場合、EV_CLEAR を使いこれをクリアすることができます。 このフィルタは vnode または BPF デバイスをサポートしていないことに 注意してください。 ソケットの場合、最低基準値およびソケットエラーの取り扱いは EVFULT_READ の場合と同じです。
EVFILT_AIO
	非同期入出力要求の sigevent 部分の、 sigev_notify_kqueue にはイベントを付加する kqueue の記述子を入れ、 sigev_value には udata の値を入れ、 sigev_notify には SIGEV_KEVENT を入れて、非同期入出力要求を埋めます。 aio_*() システムコールが呼び出されたとき、そのイベントは 指定された kqueue に登録されます。 aio_*() システムコールによって返された struct, aiocb を ident 引数にセットします。 このフィルタは aio_error と同様の条件で戻ります。 別の方法として、 ident に kqueue 記述子を入れて kevent 構造体を初期化し、 そのアドレスを非同期要求の aio_lio_opcode フィールドに置くことも可能です。 しかしながら、このアプローチは 64 ビットポインタのアーキテクチャでは 動作しないでしょうし、あてにするべきではありません。
EVFILT_VNODE
	ファイル記述子を識別子に、監視するイベントを fflags に引数として取ります。 指定した記述子に対し要求されたイベントが 1 つ以上発生したときに戻ります。 監視するイベントを以下に示します:

NOTE_DELETE	記述子が参照するファイルに対し unlink() システムコールが呼ばれました。
NOTE_WRITE	記述子が参照するファイルに対し書込みが起こりました。
NOTE_EXTEND	記述子が参照するファイルのサイズが拡張されました。
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 フラグをセットします。
EVFILT_TIMER	ident で識別される、任意のタイマを設定します。 タイマを追加する場合、 data はタイムアウトをミリ秒単位で指定します。 EV_ONESHOT を指定しない限り、タイマは周期的です。 data には、 kevent() を最後に呼び出してからのタイムアウトの回数が返ります。 このフィルタは内部で自動的に EV_CLEAR フラグをセットします。
EVFILT_NETDEV	識別子としてネットワークインタフェースの記述子を取り、 監視するイベントを fflags に取ります。 記述子上に要求されたイベントが 1 つ以上発生したとき、戻ります。 監視可能なイベントは次の通りです:
NOTE_LINKUP	リンクがアップ。
NOTE_LINKDOWN	リンクがダウン。
NOTE_LINKINV	リンク状態が無効。

戻るとき、フィルタをトリガしたイベントが fflags に格納されます。

EVFILT_NETDEV フィルタが現在実装されているのは、LINKUP と LINKDOWN の操作に miibus(4) [英語] ドライバを使用しているデバイスに対してのみです。 そのため、非イーサネットデバイスに対しては動作しません。

timeout の値は 24 時間に制限されています。 より長いタイムアウトは暗黙のうちに 24 時間として再解釈されます。