.\" -*- coding: UTF-8 -*- .\" Copyright (C) 2003 Davide Libenzi .\" Davide Libenzi .\" and Copyright 2009, 2014, 2016, 2018, 2019 Michael Kerrisk .\" .\" %%%LICENSE_START(GPLv2+_SW_3_PARA) .\" This program is free software; you can redistribute it and/or modify .\" it under the terms of the GNU General Public License as published by .\" the Free Software Foundation; either version 2 of the License, or .\" (at your option) any later version. .\" .\" This program is distributed in the hope that it will be useful, .\" but WITHOUT ANY WARRANTY; without even the implied warranty of .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the .\" GNU General Public License for more details. .\" .\" You should have received a copy of the GNU General Public .\" License along with this manual; if not, see .\" . .\" %%%LICENSE_END .\" .\"******************************************************************* .\" .\" This file was generated with po4a. Translate the source file. .\" .\"******************************************************************* .TH EPOLL_CTL 2 "1 ноября 2020 г." Linux "Руководство программиста Linux" .SH ИМЯ epoll_ctl \- интерфейс управления файловым дескриптором epoll .SH СИНТАКСИС \fB#include \fP .PP \fBint epoll_ctl(int \fP\fIepfd\fP\fB, int \fP\fIop\fP\fB, int \fP\fIfd\fP\fB, struct epoll_event *\fP\fIevent\fP\fB);\fP .SH ОПИСАНИЕ Данный системный вызов, используется для добавления, изменения или удаления записей в списке interest экземпляра \fBepoll\fP(7), на который указывает файловый дескриптор \fIepfd\fP. Он запрашивает выполнение операции \fIop\fP для файлового дескриптора назначения \fIfd\fP. .PP Допустимые значения аргумента \fIop\fP: .TP \fBEPOLL_CTL_ADD\fP Add an entry to the interest list of the epoll file descriptor, \fIepfd\fP. The entry includes the file descriptor, \fIfd\fP, a reference to the corresponding open file description (see \fBepoll\fP(7) and \fBopen\fP(2)), and the settings specified in \fIevent\fP. .TP \fBEPOLL_CTL_MOD\fP Изменить настройки, связанные с \fIfd\fP в списке interest, на новые, указанные в \fIevent\fP. .TP \fBEPOLL_CTL_DEL\fP Удалить (отменить регистрацию) файлового дескриптора назначения \fIfd\fP из списка interest. Значение \fIevent\fP игнорируется и может быть NULL (но смотрите ДЕФЕКТЫ далее). .PP Аргумент \fIevent\fP описывает объект, связанный с файловым дескриптором \fIfd\fP. Структура \fIstruct epoll_event\fP определена так: .PP .in +4n .EX 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; /* Переменная для данных пользователя */ }; .EE .in .PP The \fIdata\fP member of the \fIepoll_event\fP structure specifies data that the kernel should save and then return (via \fBepoll_wait\fP(2)) when this file descriptor becomes ready. .PP The \fIevents\fP member of the \fIepoll_event\fP structure is a bit mask composed by ORing together zero or more of the following available event types: .TP \fBEPOLLIN\fP Связанный файл доступен для чтения с помощью \fBread\fP(2). .TP \fBEPOLLOUT\fP Связанный файл доступен для записи с помощью \fBwrite\fP(2). .TP \fBEPOLLRDHUP\fP (начиная с Linux 2.6.17) Одна из сторон потокового сокета закрыла соединение или выключила записывающую часть соединения (этот флаг особенно полезен при написании простого кода для обнаружения отключения стороны с помощью слежения edge\-triggered). .TP \fBEPOLLPRI\fP Исключительное состояние файлового дескриптора. Смотрите описание \fBPOLLPRI\fP в \fBpoll\fP(2). .TP \fBEPOLLERR\fP Возникло ошибочное состояние связанного файлового дескриптора. Это событие также возникает на пишущей стороне канала, когда читающий конец закрылся. .IP \fBepoll_wait\fP(2) will always report for this event; it is not necessary to set it in \fIevents\fP when calling \fBepoll_ctl\fP(). .TP \fBEPOLLHUP\fP Hang up happened on the associated file descriptor. .IP \fBepoll_wait\fP(2) will always wait for this event; it is not necessary to set it in \fIevents\fP when calling \fBepoll_ctl\fP(). .IP Заметим, что при чтении из канала, такого как канал (pipe) или потоковый сокет, это событие всего\-навсего показывает, что партнёр закрыл канал со своего конца. Дальнейшее чтение из канала будет возвращать 0 (конец файла) только после потребления всех неполученных данных в канале. .TP \fBEPOLLET\fP Requests edge\-triggered notification for the associated file descriptor. The default behavior for \fBepoll\fP is level\-triggered. See \fBepoll\fP(7) for more detailed information about edge\-triggered and level\-triggered notification. .IP This flag is an input flag for the \fIevent.events\fP field when calling \fBepoll_ctl\fP(); it is never returned by \fBepoll_wait\fP(2). .TP \fBEPOLLONESHOT\fP (начиная с 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 \fBepoll_wait\fP(2), the file descriptor is disabled in the interest list and no other events will be reported by the \fBepoll\fP interface. The user must call \fBepoll_ctl\fP() with \fBEPOLL_CTL_MOD\fP to rearm the file descriptor with a new event mask. .IP This flag is an input flag for the \fIevent.events\fP field when calling \fBepoll_ctl\fP(); it is never returned by \fBepoll_wait\fP(2). .TP \fBEPOLLWAKEUP\fP (начиная с Linux 3.5) .\" commit 4d7e30d98939a0340022ccd49325a3d70f7e0238 Если флаги \fBEPOLLONESHOT\fP и \fBEPOLLET\fP сброшены и процесс имеет мандат \fBCAP_BLOCK_SUSPEND\fP, то убедитесь, что система не находится в режиме «suspend» или «hibernate», пока это событие ожидает обработки или обрабатывается. Событие считается «обрабатывающимся» начиная с момента, когда оно возвращается вызовом \fBepoll_wait\fP(2) и до следующего вызова \fBepoll_wait\fP(2) для того же файлового дескриптора \fBepoll\fP(7), закрытия этого файлового дескриптора, удаление файлового дескриптора события с помощью \fBEPOLL_CTL_DEL\fP или сброс \fBEPOLLWAKEUP\fP для файлового дескриптора события с помощью \fBEPOLL_CTL_MOD\fP. Также смотрите ДЕФЕКТЫ. .IP This flag is an input flag for the \fIevent.events\fP field when calling \fBepoll_ctl\fP(); it is never returned by \fBepoll_wait\fP(2). .TP \fBEPOLLEXCLUSIVE\fP (начиная с Linux 4.5) Установить единоличный режим пробуждения файлового дескриптора epoll, присоединённого к целевому файловому дескриптору \fIfd\fP. При появлении события пробуждения и к целевому файлу присоединены несколько файловых дескрипторов epoll с помощью \fBEPOLLEXCLUSIVE\fP, то события получат один или несколько файловых дескрипторов epoll через \fBepoll_wait\fP(2). По умолчанию в этом случае (если \fBEPOLLEXCLUSIVE\fP не установлен) все файловые дескрипторы epoll получают событие. Таким образом \fBEPOLLEXCLUSIVE\fP в некоторых случаях помогает избежать проблем стадной работы. .IP Если один файловый дескриптор указан в нескольких экземплярах epoll, и одни имеют флаг \fBEPOLLEXCLUSIVE\fP, а другие нет, то события получат все экземпляры epoll, у которых не указан \fBEPOLLEXCLUSIVE\fP, и, как минимум, один экземпляр epoll, у которого есть задан \fBEPOLLEXCLUSIVE\fP. .IP Следующие значения можно указывать вместе с \fBEPOLLEXCLUSIVE\fP: \fBEPOLLIN\fP, \fBEPOLLOUT\fP, \fBEPOLLWAKEUP\fP и \fBEPOLLET\fP. Также можно указывать \fBEPOLLHUP\fP и \fBEPOLLERR\fP, но они не обязательны: как обычно, события всегда приходят, если они возникают, независимо указаны ли они в \fIevents\fP. При указании других значений в \fIevents\fP возникает ошибка \fBEINVAL\fP. .IP \fBEPOLLEXCLUSIVE\fP можно использовать только в операции \fBEPOLL_CTL_ADD\fP; попытка использовать его в \fBEPOLL_CTL_MOD\fP вызывает ошибку. Если \fBEPOLLEXCLUSIVE\fP установлен с помощью \fBepoll_ctl\fP(), то последующая \fBEPOLL_CTL_MOD\fP с той же парой \fIepfd\fP,\ \fIfd\fP вызывает ошибку. Вызов \fBepoll_ctl\fP(), в котором указан \fBEPOLLEXCLUSIVE\fP в \fIevents\fP и целевой файловый дескриптор \fIfd\fP в качестве экземпляра epoll, также вызывает ошибку. Во всех случаях возникает ошибка \fBEINVAL\fP. .IP The \fBEPOLLEXCLUSIVE\fP flag is an input flag for the \fIevent.events\fP field when calling \fBepoll_ctl\fP(); it is never returned by \fBepoll_wait\fP(2). .SH "ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ" При успешном выполнении \fBepoll_ctl\fP() возвращается ноль. При возникновении ошибок \fBepoll_ctl\fP() возвращает \-1 и устанавливает \fIerrno\fP в соответствующее значение. .SH ОШИБКИ .TP \fBEBADF\fP Значение \fIepfd\fP или \fIfd\fP не является правильным файловым дескриптором. .TP \fBEEXIST\fP Значение \fIop\fP равно \fBEPOLL_CTL_ADD\fP, и указанный файловый дескриптор \fIfd\fP уже зарегистрирован в данном экземпляре epoll. .TP \fBEINVAL\fP Значение \fIepfd\fP не является файловым дескриптором \fBepoll\fP, или значение \fIfd\fP равно \fIepfd\fP, или запрашиваемая операция \fIop\fP не поддерживается данным интерфейсом. .TP \fBEINVAL\fP Указан недопустимый тип события, так как в \fIevents\fP установлен \fBEPOLLEXCLUSIVE\fP. .TP \fBEINVAL\fP Значение \fIop\fP равно \fBEPOLL_CTL_MOD\fP и \fIevents\fP содержит \fBEPOLLEXCLUSIVE\fP. .TP \fBEINVAL\fP Значение \fIop\fP равно \fBEPOLL_CTL_MOD\fP, а ранее для этой пары \fIepfd\fP,\ \fIfd\fP был применён флаг \fBEPOLLEXCLUSIVE\fP. .TP \fBEINVAL\fP Флаг \fBEPOLLEXCLUSIVE\fP указан в \fIevent\fP и \fIfd\fP ссылается на экземпляр epoll. .TP \fBELOOP\fP \fIfd\fP refers to an epoll instance and this \fBEPOLL_CTL_ADD\fP operation would result in a circular loop of epoll instances monitoring one another or a nesting depth of epoll instances greater than 5. .TP \fBENOENT\fP В \fIop\fP было указано \fBEPOLL_CTL_MOD\fP или \fBEPOLL_CTL_DEL\fP, а \fIfd\fP не было зарегистрировано в данном экземпляре epoll. .TP \fBENOMEM\fP Недостаточно памяти для обработки запрошенной управляющей операции \fIop\fP. .TP \fBENOSPC\fP При попытке регистрации (\fBEPOLL_CTL_ADD\fP) нового файлового дескриптора в экземпляре достигнут предел, накладываемый \fI/proc/sys/fs/epoll/max_user_watches\fP. Подробней см. в \fBepoll\fP(7). .TP \fBEPERM\fP Файл назначения \fIfd\fP не поддерживает \fBepoll\fP. Эта ошибка может возникнуть, если \fIfd\fP ссылается на, например, обычный файл или каталог. .SH ВЕРСИИ .\" To be precise: kernel 2.5.44. .\" The interface should be finalized by Linux kernel 2.5.66. Вызов \fBepoll_ctl\fP() был добавлен в ядро версии 2.6. В glibc соответствующая функция появилась в версии 2.3.2. .SH "СООТВЕТСТВИЕ СТАНДАРТАМ" Вызов \fBepoll_ctl\fP() есть только в Linux. .SH ЗАМЕЧАНИЯ Интерфейс \fBepoll\fP поддерживает все файловые дескрипторы, которые поддерживает \fBpoll\fP(2). .SH ДЕФЕКТЫ В ядрах до версии 2.6.9 для операции \fBEPOLL_CTL_DEL\fP в \fIevent\fP требовался указатель со значением не равным null, хотя этот аргумент игнорировался. Начиная с Linux 2.6.9, при \fBEPOLL_CTL_DEL\fP в \fIevent\fP можно указывать NULL. В переносимых приложениях, которые должны быть работоспособными в системах на ядрах до 2.6.9, в \fIevent\fP нужно указывать указатель со значением не равным null. .PP .\" commit a8159414d7e3af7233e7a5a82d1c5d85379bd75c (behavior change) .\" https://lwn.net/Articles/520198/ Если в \fIflags\fP указан \fBEPOLLWAKEUP\fP, но вызывающий не имеет мандата \fBCAP_BLOCK_SUSPEND\fP, то флаг \fBEPOLLWAKEUP\fP \fIпросто игнорируется\fP. Такое неуместное поведение необходимо, так как в первоначальной реализации не выполнялась проверка корректности аргумента \fIflags\fP, и добавление \fBEPOLLWAKEUP\fP с проверкой того, что вызов завершился с ошибкой, если вызывающий не имеет мандата \fBCAP_BLOCK_SUSPEND\fP, привело к поломке не одного существующего пользовательского приложения, которое произвольно устанавливало (и зря) этот бит. Корректное приложение должно дважды проверить, что имеет мандат \fBCAP_BLOCK_SUSPEND\fP, если пытается использовать флаг \fBEPOLLWAKEUP\fP. .SH "СМ. ТАКЖЕ" \fBepoll_create\fP(2), \fBepoll_wait\fP(2), \fBpoll\fP(2), \fBepoll\fP(7) .SH ЗАМЕЧАНИЯ Эта страница является частью проекта Linux \fIman\-pages\fP версии 5.10. Описание проекта, информацию об ошибках и последнюю версию этой страницы можно найти по адресу \%https://www.kernel.org/doc/man\-pages/. .PP .SH ПЕРЕВОД Русский перевод этой страницы руководства был сделан Azamat Hackimov , Yuri Kozlov и Иван Павлов . .PP Этот перевод является бесплатной документацией; прочитайте .UR https://www.gnu.org/licenses/gpl-3.0.html Стандартную общественную лицензию GNU версии 3 .UE или более позднюю, чтобы узнать об условиях авторского права. Мы не несем НИКАКОЙ ОТВЕТСТВЕННОСТИ. .PP Если вы обнаружите ошибки в переводе этой страницы руководства, пожалуйста, отправьте электронное письмо на .MT man-pages-ru-talks@lists.sourceforge.net .ME .