epoll_ctl

ИМЯ

epoll_ctl - интерфейс управления файловым дескриптором epoll

СИНТАКСИС

#include <sys/epoll.h>

int epoll_ctl(int epfd, int op, int fd, struct epoll_event *_Nullable event);

Данный системный вызов, используется для добавления, изменения или удаления записей в списке interest экземпляра epoll(7), на который указывает файловый дескриптор epfd. Он запрашивает выполнение операции op для файлового дескриптора назначения fd.

Допустимые значения аргумента op:

EPOLL_CTL_ADD: Add an entry to the interest list of the epoll file descriptor, epfd. The entry includes the file descriptor, fd, a reference to the corresponding open file description (see epoll(7) and open(2)), and the settings specified in event.

EPOLL_CTL_MOD: Изменить настройки, связанные с fd в списке interest, на новые, указанные в event.

EPOLL_CTL_DEL: Удалить (отменить регистрацию) файлового дескриптора назначения fd из списка interest. Значение event игнорируется и может быть NULL (но смотрите ДЕФЕКТЫ далее).

The event argument describes the object linked to the file descriptor fd. The struct epoll_event is described in epoll_event(3type).

The data member of the epoll_event structure specifies data that the kernel should save and then return (via epoll_wait(2)) when this file descriptor becomes ready.

The events member of the epoll_event structure is a bit mask composed by ORing together zero or more event types, returned by epoll_wait(2), and input flags, which affect its behaviour, but aren't returned. The available event types are:

EPOLLIN: Связанный файл доступен для чтения с помощью read(2).

EPOLLOUT: Связанный файл доступен для записи с помощью write(2).

EPOLLRDHUP (начиная с Linux 2.6.17): Одна из сторон потокового сокета закрыла соединение или выключила записывающую часть соединения (этот флаг особенно полезен при написании простого кода для обнаружения отключения стороны с помощью слежения edge-triggered).

EPOLLPRI: Исключительное состояние файлового дескриптора. Смотрите описание POLLPRI в poll(2).

EPOLLERR: Возникло ошибочное состояние связанного файлового дескриптора. Это событие также возникает на пишущей стороне канала, когда читающий конец закрылся.

: epoll_wait(2) will always report for this event; it is not necessary to set it in events when calling epoll_ctl().

EPOLLHUP: Hang up happened on the associated file descriptor.

: epoll_wait(2) will always wait for this event; it is not necessary to set it in events when calling epoll_ctl().

: Заметим, что при чтении из канала, такого как канал (pipe) или потоковый сокет, это событие всего-навсего показывает, что партнёр закрыл канал со своего конца. Дальнейшее чтение из канала будет возвращать 0 (конец файла) только после потребления всех неполученных данных в канале.

And the available input flags are:

EPOLLET: Requests edge-triggered notification for the associated file descriptor. The default behavior for epoll is level-triggered. See epoll(7) for more detailed information about edge-triggered and level-triggered notification.

EPOLLONESHOT (начиная с Linux 2.6.2): Requests one-shot notification for the associated file descriptor. This means that after an event notified for the file descriptor by epoll_wait(2), the file descriptor is disabled in the interest list and no other events will be reported by the epoll interface. The user must call epoll_ctl() with EPOLL_CTL_MOD to rearm the file descriptor with a new event mask.

EPOLLWAKEUP (начиная с Linux 3.5): Если флаги EPOLLONESHOT и EPOLLET сброшены и процесс имеет мандат CAP_BLOCK_SUSPEND, то убедитесь, что система не находится в режиме «suspend» или «hibernate», пока это событие ожидает обработки или обрабатывается. Событие считается «обрабатывающимся» начиная с момента, когда оно возвращается вызовом epoll_wait(2) и до следующего вызова epoll_wait(2) для того же файлового дескриптора epoll(7), закрытия этого файлового дескриптора, удаление файлового дескриптора события с помощью EPOLL_CTL_DEL или сброс EPOLLWAKEUP для файлового дескриптора события с помощью EPOLL_CTL_MOD. Также смотрите ДЕФЕКТЫ.

EPOLLEXCLUSIVE (начиная с Linux 4.5): Установить единоличный режим пробуждения файлового дескриптора epoll, присоединённого к целевому файловому дескриптору fd. При появлении события пробуждения и к целевому файлу присоединены несколько файловых дескрипторов epoll с помощью EPOLLEXCLUSIVE, то события получат один или несколько файловых дескрипторов epoll через epoll_wait(2). По умолчанию в этом случае (если EPOLLEXCLUSIVE не установлен) все файловые дескрипторы epoll получают событие. Таким образом EPOLLEXCLUSIVE в некоторых случаях помогает избежать проблем стадной работы.

: Если один файловый дескриптор указан в нескольких экземплярах epoll, и одни имеют флаг EPOLLEXCLUSIVE, а другие нет, то события получат все экземпляры epoll, у которых не указан EPOLLEXCLUSIVE, и, как минимум, один экземпляр epoll, у которого есть задан EPOLLEXCLUSIVE.

: Следующие значения можно указывать вместе с EPOLLEXCLUSIVE: EPOLLIN, EPOLLOUT, EPOLLWAKEUP и EPOLLET. Также можно указывать EPOLLHUP и EPOLLERR, но они не обязательны: как обычно, события всегда приходят, если они возникают, независимо указаны ли они в events. При указании других значений в events возникает ошибка EINVAL.

: EPOLLEXCLUSIVE можно использовать только в операции EPOLL_CTL_ADD; попытка использовать его в EPOLL_CTL_MOD вызывает ошибку. Если EPOLLEXCLUSIVE установлен с помощью epoll_ctl(), то последующая EPOLL_CTL_MOD с той же парой epfd, fd вызывает ошибку. Вызов epoll_ctl(), в котором указан EPOLLEXCLUSIVE в events и целевой файловый дескриптор fd в качестве экземпляра epoll, также вызывает ошибку. Во всех случаях возникает ошибка EINVAL.

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ

When successful, epoll_ctl() returns zero. When an error occurs, epoll_ctl() returns -1 and errno is set to indicate the error.

ОШИБКИ

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

EEXIST: Значение op равно EPOLL_CTL_ADD, и указанный файловый дескриптор fd уже зарегистрирован в данном экземпляре epoll.

EINVAL: Значение epfd не является файловым дескриптором epoll, или значение fd равно epfd, или запрашиваемая операция op не поддерживается данным интерфейсом.

EINVAL: Указан недопустимый тип события, так как в events установлен EPOLLEXCLUSIVE.

EINVAL: Значение op равно EPOLL_CTL_MOD и events содержит EPOLLEXCLUSIVE.

EINVAL: Значение op равно EPOLL_CTL_MOD, а ранее для этой пары epfd, fd был применён флаг EPOLLEXCLUSIVE.

EINVAL: Флаг EPOLLEXCLUSIVE указан в event и fd ссылается на экземпляр epoll.

ELOOP: fd refers to an epoll instance and this EPOLL_CTL_ADD operation would result in a circular loop of epoll instances monitoring one another or a nesting depth of epoll instances greater than 5.

ENOENT: В op было указано EPOLL_CTL_MOD или EPOLL_CTL_DEL, а fd не было зарегистрировано в данном экземпляре epoll.

ENOMEM: Недостаточно памяти для обработки запрошенной управляющей операции op.

ENOSPC: При попытке регистрации ( EPOLL_CTL_ADD) нового файлового дескриптора в экземпляре достигнут предел, накладываемый /proc/sys/fs/epoll/max_user_watches. Подробней см. в epoll(7).

EPERM: Файл назначения fd не поддерживает epoll. Эта ошибка может возникнуть, если fd ссылается на, например, обычный файл или каталог.

ВЕРСИИ

epoll_ctl() was added to in Linux 2.6. Library support is provided in glibc 2.3.2.

СТАНДАРТЫ

Вызов epoll_ctl() есть только в Linux.

ЗАМЕЧАНИЯ

Интерфейс epoll поддерживает все файловые дескрипторы, которые поддерживает poll(2).

ДЕФЕКТЫ

Before Linux 2.6.9, the EPOLL_CTL_DEL operation required a non-null pointer in event, even though this argument is ignored. Since Linux 2.6.9, event can be specified as NULL when using EPOLL_CTL_DEL. Applications that need to be portable to kernels before Linux 2.6.9 should specify a non-null pointer in event.

Если в flags указан EPOLLWAKEUP, но вызывающий не имеет мандата CAP_BLOCK_SUSPEND, то флаг EPOLLWAKEUP просто игнорируется. Такое неуместное поведение необходимо, так как в первоначальной реализации не выполнялась проверка корректности аргумента flags, и добавление EPOLLWAKEUP с проверкой того, что вызов завершился с ошибкой, если вызывающий не имеет мандата CAP_BLOCK_SUSPEND, привело к поломке не одного существующего пользовательского приложения, которое произвольно устанавливало (и зря) этот бит. Корректное приложение должно дважды проверить, что имеет мандат CAP_BLOCK_SUSPEND, если пытается использовать флаг EPOLLWAKEUP.

СМ. ТАКЖЕ

epoll_create(2), epoll_wait(2), poll(2), epoll(7)

ПЕРЕВОД

Русский перевод этой страницы руководства был сделан Azamat Hackimov <[email protected]>, Yuri Kozlov <[email protected]> и Иван Павлов <[email protected]>

Этот перевод является бесплатной документацией; прочитайте Стандартную общественную лицензию GNU версии 3 или более позднюю, чтобы узнать об условиях авторского права. Мы не несем НИКАКОЙ ОТВЕТСТВЕННОСТИ.

Если вы обнаружите ошибки в переводе этой страницы руководства, пожалуйста, отправьте электронное письмо на [email protected]

4 декабря 2022 г.

Linux man-pages 6.03