1. Manuals
  2. Leap-15.6
  3. man-pages-ru
  4. epoll_ctl(2)

Scroll to navigation

EPOLL_CTL(2) Руководство программиста Linux EPOLL_CTL(2)

ИМЯ

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

СИНТАКСИС

#include <sys/epoll.h>

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

ОПИСАНИЕ

This system call performs control operations on the epoll(7) instance referred to by the file descriptor epfd. It requests that the operation op be performed for the target file descriptor, fd.

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

Register the target file descriptor fd on the epoll instance referred to by the file descriptor epfd and associate the event event with the internal file linked to fd.
Change the event event associated with the target file descriptor fd.
Remove (deregister) the target file descriptor fd from the epoll instance referred to by epfd. The event is ignored and can be NULL (but see BUGS below).

Аргумент event описывает объект, связанный с файловым дескриптором fd. Структура 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;        /* Переменная для данных пользователя */
};

Поле events является битовой маской, составляемой из объединяемых (OR) нуля и более следующих возможных типов событий:

Связанный файл доступен для чтения с помощью read(2).
Связанный файл доступен для записи с помощью write(2).
Одна из сторон потокового сокета закрыла соединение или выключила записывающую часть соединения (этот флаг особенно полезен при написании простого кода для обнаружения отключения стороны с помощью слежения Edge Triggered).
Исключительное состояние файлового дескриптора. Смотрите описание POLLPRI в poll(2).
Возникло ошибочное состояние связанного файлового дескриптора. Это событие также возникает на пишущей стороне канала, когда читающий конец закрылся. Вызов epoll_wait(2) всегда будет сообщать об этом событии; его не нужно устанавливать в events.
Произошло зависание связанного файлового дескриптора. Вызов epoll_wait(2) будет всегда ждать этого события; его не нужно указывать в events.
Заметим, что при чтении из канала, такого как канал (pipe) или потоковый сокет, это событие всего-навсего показывает, что партнёр закрыл канал со своего конца. Дальнейшее чтение из канала будет возвращать 0 (конец файла) только после потребления всех неполученных данных в канале.
Установить поведение Edge Triggered для связанного файлового дескриптора. Поведение по умолчанию для epoll равно Level Triggered. Более подробное описание архитектуры распределения событий Edge и Level Triggered смотрите в epoll(7).
Установить однократное получение для связанного файлового дескриптора. Это означает, что после извлечения события с помощью epoll_wait(2) со связанным дескриптором приём отключается и о других событиях интерфейс epoll сообщать не будет. Пользователь должен вызвать epoll_ctl() с операцией EPOLL_CTL_MOD для переустановки новой маски событий для файлового дескриптора.
Если флаги EPOLLONESHOT и EPOLLET сброшены и процесс имеет мандат CAP_BLOCK_SUSPEND, то убедитесь, что система не находится в режиме «suspend» или «hibernate», пока это событие ожидает обработки или обрабатывается. Событие считается «обрабатывающимся» начиная с момента, когда оно возвращается вызовом epoll_wait(2) и до следующего вызова epoll_wait(2) для того же файлового дескриптора epoll(7), закрытия этого файлового дескриптора, удаление файлового дескриптора события с помощью EPOLL_CTL_DEL или сброс EPOLLWAKEUP для файлового дескриптора события с помощью EPOLL_CTL_MOD. Также смотрите ДЕФЕКТЫ.
Установить единоличный режим пробуждения файлового дескриптора epoll, присоединённого к целевому файловому дескриптору fd. При появлении события пробуждения и к целевому файлу присоединены несколько файловых дескрипторов epoll с помощью EPOLLEXCLUSIVE, то события получат один или несколько файловых дескрипторов epoll через epoll_wait(2). По умолчанию в этом случае (если EPOLLEXCLUSIVE не установлен) все файловые дескрипторы epoll получают событие. Таким образом EPOLLEXCLUSIVE в некоторых случаях помогает избежать проблем стадной работы.
Если один файловый дескриптор указан в нескольких экземплярах epoll, и одни имеют флаг EPOLLEXCLUSIVE, а другие нет, то события получат все экземпляры epoll, у которых не указан EPOLLEXCLUSIVE, и, как минимум, один экземпляр epoll, у которого есть задан EPOLLEXCLUSIVE.
The following values may be specified in conjunction with EPOLLEXCLUSIVE: EPOLLIN, EPOLLOUT, EPOLLWAKEUP, and EPOLLET. EPOLLHUP and EPOLLERR can also be specified, but this is not required: as usual, these events are always reported if they occur, regardless of whether they are specified in events. Attempts to specify other values in events yield an error. EPOLLEXCLUSIVE may be used only in an EPOLL_CTL_ADD operation; attempts to employ it with EPOLL_CTL_MOD yield an error. If EPOLLEXCLUSIVE has been set using epoll_ctl(), then a subsequent EPOLL_CTL_MOD on the same epfd, fd pair yields an error. A call to epoll_ctl() that specifies EPOLLEXCLUSIVE in events and specifies the target file descriptor fd as an epoll instance will likewise fail. The error in all of these cases is EINVAL.

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

При успешном выполнении epoll_ctl() возвращается ноль. При возникновении ошибок epoll_ctl() возвращает -1 и устанавливает errno в соответствующее значение.

ОШИБКИ

Значение epfd или fd не является правильным файловым дескриптором.
Значение op равно EPOLL_CTL_ADD, и указанный файловый дескриптор fd уже зарегистрирован в данном экземпляре epoll.
Значение epfd не является файловым дескриптором epoll, или значение fd равно epfd, или запрашиваемая операция op не поддерживается данным интерфейсом.
Указан недопустимый тип события, так как в events установлен EPOLLEXCLUSIVE.
Значение op равно EPOLL_CTL_MOD и events содержит EPOLLEXCLUSIVE.
Значение op равно EPOLL_CTL_MOD, а ранее для этой пары epfd, fd был применён флаг EPOLLEXCLUSIVE.
Флаг EPOLLEXCLUSIVE указан в event и fd ссылается на экземпляр epoll.
Значение fd ссылается на экземпляр epoll и эта операция EPOLL_CTL_ADD привела бы к зацикливанию экземпляров epoll, отслеживающих один другого.
В op было указано EPOLL_CTL_MOD или EPOLL_CTL_DEL, а fd не было зарегистрировано в данном экземпляре epoll.
Недостаточно памяти для обработки запрошенной управляющей операции op.
При попытке регистрации (EPOLL_CTL_ADD) нового файлового дескриптора в экземпляре достигнут предел, накладываемый /proc/sys/fs/epoll/max_user_watches. Подробней см. в epoll(7).
Файл назначения fd не поддерживает epoll. Эта ошибка может возникнуть, если fd ссылается на, например, обычный файл или каталог.

ВЕРСИИ

Системный вызов epoll_ctl() был добавлен в ядро версии 2.6.

СООТВЕТСТВИЕ СТАНДАРТАМ

Вызов epoll_ctl() есть только в Linux. В glibc соответствующая функция появилась в версии 2.3.2.

ЗАМЕЧАНИЯ

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

ДЕФЕКТЫ

В ядрах до версии 2.6.9 для операции EPOLL_CTL_DEL в event требовался указатель со значением не равным null, хотя этот аргумент игнорировался. Начиная с Linux 2.6.9, при EPOLL_CTL_DEL в event можно указывать NULL. В переносимых приложениях, которые должны быть работоспособными в системах на ядрах до 2.6.9, в event нужно указывать указатель со значением не равным null.

Если в 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)

ЗАМЕЧАНИЯ

Эта страница является частью проекта Linux man-pages версии 4.16. Описание проекта, информацию об ошибках и последнюю версию этой страницы можно найти по адресу https://www.kernel.org/doc/man-pages/.

ПЕРЕВОД

Русский перевод этой страницы руководства был сделан Azamat Hackimov <azamat.hackimov@gmail.com>, Yuri Kozlov <yuray@komyakino.ru> и Иван Павлов <pavia00@gmail.com>

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

Если вы обнаружите ошибки в переводе этой страницы руководства, пожалуйста, отправьте электронное письмо на man-pages-ru-talks@lists.sourceforge.net.

15 сентября 2017 г. Linux