epoll_wait(2)

НАИМЕНОВАНИЕ
epoll_wait, epoll_pwait, epoll_pwait2 - ждать события ввода/вывода на файловом дескрипторе epoll

БИБЛИОТЕКА
Standard C library (libc, -lc)

ОБЗОР
#include <sys/epoll.h>

int epoll_wait(int epfd, struct epoll_event events[.maxevents],
               int maxevents, int timeout);
int epoll_pwait(int epfd, struct epoll_event events[.maxevents],
               int maxevents, int timeout,
               const sigset_t *_Nullable sigmask);
int epoll_pwait2(int epfd, struct epoll_event events[.maxevents],
               int maxevents, const struct timespec *_Nullable timeout,
               const sigset_t *_Nullable 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.

В аргументе timeout указывается количество миллисекунд, на которые будет заблокирован epoll_wait(). Время отслеживается по часам CLOCK_MONOTONIC.

Вызов epoll_wait() будет заблокирован до тех пор, пока:

•   событие не будет доставлено в файловый дескриптор;

•   вызов не прервётся обработчиком сигнала;

•   не истечёт время ожидания.

Note that the timeout interval will be rounded up to the system clock granularity, and kernel scheduling delays mean that the blocking interval may overrun by a small amount. Specifying a timeout of -1 causes epoll_wait() to block indefinitely, while specifying a timeout equal to zero causes epoll_wait() to return immediately, even if no events are available.

struct epoll_event описан в epoll_event(3type).

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);

эквивалентен атомарному выполнению следующих вызовов:

    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_pwait2()
The epoll_pwait2() system call is equivalent to epoll_pwait() except for the timeout argument. It takes an argument of type timespec to be able to specify nanosecond resolution timeout. This argument functions the same as in pselect(2) and ppoll(2). If timeout is NULL, then epoll_pwait2() can block indefinitely.

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
On success, epoll_wait() returns the number of file descriptors ready for the requested I/O operation, or zero if no file descriptor became ready during the requested timeout milliseconds. On failure, epoll_wait() returns -1 and errno is set to indicate the error.

ОШИБКИ

EBADF
    Значение epfd не является правильным файловым дескриптором.

EFAULT
    Память, указанная events, недоступна на запись из-за прав доступа.

EINTR
    Вызов был прерван обработчиком сигнала до возникновения любого из запрошенных событий или истечения timeout; см. signal(7).

EINVAL
    epfd не является файловым дескриптором epoll, или maxevents меньше или равно нулю.

СТАНДАРТЫ
Linux.

ИСТОРИЯ

epoll_wait()
    Linux 2.6, glibc 2.3.2.

epoll_pwait()
    Linux 2.6.19, glibc 2.6.

epoll_pwait2()
    Linux 5.11.

ПРИМЕЧАНИЯ
Пока одна нить блокирована в вызове epoll_wait(), в другой нити возможно добавить файловый дескриптор, который будет ожидаться экземпляром epoll. Как только новый файловый дескриптор станет готовым, это разблокирует вызов epoll_wait().

Если готово более maxevents файловых дескрипторов при вызове epoll_wait(), то последующие вызовы epoll_wait() циклически обработают весь набор готовых файловых дескрипторов. Такое поведение помогает избежать голодания — когда процесс не уведомляется, что дополнительные файловые дескрипторы готовы, так как он нацелен на набор файловых дескрипторов, про которые уже известно об их готовности.

Заметим, что возможно вызвать epoll_wait() для экземпляра epoll, чей список interest ещё пуст (или чей список interest станет пустым, так как файловые дескрипторы закрыты или удалены из interest в другой нити). Вызов будет заблокирован до тех пор, пока какой-нибудь файловый дескриптор не будет добавлен в список interest (в другой нити) и этот файлоый дескриптор не станет готовым.

  Отличия между библиотекой C и ядром
The raw epoll_pwait() and epoll_pwait2() system calls have a sixth argument, size_t sigsetsize, which specifies the size in bytes of the sigmask argument. The glibc epoll_pwait() wrapper function specifies this argument as a fixed value (equal to sizeof(sigset_t)).

ОШИБКИ
Before Linux 2.6.37, a timeout value larger than approximately LONG_MAX / HZ milliseconds is treated as -1 (i.e., infinity). Thus, for example, on a system where sizeof(long) is 4 and the kernel HZ value is 1000, this means that timeouts greater than 35.79 minutes are treated as infinity.

СМОТРИТЕ ТАКЖЕ
epoll_create(2), epoll_ctl(2), epoll(7)

ПЕРЕВОД
Русский перевод этой страницы руководства разработал(и) Azamat Hackimov <azamat.hackimov@gmail.com>, Yuri Kozlov <yuray@komyakino.ru>, Иван Павлов <pavia00@gmail.com> и Kirill Rekhov <krekhov.dev@gmail.com>

Этот перевод является свободной программной документацией; он распространяется на условиях общедоступной лицензии GNU (GNU General Public License - GPL, https://www.gnu.org/licenses/gpl-3.0.html версии 3 или более поздней) в отношении авторского права, но БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ.

Если вы обнаружите какие-либо ошибки в переводе этой страницы руководства, пожалуйста, сообщите об этом разработчику(ам) по его(их) адресу(ам) электронной почты или по адресу списка рассылки русских переводчиков (<debian-l10n-russian@lists.debian.org>).