| .\" |
| .\" epoll by Davide Libenzi ( efficient event notification retrieval ) |
| .\" Copyright (C) 2003 Davide Libenzi |
| .\" |
| .\" 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 program; if not, write to the Free Software |
| .\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA |
| .\" |
| .\" Davide Libenzi <davidel@xmailserver.org> |
| .\" |
| .TH EPOLL_CTL 2 2008-04-25 "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 |
| Control an |
| .B epoll |
| descriptor, |
| .IR epfd , |
| by requesting that the operation |
| .I op |
| be performed on the target file descriptor, |
| .IR fd . |
| The |
| .I event |
| 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 re-enable the file descriptor with a new event mask. |
| .PP |
| The |
| .B epoll |
| interface supports all file descriptors that support |
| .BR poll (2). |
| Valid values for the |
| .I op |
| argument are : |
| .RS |
| .TP |
| .B EPOLL_CTL_ADD |
| Add the target file descriptor |
| .I fd |
| to the |
| .B epoll |
| 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 the target file descriptor |
| .I fd |
| from the |
| .B epoll |
| file descriptor, |
| .IR epfd . |
| The |
| .I event |
| is ignored and can be NULL (but see BUGS below). |
| .RE |
| .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 in |
| .IR epfd . |
| .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 in |
| .IR epfd . |
| .TP |
| .B ENOMEM |
| There was insufficient memory to handle the requested |
| .I op |
| control operation. |
| .TP |
| .B EPERM |
| The target file |
| .I fd |
| does not support |
| .BR epoll . |
| .SH CONFORMING TO |
| .BR epoll_ctl () |
| is Linux-specific, and was introduced in kernel 2.5.44. |
| .\" The interface should be finalized by Linux kernel 2.5.66. |
| .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 . |
| .SH "SEE ALSO" |
| .BR epoll_create (2), |
| .BR epoll_wait (2), |
| .BR poll (2), |
| .BR epoll (7) |