名前

       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/ に書かれている。