名称

kqueue, kevent — カーネルイベント通知メカニズム

ライブラリ

Standard C Library (libc, -lc)

書式

#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) のペアによって識別されます。単に kqueue ごとに 1 つのユニークな kevent があります。

フィルタは、既存の条件が存在していることを検知するために kevent の初期登録に実行され、また、イベントが評価のためのフィルタに渡されるときはいつでも実行されます。条件が報告されるべきであることをフィルタが決定するなら、 kevent は、検索するユーザのために kqueue に置かれます。

また、フィルタは、ユーザが kqueue から kevent を検索することを試みるときも実行されます。イベントをトリガした条件がもはや保持されないことをフィルタが示すなら、 kevent は、kqueue から削除され、返されません。

フィルタをトリガする複数のイベントは、複数の kevent が kqueue に置かれているような結果となりません。代わりに、フィルタは、単一の struct kevent にイベントを集めます。ファイル記述子で close() を呼び出すことは、記述子を参照しているあらゆる kevent を削除します。

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

kevent() システムコールは、キューでイベントを登録し、ユーザにあらゆる保留中 (pending) のイベントを返すために使用されます。 changelist 引数は、 < sys/event.h> で定義されているように、 kevent 構造体の配列へのポインタです。 changelist に含まれているすべての変更は、あらゆる保留中のイベントがキューから読み込まれる前に、適用されます。 nchanges 引数は、 changelist のサイズを与えます。 eventlist 引数は、kevent 構造体の配列へのポインタです。 nevents 引数は、 eventlist のサイズを決定します。 nevents が 0 であるとき、 kevent() は、 select(2) と違って、たとえ指定された timeout があっても、直ちに返ります。 timeout が NULL ポインタでないなら、struct 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 のフィールドは、次の通りです:

flags フィールドは、次の値を含むことができます:

あらかじめ定義されたシステムフィルタは、以下にリストされます。引数は、kevent 構造体の fflags と data フィールドを通してフィルタをやりとりして渡されます。

EVFILT_READ

識別子として記述子を取り、読み込むことができるデータがあるときはいつでも返ります。フィルタの振る舞いは、記述子タイプによって少し異なります。

EVFILT_WRITE

識別子として記述子を取り、記述子に書き込むことが可能なときはいつでも返ります。ソケット、パイプと FIFO について、 data は、書き込みバッファの残りの空間の合計を含んでいます。フィルタは、読み込み側が切断するとき、EV_EOF を設定し、 FIFO の場合に、これは、EV_CLEAR の使用によってクリアされます。このフィルタは、vnode または BPF デバイスをサポートしていないことに注意してください。

ソケットについて、最低点 (low water mark) とソケットエラーの扱いは、 EVFILT_READ の場合と同じです。

EVFILT_AIO

AIO 要求の sigevent 部分は、イベントがアタッチされるべきである kqueue の記述子を含んでいる sigev_notify_kqueue、 EV_ONESHOT、EV_CLEAR または EV_DISPATCH であるべきである kevent フラグを含んでいる sigev_notify_kevent_flags、 udata 値を含んでいる sigev_value と SIGEV_KEVENT に設定される sigev_notify で書き込まれます。 aio_*() システムコールが行われるとき、イベントは、指定された kqueue に登録され、 ident 引数は、 aio_*() システムコールによって返された struct aiocb に設定されます。フィルタは、aio_error と同じ条件で返ります。

EVFILT_VNODE

識別子としてのファイル記述子と fflags を監視するイベントを取り、1 つ以上の要求されたイベントが記述子で生じるとき、返ります。監視するイベントは、次の通りです:

返り時に、 fflags は、フィルタをトリガしたイベントを含んでいます。

EVFILT_PROC

識別子として監視するプロセス ID と fflags を監視するイベントを取り、プロセスが 1 つ以上の要求されたイベントを実行するとき、返ります。プロセスが通常、別のプロセスを見ることができるなら、それにイベントをアタッチすることができます。監視するイベントは、次の通りです:

返り時に、 fflags は、フィルタをトリガしたイベントを含んでいます。

EVFILT_SIGNAL

識別子として監視するシグナル番号を取り、与えられたシグナルがプロセスに配信されるとき、返ります。これは、 signal() と sigaction() 機能と共存し、より低い優先順位があります。無視されるなら、フィルタによって記録されない、 SIGCHLD シグナルを除いて、たとえシグナルが SIG_IGN とマークされていたとしても、フィルタは、プロセスにシグナルを配信するすべての試みを記録します。イベント通知は、通常のシグナル配信処理の後に起こります。 data は、 kevent() への最後の呼び出し以後、シグナルが生じた回数を返します。このフィルタは、内部で EV_CLEAR フラグを自動的に設定します。

EVFILT_TIMER

ident によって識別される任意のタイマを確立します。タイマを追加するとき、 data は、ミリ秒単位でタイムアウト期間を指定します。タイマは、EV_ONESHOT が指定されなければ、周期的です。返り時に、 data は、 kevent() への最後の呼び出し以後、タイムアウトが満了した回数を含んでいます。このフィルタは、内部で EV_CLEAR フラグを自動的に設定します。 kern.kq_calloutmax sysctl によって制御されるタイマの数に関してシステム全体の制限があります。

返り時に、 fflags は、フィルタをトリガしたイベントを含んでいます。

EVFILT_USER

あらゆるカーネルのメカニズムに関連していないが、ユーザレベルのコードによってトリガされる ident によって識別されるユーザイベントを確立します。 fflags の下位の 24 ビットは、ユーザ定義フラグのために使用され、次を使用して操作されます:

ユーザのイベントは、次で出力のためにトリガされます:

返り時に、 fflags は、下位 24 ビットにユーザ定義のフラグを含んでいます。

戻り値

kqueue() システムコールは、新しいカーネルのイベントキューを作成し、ファイル記述子を返します。カーネルのイベントキューの作成でエラーがあったなら、-1 の値が返され、 errno が設定されます。

kevent() システムコールは、 nevents によって与えられた値まで、 eventlist に置かれたイベントの数を返します。エラーが changelist の要素を処理する間に生じて、 eventlist に十分な空間があるなら、イベントは、 flags に EV_ERROR が設定され、 data にシステムエラーが設定された eventlist に置かれます。そうでなければ、 -1 が返され、 errno は、エラー状態を示す値に設定されます。時間の制限が満了するなら、 kevent() は、0 を返します。

エラー

kqueue() システムコールは、次の場合に失敗します:

kevent() システムコールは、次の場合に失敗します:

歴史

kqueue() と kevent() システムコールは、 FreeBSD 4.1 ではじめて登場しました。

作者

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

バグ

timeout 値は、24 時間に制限されています。より長いタイムアウトは、黙って 24 時間として解釈し直されます。

YOS OPENSONAR

名称

ライブラリ

書式

解説

戻り値

エラー

関連項目

歴史

作者

バグ