.\" -*- coding: UTF-8 -*- .\" Copyright (C) 2003 Davide Libenzi .\" Davide Libenzi .\" and Copyright 2009, 2014, 2016, 2018, 2019 Michael Kerrisk .\" .\" SPDX-License-Identifier: GPL-2.0-or-later .\" .\"******************************************************************* .\" .\" This file was generated with po4a. Translate the source file. .\" .\"******************************************************************* .TH epoll_ctl 2 "12 июня 2024 г." "Справочные страницы Linux 6.9.1" .SH ИМЯ epoll_ctl \- интерфейс управления файловым дескриптором epoll .SH БИБЛИОТЕКА Стандартная библиотека языка C (\fIlibc\fP, \fI\-lc\fP) .SH СИНТАКСИС .nf \fB#include \fP .P \fBint epoll_ctl(int \fP\fIepfd\fP\fB, int \fP\fIop\fP\fB, int \fP\fIfd\fP\fB,\fP \fB struct epoll_event *_Nullable \fP\fIevent\fP\fB);\fP .fi .SH ОПИСАНИЕ Данный системный вызов, используется для добавления, изменения или удаления записей в списке interest экземпляра \fBepoll\fP(7), на который указывает файловый дескриптор \fIepfd\fP. Он запрашивает выполнение операции \fIop\fP для файлового дескриптора назначения \fIfd\fP. .P Допустимые значения аргумента \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 (но смотрите ДЕФЕКТЫ далее). .P The \fIevent\fP argument describes the object linked to the file descriptor \fIfd\fP. The \fIstruct epoll_event\fP is described in \fBepoll_event\fP(3type). .P 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. .P The \fIevents\fP member of the \fIepoll_event\fP structure is a bit mask composed by ORing together zero or more event types, returned by \fBepoll_wait\fP(2), and input flags, which affect its behaviour, but aren't returned. The available event types are: .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 (конец файла) только после потребления всех неполученных данных в канале. .P And the available input flags are: .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. .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. .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. Также смотрите ДЕФЕКТЫ. .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 may be used only in an \fBEPOLL_CTL_ADD\fP operation; attempts to employ it with \fBEPOLL_CTL_MOD\fP yield an error. If \fBEPOLLEXCLUSIVE\fP has been set using \fBepoll_ctl\fP(), then a subsequent \fBEPOLL_CTL_MOD\fP on the same \fIepfd\fP,\ \fIfd\fP pair yields an error. A call to \fBepoll_ctl\fP() that specifies \fBEPOLLEXCLUSIVE\fP in \fIevents\fP and specifies the target file descriptor \fIfd\fP as an epoll instance will likewise fail. The error in all of these cases is \fBEINVAL\fP. .SH "ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ" When successful, \fBepoll_ctl\fP() returns zero. When an error occurs, \fBepoll_ctl\fP() returns \-1 and \fIerrno\fP is set to indicate the error. .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 was \fBEPOLL_CTL_MOD\fP and the \fBEPOLLEXCLUSIVE\fP flag has previously been applied to this \fIepfd\fP,\ \fIfd\fP pair. .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 СТАНДАРТЫ Linux. .SH ИСТОРИЯ .\" To be precise: Linux 2.5.44. .\" The interface should be finalized by Linux 2.5.66. Linux 2.6, glibc 2.3.2. .SH ПРИМЕЧАНИЯ Интерфейс \fBepoll\fP поддерживает все файловые дескрипторы, которые поддерживает \fBpoll\fP(2). .SH ОШИБКИ Before Linux 2.6.9, the \fBEPOLL_CTL_DEL\fP operation required a non\-null pointer in \fIevent\fP, even though this argument is ignored. Since Linux 2.6.9, \fIevent\fP can be specified as NULL when using \fBEPOLL_CTL_DEL\fP. Applications that need to be portable to kernels before Linux 2.6.9 should specify a non\-null pointer in \fIevent\fP. .P .\" 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), \fBioctl_eventpoll\fP(2), \fBpoll\fP(2), \fBepoll\fP(7) .PP .SH ПЕРЕВОД Русский перевод этой страницы руководства разработал(и) Azamat Hackimov , Yuri Kozlov и Иван Павлов . .PP Этот перевод является свободной программной документацией; он распространяется на условиях общедоступной лицензии GNU (GNU General Public License - GPL, .UR https://www.gnu.org/licenses/gpl-3.0.html .UE версии 3 или более поздней) в отношении авторского права, но БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ. .PP Если вы обнаружите какие-либо ошибки в переводе этой страницы руководства, пожалуйста, сообщите об этом разработчику(ам) по его(их) адресу(ам) электронной почты или по адресу .MT списка рассылки русских переводчиков .ME .