+++ /dev/null
-.\" Copyright (C) 2003 Davide Libenzi
-.\" Davide Libenzi <davidel@xmailserver.org>
-.\"
-.\" %%%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
-.\" <http://www.gnu.org/licenses/>.
-.\" %%%LICENSE_END
-.\"
-.TH EPOLL_CTL 2 2014-12-31 "Linux" "Linux Programmer's Manual"
-.SH NAME
-epoll_ctl \- control interface for an epoll descriptor
-.SH SYNOPSIS
-.B #include <sys/epoll.h>
-.sp
-.BI "int epoll_ctl(int " epfd ", int " op ", int " fd \
-", struct epoll_event *" event );
-.SH DESCRIPTION
-This system call performs control operations on the
-.BR epoll (7)
-instance
-referred to by the file descriptor
-.IR epfd .
-It requests that the operation
-.I op
-be performed for the target file descriptor,
-.IR fd .
-
-Valid values for the
-.I op
-argument are:
-.TP
-.B EPOLL_CTL_ADD
-Register the target file descriptor
-.I fd
-on the
-.B epoll
-instance referred to by the file descriptor
-.I epfd
-and associate the event
-.I event
-with the internal file linked to
-.IR fd .
-.TP
-.B EPOLL_CTL_MOD
-Change the event
-.I event
-associated with the target file descriptor
-.IR fd .
-.TP
-.B EPOLL_CTL_DEL
-Remove (deregister) the target file descriptor
-.I fd
-from the
-.B epoll
-instance referred to by
-.IR epfd .
-The
-.I event
-is ignored and can be NULL (but see BUGS below).
-.PP
-The
-.I event
-argument describes the object linked to the file descriptor
-.IR fd .
-The
-.I struct epoll_event
-is defined as:
-.sp
-.in +4n
-.nf
-typedef union epoll_data {
- void *ptr;
- int fd;
- uint32_t u32;
- uint64_t u64;
-} epoll_data_t;
-
-struct epoll_event {
- uint32_t events; /* Epoll events */
- epoll_data_t data; /* User data variable */
-};
-.fi
-.in
-
-The
-.I events
-member is a bit set composed using the following available event
-types:
-.TP
-.B EPOLLIN
-The associated file is available for
-.BR read (2)
-operations.
-.TP
-.B EPOLLOUT
-The associated file is available for
-.BR write (2)
-operations.
-.TP
-.BR EPOLLRDHUP " (since Linux 2.6.17)"
-Stream socket peer closed connection,
-or shut down writing half of connection.
-(This flag is especially useful for writing simple code to detect
-peer shutdown when using Edge Triggered monitoring.)
-.TP
-.B EPOLLPRI
-There is urgent data available for
-.BR read (2)
-operations.
-.TP
-.B EPOLLERR
-Error condition happened on the associated file descriptor.
-.BR epoll_wait (2)
-will always wait for this event; it is not necessary to set it in
-.IR events .
-.TP
-.B EPOLLHUP
-Hang up happened on the associated file descriptor.
-.BR epoll_wait (2)
-will always wait for this event; it is not necessary to set it in
-.IR events .
-.TP
-.B EPOLLET
-Sets the Edge Triggered behavior for the associated file descriptor.
-The default behavior for
-.B epoll
-is Level Triggered.
-See
-.BR epoll (7)
-for more detailed information about Edge and Level Triggered event
-distribution architectures.
-.TP
-.BR EPOLLONESHOT " (since Linux 2.6.2)"
-Sets the one-shot behavior for the associated file descriptor.
-This means that after an event is pulled out with
-.BR epoll_wait (2)
-the associated file descriptor is internally disabled and no other events
-will be reported by the
-.B epoll
-interface.
-The user must call
-.BR epoll_ctl ()
-with
-.B EPOLL_CTL_MOD
-to rearm the file descriptor with a new event mask.
-.TP
-.BR EPOLLWAKEUP " (since Linux 3.5)"
-.\" commit 4d7e30d98939a0340022ccd49325a3d70f7e0238
-If
-.B EPOLLONESHOT
-and
-.B EPOLLET
-are clear and the process has the
-.B CAP_BLOCK_SUSPEND
-capability,
-ensure that the system does not enter "suspend" or
-"hibernate" while this event is pending or being processed.
-The event is considered as being "processed" from the time
-when it is returned by a call to
-.BR epoll_wait (2)
-until the next call to
-.BR epoll_wait (2)
-on the same
-.BR epoll (7)
-file descriptor,
-the closure of that file descriptor,
-the removal of the event file descriptor with
-.BR EPOLL_CTL_DEL ,
-or the clearing of
-.B EPOLLWAKEUP
-for the event file descriptor with
-.BR EPOLL_CTL_MOD .
-See also BUGS.
-.SH RETURN VALUE
-When successful,
-.BR epoll_ctl ()
-returns zero.
-When an error occurs,
-.BR epoll_ctl ()
-returns \-1 and
-.I errno
-is set appropriately.
-.SH ERRORS
-.TP
-.B EBADF
-.I epfd
-or
-.I fd
-is not a valid file descriptor.
-.TP
-.B EEXIST
-.I op
-was
-.BR EPOLL_CTL_ADD ,
-and the supplied file descriptor
-.I fd
-is already registered with this epoll instance.
-.TP
-.B EINVAL
-.I epfd
-is not an
-.B epoll
-file descriptor,
-or
-.I fd
-is the same as
-.IR epfd ,
-or the requested operation
-.I op
-is not supported by this interface.
-.TP
-.B ENOENT
-.I op
-was
-.B EPOLL_CTL_MOD
-or
-.BR EPOLL_CTL_DEL ,
-and
-.I fd
-is not registered with this epoll instance.
-.TP
-.B ENOMEM
-There was insufficient memory to handle the requested
-.I op
-control operation.
-.TP
-.B ENOSPC
-The limit imposed by
-.I /proc/sys/fs/epoll/max_user_watches
-was encountered while trying to register
-.RB ( EPOLL_CTL_ADD )
-a new file descriptor on an epoll instance.
-See
-.BR epoll (7)
-for further details.
-.TP
-.B EPERM
-The target file
-.I fd
-does not support
-.BR epoll .
-This error can occur if
-.I fd
-refers to, for example, a regular file or a directory.
-.SH VERSIONS
-.BR epoll_ctl ()
-was added to the kernel in version 2.6.
-.\" To be precise: kernel 2.5.44.
-.\" The interface should be finalized by Linux kernel 2.5.66.
-.SH CONFORMING TO
-.BR epoll_ctl ()
-is Linux-specific.
-Library support is provided in glibc starting with version 2.3.2.
-.SH NOTES
-The
-.B epoll
-interface supports all file descriptors that support
-.BR poll (2).
-.SH BUGS
-In kernel versions before 2.6.9, the
-.B EPOLL_CTL_DEL
-operation required a non-null pointer in
-.IR event ,
-even though this argument is ignored.
-Since Linux 2.6.9,
-.I event
-can be specified as NULL
-when using
-.BR EPOLL_CTL_DEL .
-Applications that need to be portable to kernels before 2.6.9
-should specify a non-null pointer in
-.IR event .
-
-If
-.B EPOLLWAKEUP
-is specified in
-.IR flags ,
-but the caller does not have the
-.BR CAP_BLOCK_SUSPEND
-capability, then the
-.B EPOLLWAKEUP
-flag is
-.IR "silently ignored" .
-This unfortunate behavior is necessary because no validity
-checks were performed on the
-.IR flags
-argument in the original implementation, and the addition of the
-.B EPOLLWAKEUP
-with a check that caused the call to fail if the caller did not have the
-.B CAP_BLOCK_SUSPEND
-capability caused a breakage in at least one existing user-space
-application that happened to randomly (and uselessly) specify this bit.
-.\" commit a8159414d7e3af7233e7a5a82d1c5d85379bd75c (behavior change)
-.\" https://lwn.net/Articles/520198/
-A robust application should therefore double check that it has the
-.B CAP_BLOCK_SUSPEND
-capability if attempting to use the
-.B EPOLLWAKEUP
-flag.
-.SH SEE ALSO
-.BR epoll_create (2),
-.BR epoll_wait (2),
-.BR poll (2),
-.BR epoll (7)
-.SH COLOPHON
-This page is part of release 3.79 of the Linux
-.I man-pages
-project.
-A description of the project,
-information about reporting bugs,
-and the latest version of this page,
-can be found at
-\%http://www.kernel.org/doc/man\-pages/.
OSDN Git Service
