Provided by: manpages-ru-dev_4.21.0-2_all bug

ИМЯ

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

LIBRARY

       Standard C library (libc, -lc)

СИНТАКСИС

       #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
       <azamat.hackimov@gmail.com>,   Yuri   Kozlov   <yuray@komyakino.ru>    и    Иван    Павлов
       <pavia00@gmail.com>

       Этот  перевод  является  бесплатной  документацией;  прочитайте  Стандартную  общественную
       лицензию GNU версии 3 ⟨https://www.gnu.org/licenses/gpl-3.0.html⟩ или более позднюю, чтобы
       узнать об условиях авторского права. Мы не несем НИКАКОЙ ОТВЕТСТВЕННОСТИ.

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