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