名前

       epoll_wait, epoll_pwait - epoll ファイルディスクリプターの I/O イベントを待つ

書式

       #include <sys/epoll.h>

       int epoll_wait(int epfd, struct epoll_event *events,
                      int maxevents, int timeout);
       int epoll_pwait(int epfd, struct epoll_event *events,
                      int maxevents, int timeout,
                      const sigset_t *sigmask);

説明

       The epoll_wait()  system call waits for events on the epoll(7) instance referred to by the
       file descriptor epfd.  The buffer pointed to by events is used to return information  from
       the  ready  list  about  file  descriptors  in  the  interest  list  that have some events
       available.  Up to maxevents are returned by epoll_wait().  The maxevents argument must  be
       greater than zero.

       The  timeout  argument specifies the number of milliseconds that epoll_wait()  will block.
       Time is measured against the CLOCK_MONOTONIC clock.

       A call to epoll_wait()  will block until either:

       • ファイルディスクリプターがイベントを配送した

       • 呼び出しがシグナルハンドラーにより割り込まれた

       • タイムアウトが満了する

       timeout 時間はシステムクロックの粒度に切り上げられ、カーネルのスケジューリング遅延により少
       しだけ長くなる可能性がある点に注意すること。  timeout を -1 に指定すると、 epoll_wait() は
       無限に停止する。 timeout を  0  に指定すると、  epoll_wait()  は利用可能なイベントがなくて
       も、すぐに返る。

       struct epoll_event は以下のように定義される。

           typedef union epoll_data {
               void    *ptr;
               int      fd;
               uint32_t u32;
               uint64_t u64;
           } epoll_data_t;

           struct epoll_event {
               uint32_t     events;    /* epoll イベント */
               epoll_data_t data;      /* ユーザーデータ変数 */
           };

       The  data  field  of  each  returned  epoll_event  structure contains the same data as was
       specified in the most recent call to epoll_ctl(2) (EPOLL_CTL_ADD, EPOLL_CTL_MOD)  for  the
       corresponding open file descriptor.

       The  events  field  is  a  bit  mask  that indicates the events that have occurred for the
       corresponding open file description.  See epoll_ctl(2) for a list of  the  bits  that  may
       appear in this mask.

   epoll_pwait()
       epoll_wait()   と  epoll_pwait()  の関係は、 select(2)  と pselect(2) の関係と同様である。
       pselect(2)  同様、 epoll_pwait()  を使うと、アプリケーションは、ファイルディスクリプターが
       準備できた状態になるか、 シグナルが捕捉されるまで、安全に待つことができる。

       以下の epoll_pwait()  の呼び出しは、

           ready = epoll_pwait(epfd, &events, maxevents, timeout, &sigmask);

       次の呼び出しを atomic に実行するのと等価である。

           sigset_t origmask;

           pthread_sigmask(SIG_SETMASK, &sigmask, &origmask);
           ready = epoll_wait(epfd, &events, maxevents, timeout);
           pthread_sigmask(SIG_SETMASK, &origmask, NULL);

       sigmask  引数には NULL を指定してもよい。 その場合には、 epoll_pwait()  は epoll_wait() と
       等価となる。

返り値

       成功した場合、 epoll_wait()  は要求された I/O に対して準備ができているファイルディスクリプ
       ターの数を返す。 また要求された timeout ミリ秒の間にファイルディスクリプターが準備できない
       場合は、0 を返す。 エラーが起こった場合、 epoll_wait() は -1 を返し、 errno を適切に設定す
       る。

エラー

       EBADF  epfd が有効なファイルディスクリプターでない。

       EFAULT events で指されるメモリー領域に書き込み権限でアクセスできない。

       EINTR  (1) 要求されたどのイベントも発生せず、かつ (2) timeout の期限が切れる前に、システム
              コールがシグナルハンドラーによって割り込まれた。 signal(7) 参照。

       EINVAL epfd が epoll ファイルディスクリプターでない。 または maxevents が 0 以下である。

バージョン

       epoll_wait() はカーネル 2.6  で追加された。  ライブラリによるサポートは  glibc  バージョン
       2.3.2 以降で提供されている。

       epoll_pwait()  はカーネル  2.6.19 で Linux に追加された。 ライブラリによるサポートは glibc
       バージョン 2.6 以降で提供されている。

準拠

       epoll_wait() は Linux 独自である。

注意

       あるスレッドが epoll_wait() を呼び出して停止されている間に、別のスレッドが wait 中の epoll
       インストールにファイルディスクリプターを追加することがある。新しいファイルディスクリプター
       でイベントが発生すると、 epoll_wait() の呼び出しによる停止が解除されることになる。

       If more than maxevents file descriptors  are  ready  when  epoll_wait()  is  called,  then
       successive epoll_wait()  calls will round robin through the set of ready file descriptors.
       This behavior helps avoid starvation scenarios, where  a  process  fails  to  notice  that
       additional file descriptors are ready because it focuses on a set of file descriptors that
       are already known to be ready.

       Note that it is possible to call epoll_wait()  on an epoll instance whose interest list is
       currently  empty (or whose interest list becomes empty because file descriptors are closed
       or removed from the interest in another thread).  The call  will  block  until  some  file
       descriptor  is  later  added  to  the  interest  list  (in  another  thread) and that file
       descriptor becomes ready.

バグ

       バージョン 2.6.37 より前のカーネルでは、おおよそ LONG_MAX / HZ ミリ秒より大きい timeout 値
       は  -1 (つまり無限大) として扱われる。したがって、例えば、sizeof(long) が 4 で、カーネルの
       HZ の値が 1000 のシステムでは、 35.79 分よりも大きなタイムアウトは無限大として扱われるとい
       うことである。

   C ライブラリとカーネルの違い
       素の  epoll_pwait()  システムコールは  6  番目の引数 size_t sigsetsize を取る。 この引数は
       sigmask 引数のバイト単位のサイズを指定する。 glibc の epoll_pwait() ラッパー関数は、この引
       数に固定値 (sizeof(sigset_t) と同じ) を指定する。

関連項目

       epoll_create(2), epoll_ctl(2), epoll(7)

この文書について

       この man ページは Linux man-pages プロジェクトのリリース 5.10 の一部である。プロジェクトの
       説明とバグ報告に関する情報は https://www.kernel.org/doc/man-pages/ に書かれている。