diff options
Diffstat (limited to 'man2/epoll_ctl.2')
| -rw-r--r-- | man2/epoll_ctl.2 | 187 |
1 files changed, 187 insertions, 0 deletions
diff --git a/man2/epoll_ctl.2 b/man2/epoll_ctl.2 new file mode 100644 index 000000000..9f79da969 --- /dev/null +++ b/man2/epoll_ctl.2 @@ -0,0 +1,187 @@ +.\" +.\" 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 "2002-10-23" Linux "Linux Programmer's Manual" +.SH NAME +epoll_ctl \- control interface for an epoll descriptor +.SH SYNOPSIS +.B #include <sys/epoll.h> +.sp +.BR "int epoll_ctl(int " epfd ", int " op ", int " fd ", struct epoll_event *" event ) +.SH DESCRIPTION +Control an +.B epoll +descriptor, +.IR epfd , +by requesting the operation +.IR op +be performed on the target file descriptor, +.IR fd . +The +.IR event +describes the object linked to the file descriptor +.IR fd . +The +.B struct epoll_event +is defined as : +.sp +.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 + +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 +.B EPOLLPRI +There is urgent data available for +.BR read (2) +operations. +.TP +.B EPOLLERR +Error condition happened on the associated file descriptor. +.TP +.B EPOLLHUP +Hang up happened on the associated file descriptor. +.TP +.B EPOLLET +Sets the Edge Triggered behaviour for the associated file descriptor. +The default behaviour for +.B epoll +is Level Triggered. See +.BR epoll (4) +for more detailed informations about Edge and Level Triggered event +distribution architectures. +.TP +.B EPOLLONESHOT +Sets the One-Shot behaviour for the associated file descriptor. It 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 (2) +with +.B EPOLL_CTL_MOD +to re-enable the file descriptor with a new event mask. +.PP +.sp +The +.B epoll +interface supports all file descriptors that support +.BR poll (2). +Valid values for the +.IR op +parameter 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 to 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 . +.RE +.SH "RETURN VALUE" +When successful, +.BR epoll_ctl (2) +returns zero. When an error occurs, +.BR epoll_ctl (2) +returns \-1 and +.I errno +is set appropriately. +.SH ERRORS +.TP +.B EBADF +The +.I epfd +file descriptor is not a valid file descriptor. +.TP +.B EINVAL +The supplied file descriptor, +.IR epfd , +is not an +.B epoll +file descriptor, or the requested operation +.I op +is not supported by this interface. +.TP +.B ENOMEM +There was insufficient memory to handle the requested +.I op +control operation. +.TP +.B EPERM +The target file +.I fd +is not supported by +.BR epoll . +.SH CONFORMING TO +.BR epoll_ctl (2) +is a new API introduced in Linux kernel 2.5.44. +The interface should be finalized by Linux kernel 2.5.66. +.SH "SEE ALSO" +.BR epoll_create (2), +.BR epoll_wait (2), +.BR epoll (4) |