EVENTFD

名前

書式

int eventfd(unsigned int initval, int flags);  

説明

eventfd() は eventfd オブジェクトを参照するのに使用できる新しいファイルディスクリプターを返す。

以下の値のいくつかをビット単位の論理和 (OR) で指定することで、 eventfd() の振舞いを変更することができる。

EFD_CLOEXEC (Linux 2.6.27 以降)

新しいファイルディスクリプターに対して close-on-exec (FD_CLOEXEC) フラグをセットする。 このフラグが役に立つ理由については、 open(2) の O_CLOEXEC フラグの説明を参照のこと。

EFD_NONBLOCK (Linux 2.6.27 以降)

Set the O_NONBLOCK file status flag on the open file description (see open(2)) referred to by the new file descriptor. Using this flag saves extra calls to fcntl(2) to achieve the same result.

EFD_SEMAPHORE (Linux 2.6.30 以降)

新しいファイルディスクリプターからの読み出しにおいて、セマフォ風の動作を行う。 下記参照。

バージョン 2.6.26 以前の Linux では、 flags 引数は未使用であり、0 を指定しなければならない。

The following operations can be performed on the file descriptor returned by eventfd():

read(2)

read(2) は成功すると、8 バイトの整数を返す。 渡されたバッファーの大きさが 8 バイト未満の場合、 read(2) はエラー EINVAL で失敗する。

read(2) が返す値は、ホストバイトオーダ、つまり、そのホストマシンにおける整数の通常のバイトオーダである。

read(2) の動作は、 eventfd カウンターの現在の値が 0 以外であるかと、 eventfd ファイルディスクリプターを作成する際に EFD_SEMAPHORE フラグが指定されたか、により変化する。

*

EFD_SEMAPHORE が指定されておらず、eventfd カウンターが 0 以外の値の場合、 read(2) はカウンター値を格納した 8 バイトの値を返し、 カウンター値は 0 にリセットされる。

*

EFD_SEMAPHORE が指定されていて eventfd カウンターが 0 以外の値の場合、 read(2) は値 1 の 8 バイト値を返し、カウンター値は 1 減算される。

*

read(2) を呼び出した時点で eventfd カウンターが 0 の場合、 read(2) はカウンターが 0 以外になるまで停止 (block) する (0 以外になった時点で read(2) は上記で述べた通り実行を再開する)、 もしくはファイルディスクリプターが非停止 (nonblocking) に設定されている場合はエラー EAGAIN で失敗する。

write(2)

write(2) は、引数のバッファーで渡された 8 バイトの整数値をカウンターに加算する。 カウンターに格納可能な最大値は unsigned の 64 ビット整数の最大値から 1 を引いた値 (すなわち 0xfffffffffffffffe) である。 加算を行うとカウンター値が最大値を超過する場合には、 そのファイルディスクリプターに対して read(2) が実行されるまで、 write(2) は停止 (block) する、 もしくはファイルディスクリプターが非停止 (nonblocking) に設定されている場合はエラー EAGAIN で失敗する。

渡されたバッファーの大きさが 8 バイト未満の場合、もしくは 値 0xffffffffffffffff を書き込もうとした場合、 write(2) はエラー EINVAL で失敗する。

poll(2), select(2) (と同様の操作)

返されたファイルディスクリプターは、 poll(2) (epoll(7) も同じ) や select(2) をサポートしており、以下のような動作をする。

*

カウンターが 0 より大きい値の場合、 ファイルディスクリプターは読み出し可能となる (select(2) の readfds 引数や poll(2) の POLLIN フラグ)。

*

少なくとも値 "1" を、停止 (block) を伴わずに書き込める場合、 ファイルディスクリプターは書き込み可能となる (select(2) の writefds 引数や poll(2) の POLLOUT フラグ)。

*

カウンター値のオーバーフローが検出された場合、 select(2) はファイルディスクリプターは読み出し可能と書き込み可能の両方を通知し、 poll(2) は POLLERR イベントを返す。 上述の通り、 write(2) でカウンターがオーバーフローすることは決してない。 しかしながら、 KAIO サブシステムによって 2^64 回の eventfd "signal posts" が 実行された場合にはオーバーフローが起こり得る (理論的にはあり得るが、実用的にはあり得ない)。 オーバーフローが発生した場合、 read(2) は uint64_t の最大値 (すなわち 0xffffffffffffffff) を返す。

eventfd ファイルディスクリプターは、これ以外のファイルディスクリプター 多重 API である pselect(2) と ppoll(2) もサポートしている。

close(2)

ファイルディスクリプターがそれ以降は必要なくなった際には、クローズすべきである。 同じ eventfd オブジェクトに関連付けられたファイルディスクリプターが全て クローズされると、そのオブジェクト用の資源がカーネルにより解放される。

fork(2) で生成された子プロセスは、 eventfd() で生成されたファイルディスクリプターのコピーを継承する。 複製されたファイルディスクリプターは同じ eventfd オブジェクトに関連付けられる。 close-on-exec フラグが設定されていない場合、 execve(2) の前後で eventfd() で生成されたファイルディスクリプターは保持される。  

返り値

エラー

EINVAL

flags にサポートされていない値が指定された。

EMFILE

オープン済みのファイルディスクリプターの数がプロセスあたりの上限に 達していた。

ENFILE

オープン済みのファイル総数がシステム全体の上限に達していた。

ENODEV

(カーネル内の) 無名 inode デバイスをマウントできなかった。

ENOMEM

新しい eventfd ファイルディスクリプターを生成するのに十分なメモリーがなかった。

バージョン

属性

準拠

注意

カーネル内で使用すると、eventfd ファイルディスクリプターはカーネル空間からユーザー空間へのブリッジ機能を提供することができ、 例えば KAIO (kernel AIO) のような機能が、あるファイルディスクリプターに何らかの操作が完了したことを 通知することができる。

eventfd ファイルディスクリプターの重要な点は、 eventfd ファイルディスクリプターが select(2), poll(2), epoll(7) を使って他のファイルディスクリプターと全く同様に監視できる点である。 このことは、アプリケーションは「従来の (traditional)」 ファイルの状態変化と eventfd インターフェースをサポートする他のカーネル機構の状態変化を同時に監視 できることを意味する (eventfd() インターフェースがない時には、これらのカーネル機構は select(2), poll(2), epoll(7) 経由で多重することはできなかった)。

The current value of an eventfd counter can be viewed via the entry for the corresponding file descriptor in the process's /proc/[pid]/fdinfo directory. See proc(5) for further details.  

C ライブラリとカーネルの違い

glibc の追加機能

typedef uint64_t eventfd_t;

int eventfd_read(int fd, eventfd_t *value); int eventfd_write(int fd, eventfd_t value);

これらの関数は、eventfd ファイルディスクリプターに対する読み出しと 書き込みの操作を実行し、正しいバイト数が転送された場合には 0 を返し、そうでない場合は -1 を返す。  

例

以下に示すシェルセッションにこのプログラムの使い方を示す。

$ ./a.out 1 2 4 7 14 Child writing 1 to efd Child writing 2 to efd Child writing 4 to efd Child writing 7 to efd Child writing 14 to efd Child completed write loop Parent about to read Parent read 28 (0x1c) from efd  

プログラムのソース

#define handle_error(msg) \
    do { perror(msg); exit(EXIT_FAILURE); } while (0)

int main(int argc, char *argv[]) {
    int efd;
    uint64_t u;
    ssize_t s;

    if (argc < 2) {
        fprintf(stderr, "Usage: %s <num>...\n", argv[0]);
        exit(EXIT_FAILURE);
    }

    efd = eventfd(0, 0);
    if (efd == -1)
        handle_error("eventfd");

    switch (fork()) {
    case 0:
        for (int j = 1; j < argc; j++) {
            printf("Child writing %s to efd\n", argv[j]);
            u = strtoull(argv[j], NULL, 0);
                    /* strtoull() allows various bases */
            s = write(efd, &u, sizeof(uint64_t));
            if (s != sizeof(uint64_t))
                handle_error("write");
        }
        printf("Child completed write loop\n");

        exit(EXIT_SUCCESS);

    default:
        sleep(2);

        printf("Parent about to read\n");
        s = read(efd, &u, sizeof(uint64_t));
        if (s != sizeof(uint64_t))
            handle_error("read");
        printf("Parent read %"PRIu64" (%#"PRIx64") from efd\n", u, u);
        exit(EXIT_SUCCESS);

    case -1:
        handle_error("fork");
    } }  

関連項目

この文書について

Index

名前

書式

説明

返り値

エラー

バージョン

属性

準拠

注意

C ライブラリとカーネルの違い

glibc の追加機能

例

プログラムのソース

関連項目

この文書について