1 EPOLL_CTL(3C) Standard C Library Functions EPOLL_CTL(3C)
2
3
4
5 NAME
6 epoll_ctl - control an epoll instance
7
8 SYNOPSIS
9 #include <sys/epoll.h>
10
11 int epoll_ctl(int epfd, int op, int fd, struct epoll_event *event);
12
13
14 DESCRIPTION
15 The epoll_ctl() function executes the operation specified by op (as
16 parameterized by event) on the epfd epoll instance. Valid values for
17 op:
18
19
20 EPOLL_CTL_ADD
21 For the epoll(5) instance specified by epfd, associate the
22 file descriptor specified by fd with the event specified by
23 event.
24
25
26 EPOLL_CTL_DEL
27 For the epoll(5) instance specified by epfd, remove all
28 event associations for the file descriptor specified by fd.
29 event is ignored, and may be NULL.
30
31
32 EPOLL_CTL_MOD
33 For the epoll(5) instance specified by epfd, modify the
34 event association for the file descriptor specified by fd
35 to be that specified by event.
36
37
38 The event parameter has the following structure:
39
40 typedef union epoll_data {
41 void *ptr;
42 int fd;
43 uint32_t u32;
44 uint64_t u64;
45 } epoll_data_t;
46
47 struct epoll_event {
48 uint32_t events;
49 epoll_data_t data;
50 };
51
52 The data field specifies the datum to be associated with the event and
53 will be returned via epoll_wait(3C). The events field denotes both the
54 desired events (when specified via epoll_ctl()) and the events that
55 have occurred (when returned via epoll_wait(3C)). In either case, the
56 events field is a bitmask constructed by a logical OR operation of any
57 combination of the following event flags:
58
59
60 EPOLLIN
61 Data other than high priority data may be read without
62 blocking. For streams, this flag is set in the returned
63 events even if the message is of zero length.
64
65
66 EPOLLPRI
67 Normal data (priority band equals 0) may be read without
68 blocking. For streams, this flag is set in the returned
69 events even if the message is of zero length.
70
71
72 EPOLLOUT
73 Normal data (priority band equals 0) may be written
74 without blocking.
75
76
77 EPOLLRDNORM
78 Normal data (priority band equals 0) may be read without
79 blocking. For streams, this flag is set in the returned
80 revents even if the message is of zero length.
81
82
83 EPOLLRDBAND
84 Data from a non-zero priority band may be read without
85 blocking. For streams, this flag is set in the returned
86 revents even if the message is of zero length.
87
88
89 EPOLLWRNORM
90 The same as EPOLLOUT.
91
92
93 EPOLLWRBAND
94 Priority data (priority band > 0) may be written. This
95 event only examines bands that have been written to at
96 least once.
97
98
99 EPOLLMSG
100 This exists only for backwards binary and source
101 compatibility with Linux; it has no meaning and is
102 ignored.
103
104
105 EPOLLERR
106 An error has occurred on the device or stream. This flag
107 is only valid in the returned events field.
108
109
110 EPOLLHUP
111 A hangup has occurred on the stream. This event and
112 EPOLLOUT are mutually exclusive; a stream can never be
113 writable if a hangup has occurred. However, this event
114 and EPOLLIN, EPOLLRDNORM, EPOLLRDBAND, EPOLLRDHUP or
115 EPOLLPRI are not mutually exclusive. This flag is only
116 valid in the events field returned from epoll_wait(3C);
117 it is not used in the events field specified via
118 epoll_ctl().
119
120
121 EPOLLRDHUP
122 The stream socket peer shutdown the writing half of the
123 connection and no further data will be readable via the
124 socket. This event is not mutually exclusive with
125 EPOLLIN.
126
127
128 EPOLLWAKEUP
129 This exists only for backwards binary and source
130 compatibility with Linux; it has no meaning and is
131 ignored.
132
133
134 EPOLLONESHOT
135 Sets the specified event to be in one-shot mode, whereby
136 the event association with the epoll(5) instance
137 specified by epfd is removed atomically as the event is
138 returned via epoll_wait(3C). Use of this mode allows for
139 resolution of some of the races inherent in multithreaded
140 use of epoll_wait(3C).
141
142
143 EPOLLET
144 Sets the specified event to be edge-triggered mode
145 instead of the default mode of level-triggered. In this
146 mode, events will be induced by transitions on an event
147 source rather than the state of the event source. While
148 perhaps superficially appealing, this mode introduces
149 several new potential failure modes for user-level
150 software and should be used with caution.
151
152
153 RETURN VALUES
154 Upon successful completion, epoll_ctl() returns 0. If an error occurs,
155 -1 is returned and errno is set to indicate the error.
156
157
158 ERRORS
159 epoll_ctl() will fail if:
160
161 EBADF
162 epfd is not a valid file descriptor.
163
164
165 EFAULT
166 The memory associated with event was not mapped.
167
168
169 EEXIST
170 The operation specified was EPOLL_CTL_ADD and the specified
171 file descriptor is already associated with an event for the
172 specified epoll(5) instance.
173
174
175 ENOENT
176 The operation specified was EPOLL_CTL_MOD or EPOLL_CTL_DEL
177 and the specified file descriptor is not associated with an
178 event for the specified epoll(5) instance.
179
180
181
182 NOTES
183 The epoll(5) facility is implemented for purposes of offering
184 compatibility for Linux-borne applications; native applications should
185 continue to prefer using event ports via the port_create(3C),
186 port_associate(3C) and port_get(3C) interfaces. See epoll(5) for
187 compatibility details and restrictions.
188
189
190 SEE ALSO
191 epoll_create(3C), epoll_wait(3C), port_create(3C), port_associate(3C),
192 port_get(3C), epoll(5)
193
194
195
196 April 9, 2016 EPOLL_CTL(3C)