1EPOLL_CTL(2) Linux Programmer's Manual EPOLL_CTL(2)
2
3
4
6 epoll_ctl - control interface for an epoll descriptor
7
9 #include <sys/epoll.h>
10
11 int epoll_ctl(int epfd, int op, int fd, struct epoll_event *event);
12
14 This system call performs control operations on the epoll(7) instance
15 referred to by the file descriptor epfd. It requests that the opera‐
16 tion op be performed for the target file descriptor, fd.
17
18 Valid values for the op argument are :
19
20 EPOLL_CTL_ADD
21 Register the target file descriptor fd on the epoll instance
22 referred to by the file descriptor epfd and associate the event
23 event with the internal file linked to fd.
24
25 EPOLL_CTL_MOD
26 Change the event event associated with the target file descrip‐
27 tor fd.
28
29 EPOLL_CTL_DEL
30 Remove (deregister) the target file descriptor fd from the epoll
31 instance referred to by epfd. The event is ignored and can be
32 NULL (but see BUGS below).
33
34 The event argument describes the object linked to the file descriptor
35 fd. The struct epoll_event is defined as :
36
37 typedef union epoll_data {
38 void *ptr;
39 int fd;
40 uint32_t u32;
41 uint64_t u64;
42 } epoll_data_t;
43
44 struct epoll_event {
45 uint32_t events; /* Epoll events */
46 epoll_data_t data; /* User data variable */
47 };
48
49 The events member is a bit set composed using the following available
50 event types:
51
52 EPOLLIN
53 The associated file is available for read(2) operations.
54
55 EPOLLOUT
56 The associated file is available for write(2) operations.
57
58 EPOLLRDHUP (since Linux 2.6.17)
59 Stream socket peer closed connection, or shut down writing half
60 of connection. (This flag is especially useful for writing sim‐
61 ple code to detect peer shutdown when using Edge Triggered moni‐
62 toring.)
63
64 EPOLLPRI
65 There is urgent data available for read(2) operations.
66
67 EPOLLERR
68 Error condition happened on the associated file descriptor.
69 epoll_wait(2) will always wait for this event; it is not neces‐
70 sary to set it in events.
71
72 EPOLLHUP
73 Hang up happened on the associated file descriptor.
74 epoll_wait(2) will always wait for this event; it is not neces‐
75 sary to set it in events.
76
77 EPOLLET
78 Sets the Edge Triggered behavior for the associated file
79 descriptor. The default behavior for epoll is Level Triggered.
80 See epoll(7) for more detailed information about Edge and Level
81 Triggered event distribution architectures.
82
83 EPOLLONESHOT (since Linux 2.6.2)
84 Sets the one-shot behavior for the associated file descriptor.
85 This means that after an event is pulled out with epoll_wait(2)
86 the associated file descriptor is internally disabled and no
87 other events will be reported by the epoll interface. The user
88 must call epoll_ctl() with EPOLL_CTL_MOD to rearm the file
89 descriptor with a new event mask.
90
92 When successful, epoll_ctl() returns zero. When an error occurs,
93 epoll_ctl() returns -1 and errno is set appropriately.
94
96 EBADF epfd or fd is not a valid file descriptor.
97
98 EEXIST op was EPOLL_CTL_ADD, and the supplied file descriptor fd is
99 already registered with this epoll instance.
100
101 EINVAL epfd is not an epoll file descriptor, or fd is the same as epfd,
102 or the requested operation op is not supported by this inter‐
103 face.
104
105 ENOENT op was EPOLL_CTL_MOD or EPOLL_CTL_DEL, and fd is not registered
106 with this epoll instance.
107
108 ENOMEM There was insufficient memory to handle the requested op control
109 operation.
110
111 ENOSPC The limit imposed by /proc/sys/fs/epoll/max_user_watches was
112 encountered while trying to register (EPOLL_CTL_ADD) a new file
113 descriptor on an epoll instance. See epoll(7) for further
114 details.
115
116 EPERM The target file fd does not support epoll.
117
119 epoll_ctl() was added to the kernel in version 2.6.
120
122 epoll_ctl() is Linux-specific. Library support is provided in glibc
123 starting with version 2.3.2.
124
126 The epoll interface supports all file descriptors that support poll(2).
127
129 In kernel versions before 2.6.9, the EPOLL_CTL_DEL operation required a
130 non-NULL pointer in event, even though this argument is ignored. Since
131 Linux 2.6.9, event can be specified as NULL when using EPOLL_CTL_DEL.
132 Applications that need to be portable to kernels before 2.6.9 should
133 specify a non-NULL pointer in event.
134
136 epoll_create(2), epoll_wait(2), poll(2), epoll(7)
137
139 This page is part of release 3.53 of the Linux man-pages project. A
140 description of the project, and information about reporting bugs, can
141 be found at http://www.kernel.org/doc/man-pages/.
142
143
144
145Linux 2012-04-15 EPOLL_CTL(2)