| @@ -1,782 +1,783 @@ | | | @@ -1,782 +1,783 @@ |
1 | .\" $NetBSD: kqueue.2,v 1.52 2020/10/31 10:51:59 wiz Exp $ | | 1 | .\" $NetBSD: kqueue.2,v 1.53 2020/10/31 14:35:28 christos Exp $ |
2 | .\" | | 2 | .\" |
3 | .\" Copyright (c) 2000 Jonathan Lemon | | 3 | .\" Copyright (c) 2000 Jonathan Lemon |
4 | .\" All rights reserved. | | 4 | .\" All rights reserved. |
5 | .\" | | 5 | .\" |
6 | .\" Copyright (c) 2001, 2002, 2003 The NetBSD Foundation, Inc. | | 6 | .\" Copyright (c) 2001, 2002, 2003 The NetBSD Foundation, Inc. |
7 | .\" All rights reserved. | | 7 | .\" All rights reserved. |
8 | .\" | | 8 | .\" |
9 | .\" Portions of this documentation is derived from text contributed by | | 9 | .\" Portions of this documentation is derived from text contributed by |
10 | .\" Luke Mewburn. | | 10 | .\" Luke Mewburn. |
11 | .\" | | 11 | .\" |
12 | .\" Redistribution and use in source and binary forms, with or without | | 12 | .\" Redistribution and use in source and binary forms, with or without |
13 | .\" modification, are permitted provided that the following conditions | | 13 | .\" modification, are permitted provided that the following conditions |
14 | .\" are met: | | 14 | .\" are met: |
15 | .\" 1. Redistributions of source code must retain the above copyright | | 15 | .\" 1. Redistributions of source code must retain the above copyright |
16 | .\" notice, this list of conditions and the following disclaimer. | | 16 | .\" notice, this list of conditions and the following disclaimer. |
17 | .\" 2. Redistributions in binary form must reproduce the above copyright | | 17 | .\" 2. Redistributions in binary form must reproduce the above copyright |
18 | .\" notice, this list of conditions and the following disclaimer in the | | 18 | .\" notice, this list of conditions and the following disclaimer in the |
19 | .\" documentation and/or other materials provided with the distribution. | | 19 | .\" documentation and/or other materials provided with the distribution. |
20 | .\" | | 20 | .\" |
21 | .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND | | 21 | .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND |
22 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | | 22 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
23 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | | 23 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
24 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE | | 24 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE |
25 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | | 25 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL |
26 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | | 26 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS |
27 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | | 27 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) |
28 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | | 28 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT |
29 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | | 29 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY |
30 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | | 30 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF |
31 | .\" SUCH DAMAGE. | | 31 | .\" SUCH DAMAGE. |
32 | .\" | | 32 | .\" |
33 | .\" $FreeBSD: src/lib/libc/sys/kqueue.2,v 1.22 2001/06/27 19:55:57 dd Exp $ | | 33 | .\" $FreeBSD: src/lib/libc/sys/kqueue.2,v 1.22 2001/06/27 19:55:57 dd Exp $ |
34 | .\" | | 34 | .\" |
35 | .Dd October 30, 2020 | | 35 | .Dd October 30, 2020 |
36 | .Dt KQUEUE 2 | | 36 | .Dt KQUEUE 2 |
37 | .Os | | 37 | .Os |
38 | .Sh NAME | | 38 | .Sh NAME |
39 | .Nm kqueue , | | 39 | .Nm kqueue , |
40 | .Nm kqueue1 , | | 40 | .Nm kqueue1 , |
41 | .Nm kevent , | | 41 | .Nm kevent , |
42 | .Nm EV_SET | | 42 | .Nm EV_SET |
43 | .Nd kernel event notification mechanism | | 43 | .Nd kernel event notification mechanism |
44 | .Sh LIBRARY | | 44 | .Sh LIBRARY |
45 | .Lb libc | | 45 | .Lb libc |
46 | .Sh SYNOPSIS | | 46 | .Sh SYNOPSIS |
47 | .In sys/event.h | | 47 | .In sys/event.h |
48 | .In sys/time.h | | 48 | .In sys/time.h |
49 | .Ft int | | 49 | .Ft int |
50 | .Fn kqueue "void" | | 50 | .Fn kqueue "void" |
51 | .Ft int | | 51 | .Ft int |
52 | .Fn kqueue1 "int flags" | | 52 | .Fn kqueue1 "int flags" |
53 | .Ft int | | 53 | .Ft int |
54 | .Fn kevent "int kq" "const struct kevent *changelist" "size_t nchanges" "struct kevent *eventlist" "size_t nevents" "const struct timespec *timeout" | | 54 | .Fn kevent "int kq" "const struct kevent *changelist" "size_t nchanges" "struct kevent *eventlist" "size_t nevents" "const struct timespec *timeout" |
55 | .Fn EV_SET "&kev" ident filter flags fflags data udata | | 55 | .Fn EV_SET "&kev" ident filter flags fflags data udata |
56 | .Sh DESCRIPTION | | 56 | .Sh DESCRIPTION |
57 | The | | 57 | The |
58 | .Fn kqueue | | 58 | .Fn kqueue |
59 | system call | | 59 | system call |
60 | provides a generic method of notifying the user when an event | | 60 | provides a generic method of notifying the user when an event |
61 | happens or a condition holds, based on the results of small | | 61 | happens or a condition holds, based on the results of small |
62 | pieces of kernel code termed filters. | | 62 | pieces of kernel code termed filters. |
63 | A kevent is identified by the (ident, filter) pair; there may only | | 63 | A kevent is identified by the (ident, filter) pair; there may only |
64 | be one unique kevent per kqueue. | | 64 | be one unique kevent per kqueue. |
65 | .Pp | | 65 | .Pp |
66 | The filter is executed upon the initial registration of a kevent | | 66 | The filter is executed upon the initial registration of a kevent |
67 | in order to detect whether a preexisting condition is present, and is also | | 67 | in order to detect whether a preexisting condition is present, and is also |
68 | executed whenever an event is passed to the filter for evaluation. | | 68 | executed whenever an event is passed to the filter for evaluation. |
69 | If the filter determines that the condition should be reported, | | 69 | If the filter determines that the condition should be reported, |
70 | then the kevent is placed on the kqueue for the user to retrieve. | | 70 | then the kevent is placed on the kqueue for the user to retrieve. |
71 | .Pp | | 71 | .Pp |
72 | The filter is also run when the user attempts to retrieve the kevent | | 72 | The filter is also run when the user attempts to retrieve the kevent |
73 | from the kqueue. | | 73 | from the kqueue. |
74 | If the filter indicates that the condition that triggered | | 74 | If the filter indicates that the condition that triggered |
75 | the event no longer holds, the kevent is removed from the kqueue and | | 75 | the event no longer holds, the kevent is removed from the kqueue and |
76 | is not returned. | | 76 | is not returned. |
77 | .Pp | | 77 | .Pp |
78 | Multiple events which trigger the filter do not result in multiple | | 78 | Multiple events which trigger the filter do not result in multiple |
79 | kevents being placed on the kqueue; instead, the filter will aggregate | | 79 | kevents being placed on the kqueue; instead, the filter will aggregate |
80 | the events into a single struct kevent. | | 80 | the events into a single struct kevent. |
81 | Calling | | 81 | Calling |
82 | .Xr close 2 | | 82 | .Xr close 2 |
83 | on a file descriptor will remove any kevents that reference the descriptor. | | 83 | on a file descriptor will remove any kevents that reference the descriptor. |
84 | .Pp | | 84 | .Pp |
85 | The | | 85 | The |
86 | .Fn kqueue | | 86 | .Fn kqueue |
87 | system call | | 87 | system call |
88 | creates a new kernel event queue and returns a descriptor. | | 88 | creates a new kernel event queue and returns a descriptor. |
89 | .Pp | | 89 | .Pp |
90 | The | | 90 | The |
91 | .Fn kqueue1 | | 91 | .Fn kqueue1 |
92 | system call also allows to set the following | | 92 | system call also allows to set the following |
93 | .Fa flags | | 93 | .Fa flags |
94 | on the returned file descriptor: | | 94 | on the returned file descriptor: |
95 | .Bl -column O_NONBLOCK -offset indent | | 95 | .Bl -column O_NONBLOCK -offset indent |
96 | .It Dv O_CLOEXEC | | 96 | .It Dv O_CLOEXEC |
97 | Set the close on exec property. | | 97 | Set the close on exec property. |
98 | .It Dv O_NONBLOCK | | 98 | .It Dv O_NONBLOCK |
99 | Set non-blocking I/O. | | 99 | Set non-blocking I/O. |
100 | .It Dv O_NOSIGPIPE | | 100 | .It Dv O_NOSIGPIPE |
101 | Return | | 101 | Return |
102 | .Er EPIPE | | 102 | .Er EPIPE |
103 | instead of raising | | 103 | instead of raising |
104 | .Dv SIGPIPE . | | 104 | .Dv SIGPIPE . |
105 | .El | | 105 | .El |
106 | .Pp | | 106 | .Pp |
107 | The queue is not inherited by a child created with | | 107 | The queue is not inherited by a child created with |
108 | .Xr fork 2 . | | 108 | .Xr fork 2 . |
109 | .\" However, if | | 109 | .\" However, if |
110 | .\" .Xr rfork 2 | | 110 | .\" .Xr rfork 2 |
111 | .\" is called without the | | 111 | .\" is called without the |
112 | .\" .Dv RFFDG | | 112 | .\" .Dv RFFDG |
113 | .\" flag, then the descriptor table is shared, | | 113 | .\" flag, then the descriptor table is shared, |
114 | .\" which will allow sharing of the kqueue between two processes. | | 114 | .\" which will allow sharing of the kqueue between two processes. |
115 | .Pp | | 115 | .Pp |
116 | The | | 116 | The |
117 | .Fn kevent | | 117 | .Fn kevent |
118 | system call | | 118 | system call |
119 | is used to register events with the queue, and return any pending | | 119 | is used to register events with the queue, and return any pending |
120 | events to the user. | | 120 | events to the user. |
121 | The | | 121 | The |
122 | .Fa changelist | | 122 | .Fa changelist |
123 | argument | | 123 | argument |
124 | is a pointer to an array of | | 124 | is a pointer to an array of |
125 | .Va kevent | | 125 | .Va kevent |
126 | structures, as defined in | | 126 | structures, as defined in |
127 | .In sys/event.h . | | 127 | .In sys/event.h . |
128 | All changes contained in the | | 128 | All changes contained in the |
129 | .Fa changelist | | 129 | .Fa changelist |
130 | are applied before any pending events are read from the queue. | | 130 | are applied before any pending events are read from the queue. |
131 | The | | 131 | The |
132 | .Fa nchanges | | 132 | .Fa nchanges |
133 | argument | | 133 | argument |
134 | gives the size of | | 134 | gives the size of |
135 | .Fa changelist . | | 135 | .Fa changelist . |
136 | The | | 136 | The |
137 | .Fa eventlist | | 137 | .Fa eventlist |
138 | argument | | 138 | argument |
139 | is a pointer to an array of kevent structures. | | 139 | is a pointer to an array of kevent structures. |
140 | The | | 140 | The |
141 | .Fa nevents | | 141 | .Fa nevents |
142 | argument | | 142 | argument |
143 | determines the size of | | 143 | determines the size of |
144 | .Fa eventlist . | | 144 | .Fa eventlist . |
145 | When | | 145 | When |
146 | .Fa nevents | | 146 | .Fa nevents |
147 | is zero, | | 147 | is zero, |
148 | .Fn kevent | | 148 | .Fn kevent |
149 | will return immediately even if there is a | | 149 | will return immediately even if there is a |
150 | .Fa timeout | | 150 | .Fa timeout |
151 | specified unlike | | 151 | specified unlike |
152 | .Xr select 2 . | | 152 | .Xr select 2 . |
153 | If | | 153 | If |
154 | .Fa timeout | | 154 | .Fa timeout |
155 | is a | | 155 | is a |
156 | .No non- Ns Dv NULL | | 156 | .No non- Ns Dv NULL |
157 | pointer, it specifies a maximum interval to wait | | 157 | pointer, it specifies a maximum interval to wait |
158 | for an event, which will be interpreted as a | | 158 | for an event, which will be interpreted as a |
159 | .Li struct timespec . | | 159 | .Li struct timespec . |
160 | If | | 160 | If |
161 | .Fa timeout | | 161 | .Fa timeout |
162 | is a | | 162 | is a |
163 | .Dv NULL | | 163 | .Dv NULL |
164 | pointer, | | 164 | pointer, |
165 | .Fn kevent | | 165 | .Fn kevent |
166 | waits indefinitely. | | 166 | waits indefinitely. |
167 | To effect a poll, the | | 167 | To effect a poll, the |
168 | .Fa timeout | | 168 | .Fa timeout |
169 | argument should be | | 169 | argument should be |
170 | .No non- Ns Dv NULL , | | 170 | .No non- Ns Dv NULL , |
171 | pointing to a zero-valued | | 171 | pointing to a zero-valued |
172 | .Xr timespec 3 | | 172 | .Xr timespec 3 |
173 | structure. | | 173 | structure. |
174 | The same array may be used for the | | 174 | The same array may be used for the |
175 | .Fa changelist | | 175 | .Fa changelist |
176 | and | | 176 | and |
177 | .Fa eventlist . | | 177 | .Fa eventlist . |
178 | .Pp | | 178 | .Pp |
179 | The | | 179 | The |
180 | .Fn EV_SET | | 180 | .Fn EV_SET |
181 | macro is provided for ease of initializing a kevent structure. | | 181 | macro is provided for ease of initializing a kevent structure. |
182 | This macro does not evaluate its parameters multiple times. | | 182 | This macro does not evaluate its parameters multiple times. |
183 | .Pp | | 183 | .Pp |
184 | The | | 184 | The |
185 | .Va kevent | | 185 | .Va kevent |
186 | structure is defined as: | | 186 | structure is defined as: |
187 | .Bd -literal | | 187 | .Bd -literal |
188 | struct kevent { | | 188 | struct kevent { |
189 | uintptr_t ident; /* identifier for this event */ | | 189 | uintptr_t ident; /* identifier for this event */ |
190 | uint32_t filter; /* filter for event */ | | 190 | uint32_t filter; /* filter for event */ |
191 | uint32_t flags; /* action flags for kqueue */ | | 191 | uint32_t flags; /* action flags for kqueue */ |
192 | uint32_t fflags; /* filter flag value */ | | 192 | uint32_t fflags; /* filter flag value */ |
193 | int64_t data; /* filter data value */ | | 193 | int64_t data; /* filter data value */ |
194 | void *udata; /* opaque user data identifier */ | | 194 | void *udata; /* opaque user data identifier */ |
195 | }; | | 195 | }; |
196 | .Ed | | 196 | .Ed |
197 | .Pp | | 197 | .Pp |
198 | The fields of | | 198 | The fields of |
199 | .Fa struct kevent | | 199 | .Fa struct kevent |
200 | are: | | 200 | are: |
201 | .Bl -tag -width "Fa filter" -offset indent | | 201 | .Bl -tag -width "Fa filter" -offset indent |
202 | .It ident | | 202 | .It ident |
203 | Value used to identify this event. | | 203 | Value used to identify this event. |
204 | The exact interpretation is determined by the attached filter, | | 204 | The exact interpretation is determined by the attached filter, |
205 | but often is a file descriptor. | | 205 | but often is a file descriptor. |
206 | .It Fa filter | | 206 | .It Fa filter |
207 | Identifies the kernel filter used to process this event. | | 207 | Identifies the kernel filter used to process this event. |
208 | There are pre-defined system filters (which are described below), and | | 208 | There are pre-defined system filters (which are described below), and |
209 | other filters may be added by kernel subsystems as necessary. | | 209 | other filters may be added by kernel subsystems as necessary. |
210 | .It Fa flags | | 210 | .It Fa flags |
211 | Actions to perform on the event. | | 211 | Actions to perform on the event. |
212 | .It Fa fflags | | 212 | .It Fa fflags |
213 | Filter-specific flags. | | 213 | Filter-specific flags. |
214 | .It Fa data | | 214 | .It Fa data |
215 | Filter-specific data value. | | 215 | Filter-specific data value. |
216 | .It Fa udata | | 216 | .It Fa udata |
217 | Opaque user-defined value passed through the kernel unchanged. | | 217 | Opaque user-defined value passed through the kernel unchanged. |
218 | .El | | 218 | .El |
219 | .Pp | | 219 | .Pp |
220 | The | | 220 | The |
221 | .Va flags | | 221 | .Va flags |
222 | field can contain the following values: | | 222 | field can contain the following values: |
223 | .Bl -tag -width XXXEV_ONESHOT -offset indent | | 223 | .Bl -tag -width XXXEV_ONESHOT -offset indent |
224 | .It Dv EV_ADD | | 224 | .It Dv EV_ADD |
225 | Adds the event to the kqueue. | | 225 | Adds the event to the kqueue. |
226 | Re-adding an existing event will modify the parameters of the original | | 226 | Re-adding an existing event will modify the parameters of the original |
227 | event, and not result in a duplicate entry. | | 227 | event, and not result in a duplicate entry. |
228 | Adding an event automatically enables it, | | 228 | Adding an event automatically enables it, |
229 | unless overridden by the EV_DISABLE flag. | | 229 | unless overridden by the EV_DISABLE flag. |
230 | .It Dv EV_ENABLE | | 230 | .It Dv EV_ENABLE |
231 | Permit | | 231 | Permit |
232 | .Fn kevent | | 232 | .Fn kevent |
233 | to return the event if it is triggered. | | 233 | to return the event if it is triggered. |
234 | .It Dv EV_DISABLE | | 234 | .It Dv EV_DISABLE |
235 | Disable the event so | | 235 | Disable the event so |
236 | .Fn kevent | | 236 | .Fn kevent |
237 | will not return it. | | 237 | will not return it. |
238 | The filter itself is not disabled. | | 238 | The filter itself is not disabled. |
239 | .It Dv EV_DISPATCH | | 239 | .It Dv EV_DISPATCH |
240 | Disable the event source immediately after delivery of an event. | | 240 | Disable the event source immediately after delivery of an event. |
241 | See | | 241 | See |
242 | .Dv EV_DISABLE | | 242 | .Dv EV_DISABLE |
243 | above. | | 243 | above. |
244 | .It Dv EV_DELETE | | 244 | .It Dv EV_DELETE |
245 | Removes the event from the kqueue. | | 245 | Removes the event from the kqueue. |
246 | Events which are attached to file descriptors are automatically deleted | | 246 | Events which are attached to file descriptors are automatically deleted |
247 | on the last close of the descriptor. | | 247 | on the last close of the descriptor. |
248 | .It Dv EV_RECEIPT | | 248 | .It Dv EV_RECEIPT |
249 | This flag is useful for making bulk changes to a kqueue without draining | | 249 | This flag is useful for making bulk changes to a kqueue without draining |
250 | any pending events. | | 250 | any pending events. |
251 | When passed as input, it forces | | 251 | When passed as input, it forces |
252 | .Dv EV_ERROR | | 252 | .Dv EV_ERROR |
253 | to always be returned. | | 253 | to always be returned. |
254 | When a filter is successfully added the | | 254 | When a filter is successfully added the |
255 | .Va data | | 255 | .Va data |
256 | field will be zero. | | 256 | field will be zero. |
257 | Note that if this flag is encountered and there is no remaining space in | | 257 | Note that if this flag is encountered and there is no remaining space in |
258 | .Fa eventlist | | 258 | .Fa eventlist |
259 | to hold the | | 259 | to hold the |
260 | .Dv EV_ERROR | | 260 | .Dv EV_ERROR |
261 | event, then subsequent changes will not get processed. | | 261 | event, then subsequent changes will not get processed. |
262 | .It Dv EV_ONESHOT | | 262 | .It Dv EV_ONESHOT |
263 | Causes the event to return only the first occurrence of the filter | | 263 | Causes the event to return only the first occurrence of the filter |
264 | being triggered. | | 264 | being triggered. |
265 | After the user retrieves the event from the kqueue, it is deleted. | | 265 | After the user retrieves the event from the kqueue, it is deleted. |
266 | .It Dv EV_CLEAR | | 266 | .It Dv EV_CLEAR |
267 | After the event is retrieved by the user, its state is reset. | | 267 | After the event is retrieved by the user, its state is reset. |
268 | This is useful for filters which report state transitions | | 268 | This is useful for filters which report state transitions |
269 | instead of the current state. | | 269 | instead of the current state. |
270 | Note that some filters may automatically set this flag internally. | | 270 | Note that some filters may automatically set this flag internally. |
271 | .It Dv EV_EOF | | 271 | .It Dv EV_EOF |
272 | Filters may set this flag to indicate filter-specific EOF condition. | | 272 | Filters may set this flag to indicate filter-specific EOF condition. |
273 | .It Dv EV_ERROR | | 273 | .It Dv EV_ERROR |
274 | See | | 274 | See |
275 | .Sx RETURN VALUES | | 275 | .Sx RETURN VALUES |
276 | below. | | 276 | below. |
277 | .El | | 277 | .El |
278 | .Ss Filters | | 278 | .Ss Filters |
279 | Filters are identified by a number. | | 279 | Filters are identified by a number. |
280 | There are two types of filters; pre-defined filters which | | 280 | There are two types of filters; pre-defined filters which |
281 | are described below, and third-party filters that may be added with | | 281 | are described below, and third-party filters that may be added with |
282 | .Xr kfilter_register 9 | | 282 | .Xr kfilter_register 9 |
283 | by kernel sub-systems, third-party device drivers, or loadable | | 283 | by kernel sub-systems, third-party device drivers, or loadable |
284 | kernel modules. | | 284 | kernel modules. |
285 | .Pp | | 285 | .Pp |
286 | As a third-party filter is referenced by a well-known name instead | | 286 | As a third-party filter is referenced by a well-known name instead |
287 | of a statically assigned number, two | | 287 | of a statically assigned number, two |
288 | .Xr ioctl 2 Ns s | | 288 | .Xr ioctl 2 Ns s |
289 | are supported on the file descriptor returned by | | 289 | are supported on the file descriptor returned by |
290 | .Fn kqueue | | 290 | .Fn kqueue |
291 | to map a filter name to a filter number, and vice-versa (passing | | 291 | to map a filter name to a filter number, and vice-versa (passing |
292 | arguments in a structure described below): | | 292 | arguments in a structure described below): |
293 | .Bl -tag -width KFILTER_BYFILTER -offset indent | | 293 | .Bl -tag -width KFILTER_BYFILTER -offset indent |
294 | .It Dv KFILTER_BYFILTER | | 294 | .It Dv KFILTER_BYFILTER |
295 | Map | | 295 | Map |
296 | .Va filter | | 296 | .Va filter |
297 | to | | 297 | to |
298 | .Va name , | | 298 | .Va name , |
299 | which is of size | | 299 | which is of size |
300 | .Va len . | | 300 | .Va len . |
301 | .It Dv KFILTER_BYNAME | | 301 | .It Dv KFILTER_BYNAME |
302 | Map | | 302 | Map |
303 | .Va name | | 303 | .Va name |
304 | to | | 304 | to |
305 | .Va filter . | | 305 | .Va filter . |
306 | .Va len | | 306 | .Va len |
307 | is ignored. | | 307 | is ignored. |
308 | .El | | 308 | .El |
309 | .Pp | | 309 | .Pp |
310 | The following structure is used to pass arguments in and out of the | | 310 | The following structure is used to pass arguments in and out of the |
311 | .Xr ioctl 2 : | | 311 | .Xr ioctl 2 : |
312 | .Bd -literal -offset indent | | 312 | .Bd -literal -offset indent |
313 | struct kfilter_mapping { | | 313 | struct kfilter_mapping { |
314 | char *name; /* name to lookup or return */ | | 314 | char *name; /* name to lookup or return */ |
315 | size_t len; /* length of name */ | | 315 | size_t len; /* length of name */ |
316 | uint32_t filter; /* filter to lookup or return */ | | 316 | uint32_t filter; /* filter to lookup or return */ |
317 | }; | | 317 | }; |
318 | .Ed | | 318 | .Ed |
319 | .Pp | | 319 | .Pp |
320 | The predefined system filters are listed below. | | 320 | The predefined system filters are listed below. |
321 | Arguments may be passed to and from the filter via the | | 321 | Arguments may be passed to and from the filter via the |
322 | .Va fflags | | 322 | .Va fflags |
323 | and | | 323 | and |
324 | .Va data | | 324 | .Va data |
325 | fields in the kevent structure. | | 325 | fields in the kevent structure. |
326 | .Pp | | 326 | .Pp |
327 | The predefined system filters are: | | 327 | The predefined system filters are: |
328 | .Bl -tag -width EVFILT_SIGNAL | | 328 | .Bl -tag -width EVFILT_SIGNAL |
329 | .It Dv EVFILT_READ | | 329 | .It Dv EVFILT_READ |
330 | Takes a descriptor as the identifier, and returns whenever | | 330 | Takes a descriptor as the identifier, and returns whenever |
331 | there is data available to read. | | 331 | there is data available to read. |
332 | The behavior of the filter is slightly different depending | | 332 | The behavior of the filter is slightly different depending |
333 | on the descriptor type. | | 333 | on the descriptor type. |
334 | .Bl -tag -width 2n | | 334 | .Bl -tag -width 2n |
335 | .It Sockets | | 335 | .It Sockets |
336 | Sockets which have previously been passed to | | 336 | Sockets which have previously been passed to |
337 | .Xr listen 2 | | 337 | .Xr listen 2 |
338 | return when there is an incoming connection pending. | | 338 | return when there is an incoming connection pending. |
339 | .Va data | | 339 | .Va data |
340 | contains the size of the listen backlog (i.e., the number of | | 340 | contains the size of the listen backlog (i.e., the number of |
341 | connections ready to be accepted with | | 341 | connections ready to be accepted with |
342 | .Xr accept 2 . ) | | 342 | .Xr accept 2 . ) |
343 | .Pp | | 343 | .Pp |
344 | Other socket descriptors return when there is data to be read, | | 344 | Other socket descriptors return when there is data to be read, |
345 | subject to the | | 345 | subject to the |
346 | .Dv SO_RCVLOWAT | | 346 | .Dv SO_RCVLOWAT |
347 | value of the socket buffer. | | 347 | value of the socket buffer. |
348 | This may be overridden with a per-filter low water mark at the | | 348 | This may be overridden with a per-filter low water mark at the |
349 | time the filter is added by setting the | | 349 | time the filter is added by setting the |
350 | NOTE_LOWAT | | 350 | NOTE_LOWAT |
351 | flag in | | 351 | flag in |
352 | .Va fflags , | | 352 | .Va fflags , |
353 | and specifying the new low water mark in | | 353 | and specifying the new low water mark in |
354 | .Va data . | | 354 | .Va data . |
355 | On return, | | 355 | On return, |
356 | .Va data | | 356 | .Va data |
357 | contains the number of bytes in the socket buffer. | | 357 | contains the number of bytes in the socket buffer. |
358 | .Pp | | 358 | .Pp |
359 | If the read direction of the socket has shutdown, then the filter | | 359 | If the read direction of the socket has shutdown, then the filter |
360 | also sets EV_EOF in | | 360 | also sets EV_EOF in |
361 | .Va flags , | | 361 | .Va flags , |
362 | and returns the socket error (if any) in | | 362 | and returns the socket error (if any) in |
363 | .Va fflags . | | 363 | .Va fflags . |
364 | It is possible for EOF to be returned (indicating the connection is gone) | | 364 | It is possible for EOF to be returned (indicating the connection is gone) |
365 | while there is still data pending in the socket buffer. | | 365 | while there is still data pending in the socket buffer. |
366 | .It Vnodes | | 366 | .It Vnodes |
367 | Returns when the file pointer is not at the end of file. | | 367 | Returns when the file pointer is not at the end of file. |
368 | .Va data | | 368 | .Va data |
369 | contains the offset from current position to end of file, | | 369 | contains the offset from current position to end of file, |
370 | and may be negative. | | 370 | and may be negative. |
371 | .\" .Pp | | 371 | .\" .Pp |
372 | .\" This behavior is different from | | 372 | .\" This behavior is different from |
373 | .\" .Xr poll 2 , | | 373 | .\" .Xr poll 2 , |
374 | .\" where read events are triggered for regular files unconditionally. | | 374 | .\" where read events are triggered for regular files unconditionally. |
375 | .\" This event can be triggered unconditionally by setting the | | 375 | .\" This event can be triggered unconditionally by setting the |
376 | .\" .Dv NOTE_FILE_POLL | | 376 | .\" .Dv NOTE_FILE_POLL |
377 | .\" flag in | | 377 | .\" flag in |
378 | .\" .Va fflags . | | 378 | .\" .Va fflags . |
379 | .It "Fifos, Pipes" | | 379 | .It "Fifos, Pipes" |
380 | Returns when there is data to read; | | 380 | Returns when there is data to read; |
381 | .Va data | | 381 | .Va data |
382 | contains the number of bytes available. | | 382 | contains the number of bytes available. |
383 | .Pp | | 383 | .Pp |
384 | When the last writer disconnects, the filter will set EV_EOF in | | 384 | When the last writer disconnects, the filter will set EV_EOF in |
385 | .Va flags . | | 385 | .Va flags . |
386 | This may be cleared by passing in EV_CLEAR, at which point the | | 386 | This may be cleared by passing in EV_CLEAR, at which point the |
387 | filter will resume waiting for data to become available before | | 387 | filter will resume waiting for data to become available before |
388 | returning. | | 388 | returning. |
389 | .It "BPF devices" | | 389 | .It "BPF devices" |
390 | Returns when the BPF buffer is full, the BPF timeout has expired, or | | 390 | Returns when the BPF buffer is full, the BPF timeout has expired, or |
391 | when the BPF has | | 391 | when the BPF has |
392 | .Dq immediate mode | | 392 | .Dq immediate mode |
393 | enabled and there is any data to read; | | 393 | enabled and there is any data to read; |
394 | .Va data | | 394 | .Va data |
| | | 395 | contains the number of bytes available. |
395 | .El | | 396 | .El |
396 | .It Dv EVFILT_WRITE | | 397 | .It Dv EVFILT_WRITE |
397 | Takes a descriptor as the identifier, and returns whenever | | 398 | Takes a descriptor as the identifier, and returns whenever |
398 | it is possible to write to the descriptor. | | 399 | it is possible to write to the descriptor. |
399 | For sockets, pipes, fifos, and ttys, | | 400 | For sockets, pipes, fifos, and ttys, |
400 | .Va data | | 401 | .Va data |
401 | will contain the amount of space remaining in the write buffer. | | 402 | will contain the amount of space remaining in the write buffer. |
402 | The filter will set EV_EOF when the reader disconnects, and for | | 403 | The filter will set EV_EOF when the reader disconnects, and for |
403 | the fifo case, this may be cleared by use of EV_CLEAR. | | 404 | the fifo case, this may be cleared by use of EV_CLEAR. |
404 | Note that this filter is not supported for vnodes. | | 405 | Note that this filter is not supported for vnodes. |
405 | .Pp | | 406 | .Pp |
406 | For sockets, the low water mark and socket error handling is | | 407 | For sockets, the low water mark and socket error handling is |
407 | identical to the EVFILT_READ case. | | 408 | identical to the EVFILT_READ case. |
408 | .It Dv EVFILT_AIO | | 409 | .It Dv EVFILT_AIO |
409 | This is not implemented in | | 410 | This is not implemented in |
410 | .Nx . | | 411 | .Nx . |
411 | .ig | | 412 | .ig |
412 | The sigevent portion of the AIO request is filled in, with | | 413 | The sigevent portion of the AIO request is filled in, with |
413 | .Va sigev_notify_kqueue | | 414 | .Va sigev_notify_kqueue |
414 | containing the descriptor of the kqueue that the event should | | 415 | containing the descriptor of the kqueue that the event should |
415 | be attached to, | | 416 | be attached to, |
416 | .Va sigev_value | | 417 | .Va sigev_value |
417 | containing the udata value, and | | 418 | containing the udata value, and |
418 | .Va sigev_notify | | 419 | .Va sigev_notify |
419 | set to SIGEV_EVENT. | | 420 | set to SIGEV_EVENT. |
420 | When the aio_* function is called, the event will be registered | | 421 | When the aio_* function is called, the event will be registered |
421 | with the specified kqueue, and the | | 422 | with the specified kqueue, and the |
422 | .Va ident | | 423 | .Va ident |
423 | argument set to the | | 424 | argument set to the |
424 | .Fa struct aiocb | | 425 | .Fa struct aiocb |
425 | returned by the aio_* function. | | 426 | returned by the aio_* function. |
426 | The filter returns under the same conditions as aio_error. | | 427 | The filter returns under the same conditions as aio_error. |
427 | .Pp | | 428 | .Pp |
428 | Alternatively, a kevent structure may be initialized, with | | 429 | Alternatively, a kevent structure may be initialized, with |
429 | .Va ident | | 430 | .Va ident |
430 | containing the descriptor of the kqueue, and the | | 431 | containing the descriptor of the kqueue, and the |
431 | address of the kevent structure placed in the | | 432 | address of the kevent structure placed in the |
432 | .Va aio_lio_opcode | | 433 | .Va aio_lio_opcode |
433 | field of the AIO request. | | 434 | field of the AIO request. |
434 | However, this approach will not work on | | 435 | However, this approach will not work on |
435 | architectures with 64-bit pointers, and should be considered deprecated. | | 436 | architectures with 64-bit pointers, and should be considered deprecated. |
436 | .. | | 437 | .. |
437 | .It Dv EVFILT_VNODE | | 438 | .It Dv EVFILT_VNODE |
438 | Takes a file descriptor as the identifier and the events to watch for in | | 439 | Takes a file descriptor as the identifier and the events to watch for in |
439 | .Va fflags , | | 440 | .Va fflags , |
440 | and returns when one or more of the requested events occurs on the descriptor. | | 441 | and returns when one or more of the requested events occurs on the descriptor. |
441 | The events to monitor are: | | 442 | The events to monitor are: |
442 | .Bl -tag -width XXNOTE_RENAME | | 443 | .Bl -tag -width XXNOTE_RENAME |
443 | .It Dv NOTE_DELETE | | 444 | .It Dv NOTE_DELETE |
444 | .Xr unlink 2 | | 445 | .Xr unlink 2 |
445 | was called on the file referenced by the descriptor. | | 446 | was called on the file referenced by the descriptor. |
446 | .It Dv NOTE_WRITE | | 447 | .It Dv NOTE_WRITE |
447 | A write occurred on the file referenced by the descriptor. | | 448 | A write occurred on the file referenced by the descriptor. |
448 | .It Dv NOTE_EXTEND | | 449 | .It Dv NOTE_EXTEND |
449 | The file referenced by the descriptor was extended. | | 450 | The file referenced by the descriptor was extended. |
450 | .It Dv NOTE_ATTRIB | | 451 | .It Dv NOTE_ATTRIB |
451 | The file referenced by the descriptor had its attributes changed. | | 452 | The file referenced by the descriptor had its attributes changed. |
452 | .It Dv NOTE_LINK | | 453 | .It Dv NOTE_LINK |
453 | The link count on the file changed. | | 454 | The link count on the file changed. |
454 | .It Dv NOTE_RENAME | | 455 | .It Dv NOTE_RENAME |
455 | The file referenced by the descriptor was renamed. | | 456 | The file referenced by the descriptor was renamed. |
456 | .It Dv NOTE_REVOKE | | 457 | .It Dv NOTE_REVOKE |
457 | Access to the file was revoked via | | 458 | Access to the file was revoked via |
458 | .Xr revoke 2 | | 459 | .Xr revoke 2 |
459 | or the underlying file system was unmounted. | | 460 | or the underlying file system was unmounted. |
460 | .El | | 461 | .El |
461 | .Pp | | 462 | .Pp |
462 | On return, | | 463 | On return, |
463 | .Va fflags | | 464 | .Va fflags |
464 | contains the events which triggered the filter. | | 465 | contains the events which triggered the filter. |
465 | .It Dv EVFILT_PROC | | 466 | .It Dv EVFILT_PROC |
466 | Takes the process ID to monitor as the identifier and the events to watch for | | 467 | Takes the process ID to monitor as the identifier and the events to watch for |
467 | in | | 468 | in |
468 | .Va fflags , | | 469 | .Va fflags , |
469 | and returns when the process performs one or more of the requested events. | | 470 | and returns when the process performs one or more of the requested events. |
470 | If a process can normally see another process, it can attach an event to it. | | 471 | If a process can normally see another process, it can attach an event to it. |
471 | The events to monitor are: | | 472 | The events to monitor are: |
472 | .Bl -tag -width XXNOTE_TRACKERR | | 473 | .Bl -tag -width XXNOTE_TRACKERR |
473 | .It Dv NOTE_EXIT | | 474 | .It Dv NOTE_EXIT |
474 | The process has exited. | | 475 | The process has exited. |
475 | The exit code of the process is stored in | | 476 | The exit code of the process is stored in |
476 | .Va data . | | 477 | .Va data . |
477 | .It Dv NOTE_FORK | | 478 | .It Dv NOTE_FORK |
478 | The process has called | | 479 | The process has called |
479 | .Xr fork 2 . | | 480 | .Xr fork 2 . |
480 | .It Dv NOTE_EXEC | | 481 | .It Dv NOTE_EXEC |
481 | The process has executed a new process via | | 482 | The process has executed a new process via |
482 | .Xr execve 2 | | 483 | .Xr execve 2 |
483 | or similar call. | | 484 | or similar call. |
484 | .It Dv NOTE_TRACK | | 485 | .It Dv NOTE_TRACK |
485 | Follow a process across | | 486 | Follow a process across |
486 | .Xr fork 2 | | 487 | .Xr fork 2 |
487 | calls. | | 488 | calls. |
488 | The parent process will return with NOTE_TRACK set in the | | 489 | The parent process will return with NOTE_TRACK set in the |
489 | .Va fflags | | 490 | .Va fflags |
490 | field, while the child process will return with NOTE_CHILD set in | | 491 | field, while the child process will return with NOTE_CHILD set in |
491 | .Va fflags | | 492 | .Va fflags |
492 | and the parent PID in | | 493 | and the parent PID in |
493 | .Va data . | | 494 | .Va data . |
494 | .It Dv NOTE_TRACKERR | | 495 | .It Dv NOTE_TRACKERR |
495 | This flag is returned if the system was unable to attach an event to | | 496 | This flag is returned if the system was unable to attach an event to |
496 | the child process, usually due to resource limitations. | | 497 | the child process, usually due to resource limitations. |
497 | .El | | 498 | .El |
498 | .Pp | | 499 | .Pp |
499 | On return, | | 500 | On return, |
500 | .Va fflags | | 501 | .Va fflags |
501 | contains the events which triggered the filter. | | 502 | contains the events which triggered the filter. |
502 | .It Dv EVFILT_SIGNAL | | 503 | .It Dv EVFILT_SIGNAL |
503 | Takes the signal number to monitor as the identifier and returns | | 504 | Takes the signal number to monitor as the identifier and returns |
504 | when the given signal is delivered to the current process. | | 505 | when the given signal is delivered to the current process. |
505 | This coexists with the | | 506 | This coexists with the |
506 | .Xr signal 3 | | 507 | .Xr signal 3 |
507 | and | | 508 | and |
508 | .Xr sigaction 2 | | 509 | .Xr sigaction 2 |
509 | facilities, and has a lower precedence. | | 510 | facilities, and has a lower precedence. |
510 | The filter will record | | 511 | The filter will record |
511 | all attempts to deliver a signal to a process, even if the signal has | | 512 | all attempts to deliver a signal to a process, even if the signal has |
512 | been marked as SIG_IGN. | | 513 | been marked as SIG_IGN. |
513 | Event notification happens after normal signal delivery processing. | | 514 | Event notification happens after normal signal delivery processing. |
514 | .Va data | | 515 | .Va data |
515 | returns the number of times the signal has occurred since the last call to | | 516 | returns the number of times the signal has occurred since the last call to |
516 | .Fn kevent . | | 517 | .Fn kevent . |
517 | This filter automatically sets the EV_CLEAR flag internally. | | 518 | This filter automatically sets the EV_CLEAR flag internally. |
518 | .It Dv EVFILT_TIMER | | 519 | .It Dv EVFILT_TIMER |
519 | Establishes an arbitrary timer identified by | | 520 | Establishes an arbitrary timer identified by |
520 | .Va ident . | | 521 | .Va ident . |
521 | When adding a timer, | | 522 | When adding a timer, |
522 | .Va data | | 523 | .Va data |
523 | specifies the timeout period in milliseconds. | | 524 | specifies the timeout period in milliseconds. |
524 | The timer will be periodic unless EV_ONESHOT is specified. | | 525 | The timer will be periodic unless EV_ONESHOT is specified. |
525 | On return, | | 526 | On return, |
526 | .Va data | | 527 | .Va data |
527 | contains the number of times the timeout has expired since the last call to | | 528 | contains the number of times the timeout has expired since the last call to |
528 | .Fn kevent . | | 529 | .Fn kevent . |
529 | This filter automatically sets the EV_CLEAR flag internally. | | 530 | This filter automatically sets the EV_CLEAR flag internally. |
530 | .It Dv EVFILT_FS | | 531 | .It Dv EVFILT_FS |
531 | Establishes a file system monitor. | | 532 | Establishes a file system monitor. |
532 | Currently it only monitors file system mount and unmount actions. | | 533 | Currently it only monitors file system mount and unmount actions. |
533 | .It Dv EVFILT_USER | | 534 | .It Dv EVFILT_USER |
534 | Establishes a user event identified by | | 535 | Establishes a user event identified by |
535 | .Va ident | | 536 | .Va ident |
536 | which is not associated with any kernel mechanism but is triggered by | | 537 | which is not associated with any kernel mechanism but is triggered by |
537 | user level code. | | 538 | user level code. |
538 | The lower 24 bits of the | | 539 | The lower 24 bits of the |
539 | .Va fflags | | 540 | .Va fflags |
540 | may be used for user defined flags and manipulated using the following: | | 541 | may be used for user defined flags and manipulated using the following: |
541 | .Bl -tag -width "Dv NOTE_FFLAGSMASK" | | 542 | .Bl -tag -width "Dv NOTE_FFLAGSMASK" |
542 | .It Dv NOTE_FFNOP | | 543 | .It Dv NOTE_FFNOP |
543 | Ignore the input | | 544 | Ignore the input |
544 | .Va fflags . | | 545 | .Va fflags . |
545 | .It Dv NOTE_FFAND | | 546 | .It Dv NOTE_FFAND |
546 | Bitwise AND | | 547 | Bitwise AND |
547 | .Va fflags . | | 548 | .Va fflags . |
548 | .It Dv NOTE_FFOR | | 549 | .It Dv NOTE_FFOR |
549 | Bitwise OR | | 550 | Bitwise OR |
550 | .Va fflags . | | 551 | .Va fflags . |
551 | .It Dv NOTE_FFCOPY | | 552 | .It Dv NOTE_FFCOPY |
552 | Copy | | 553 | Copy |
553 | .Va fflags . | | 554 | .Va fflags . |
554 | .It Dv NOTE_FFCTRLMASK | | 555 | .It Dv NOTE_FFCTRLMASK |
555 | Control mask for | | 556 | Control mask for |
556 | .Va fflags . | | 557 | .Va fflags . |
557 | .It Dv NOTE_FFLAGSMASK | | 558 | .It Dv NOTE_FFLAGSMASK |
558 | User defined flag mask for | | 559 | User defined flag mask for |
559 | .Va fflags . | | 560 | .Va fflags . |
560 | .El | | 561 | .El |
561 | .Pp | | 562 | .Pp |
562 | A user event is triggered for output with the following: | | 563 | A user event is triggered for output with the following: |
563 | .Bl -tag -width "Dv NOTE_FFLAGSMASK" | | 564 | .Bl -tag -width "Dv NOTE_FFLAGSMASK" |
564 | .It Dv NOTE_TRIGGER | | 565 | .It Dv NOTE_TRIGGER |
565 | Cause the event to be triggered. | | 566 | Cause the event to be triggered. |
566 | .El | | 567 | .El |
567 | .Pp | | 568 | .Pp |
568 | On return, | | 569 | On return, |
569 | .Va fflags | | 570 | .Va fflags |
570 | contains the users defined flags in the lower 24 bits. | | 571 | contains the users defined flags in the lower 24 bits. |
571 | .El | | 572 | .El |
572 | .Sh CANCELLATION BEHAVIOUR | | 573 | .Sh CANCELLATION BEHAVIOUR |
573 | If | | 574 | If |
574 | .Fa nevents | | 575 | .Fa nevents |
575 | is non-zero, i.e., the function is potentially blocking, the call | | 576 | is non-zero, i.e., the function is potentially blocking, the call |
576 | is a cancellation point. | | 577 | is a cancellation point. |
577 | Otherwise, i.e., if | | 578 | Otherwise, i.e., if |
578 | .Fa nevents | | 579 | .Fa nevents |
579 | is zero, the call is not cancellable. | | 580 | is zero, the call is not cancellable. |
580 | Cancellation can only occur before any changes are made to the kqueue, | | 581 | Cancellation can only occur before any changes are made to the kqueue, |
581 | or when the call was blocked and no changes to the queue were requested. | | 582 | or when the call was blocked and no changes to the queue were requested. |
582 | .Sh RETURN VALUES | | 583 | .Sh RETURN VALUES |
583 | The | | 584 | The |
584 | .Fn kqueue | | 585 | .Fn kqueue |
585 | system call | | 586 | system call |
586 | creates a new kernel event queue and returns a file descriptor. | | 587 | creates a new kernel event queue and returns a file descriptor. |
587 | If there was an error creating the kernel event queue, a value of \-1 is | | 588 | If there was an error creating the kernel event queue, a value of \-1 is |
588 | returned and | | 589 | returned and |
589 | .Dv errno | | 590 | .Dv errno |
590 | is set. | | 591 | is set. |
591 | .Pp | | 592 | .Pp |
592 | The | | 593 | The |
593 | .Fn kevent | | 594 | .Fn kevent |
594 | system call | | 595 | system call |
595 | returns the number of events placed in the | | 596 | returns the number of events placed in the |
596 | .Fa eventlist , | | 597 | .Fa eventlist , |
597 | up to the value given by | | 598 | up to the value given by |
598 | .Fa nevents . | | 599 | .Fa nevents . |
599 | If an error occurs while processing an element of the | | 600 | If an error occurs while processing an element of the |
600 | .Fa changelist | | 601 | .Fa changelist |
601 | and there is enough room in the | | 602 | and there is enough room in the |
602 | .Fa eventlist , | | 603 | .Fa eventlist , |
603 | then the event will be placed in the | | 604 | then the event will be placed in the |
604 | .Fa eventlist | | 605 | .Fa eventlist |
605 | with | | 606 | with |
606 | .Dv EV_ERROR | | 607 | .Dv EV_ERROR |
607 | set in | | 608 | set in |
608 | .Va flags | | 609 | .Va flags |
609 | and the system error in | | 610 | and the system error in |
610 | .Va data . | | 611 | .Va data . |
611 | Otherwise, | | 612 | Otherwise, |
612 | .Dv \-1 | | 613 | .Dv \-1 |
613 | will be returned, and | | 614 | will be returned, and |
614 | .Dv errno | | 615 | .Dv errno |
615 | will be set to indicate the error condition. | | 616 | will be set to indicate the error condition. |
616 | If the time limit expires, then | | 617 | If the time limit expires, then |
617 | .Fn kevent | | 618 | .Fn kevent |
618 | returns 0. | | 619 | returns 0. |
619 | .Sh EXAMPLES | | 620 | .Sh EXAMPLES |
620 | The following example program monitors a file (provided to it as the first | | 621 | The following example program monitors a file (provided to it as the first |
621 | argument) and prints information about some common events it receives | | 622 | argument) and prints information about some common events it receives |
622 | notifications for: | | 623 | notifications for: |
623 | .Bd -literal -offset indent | | 624 | .Bd -literal -offset indent |
624 | #include <sys/types.h> | | 625 | #include <sys/types.h> |
625 | #include <sys/event.h> | | 626 | #include <sys/event.h> |
626 | #include <sys/time.h> | | 627 | #include <sys/time.h> |
627 | #include <stdio.h> | | 628 | #include <stdio.h> |
628 | #include <unistd.h> | | 629 | #include <unistd.h> |
629 | #include <stdlib.h> | | 630 | #include <stdlib.h> |
630 | #include <fcntl.h> | | 631 | #include <fcntl.h> |
631 | #include <err.h> | | 632 | #include <err.h> |
632 | | | 633 | |
633 | int | | 634 | int |
634 | main(int argc, char *argv[]) | | 635 | main(int argc, char *argv[]) |
635 | { | | 636 | { |
636 | int fd, kq, nev; | | 637 | int fd, kq, nev; |
637 | struct kevent ev; | | 638 | struct kevent ev; |
638 | static const struct timespec tout = { 1, 0 }; | | 639 | static const struct timespec tout = { 1, 0 }; |
639 | | | 640 | |
640 | if ((fd = open(argv[1], O_RDONLY)) == -1) | | 641 | if ((fd = open(argv[1], O_RDONLY)) == -1) |
641 | err(1, "Cannot open `%s'", argv[1]); | | 642 | err(1, "Cannot open `%s'", argv[1]); |
642 | | | 643 | |
643 | if ((kq = kqueue()) == -1) | | 644 | if ((kq = kqueue()) == -1) |
644 | err(1, "Cannot create kqueue"); | | 645 | err(1, "Cannot create kqueue"); |
645 | | | 646 | |
646 | EV_SET(&ev, fd, EVFILT_VNODE, EV_ADD | EV_ENABLE | EV_CLEAR, | | 647 | EV_SET(&ev, fd, EVFILT_VNODE, EV_ADD | EV_ENABLE | EV_CLEAR, |
647 | NOTE_DELETE|NOTE_WRITE|NOTE_EXTEND|NOTE_ATTRIB|NOTE_LINK| | | 648 | NOTE_DELETE|NOTE_WRITE|NOTE_EXTEND|NOTE_ATTRIB|NOTE_LINK| |
648 | NOTE_RENAME|NOTE_REVOKE, 0, 0); | | 649 | NOTE_RENAME|NOTE_REVOKE, 0, 0); |
649 | if (kevent(kq, &ev, 1, NULL, 0, &tout) == -1) | | 650 | if (kevent(kq, &ev, 1, NULL, 0, &tout) == -1) |
650 | err(1, "kevent"); | | 651 | err(1, "kevent"); |
651 | for (;;) { | | 652 | for (;;) { |
652 | nev = kevent(kq, NULL, 0, &ev, 1, &tout); | | 653 | nev = kevent(kq, NULL, 0, &ev, 1, &tout); |
653 | if (nev == -1) | | 654 | if (nev == -1) |
654 | err(1, "kevent"); | | 655 | err(1, "kevent"); |
655 | if (nev == 0) | | 656 | if (nev == 0) |
656 | continue; | | 657 | continue; |
657 | if (ev.fflags & NOTE_DELETE) { | | 658 | if (ev.fflags & NOTE_DELETE) { |
658 | printf("deleted "); | | 659 | printf("deleted "); |
659 | ev.fflags &= ~NOTE_DELETE; | | 660 | ev.fflags &= ~NOTE_DELETE; |
660 | } | | 661 | } |
661 | if (ev.fflags & NOTE_WRITE) { | | 662 | if (ev.fflags & NOTE_WRITE) { |
662 | printf("written "); | | 663 | printf("written "); |
663 | ev.fflags &= ~NOTE_WRITE; | | 664 | ev.fflags &= ~NOTE_WRITE; |
664 | } | | 665 | } |
665 | if (ev.fflags & NOTE_EXTEND) { | | 666 | if (ev.fflags & NOTE_EXTEND) { |
666 | printf("extended "); | | 667 | printf("extended "); |
667 | ev.fflags &= ~NOTE_EXTEND; | | 668 | ev.fflags &= ~NOTE_EXTEND; |
668 | } | | 669 | } |
669 | if (ev.fflags & NOTE_ATTRIB) { | | 670 | if (ev.fflags & NOTE_ATTRIB) { |
670 | printf("chmod/chown/utimes "); | | 671 | printf("chmod/chown/utimes "); |
671 | ev.fflags &= ~NOTE_ATTRIB; | | 672 | ev.fflags &= ~NOTE_ATTRIB; |
672 | } | | 673 | } |
673 | if (ev.fflags & NOTE_LINK) { | | 674 | if (ev.fflags & NOTE_LINK) { |
674 | printf("hardlinked "); | | 675 | printf("hardlinked "); |
675 | ev.fflags &= ~NOTE_LINK; | | 676 | ev.fflags &= ~NOTE_LINK; |
676 | } | | 677 | } |
677 | if (ev.fflags & NOTE_RENAME) { | | 678 | if (ev.fflags & NOTE_RENAME) { |
678 | printf("renamed "); | | 679 | printf("renamed "); |
679 | ev.fflags &= ~NOTE_RENAME; | | 680 | ev.fflags &= ~NOTE_RENAME; |
680 | } | | 681 | } |
681 | if (ev.fflags & NOTE_REVOKE) { | | 682 | if (ev.fflags & NOTE_REVOKE) { |
682 | printf("revoked "); | | 683 | printf("revoked "); |
683 | ev.fflags &= ~NOTE_REVOKE; | | 684 | ev.fflags &= ~NOTE_REVOKE; |
684 | } | | 685 | } |
685 | printf("\\n"); | | 686 | printf("\\n"); |
686 | if (ev.fflags) | | 687 | if (ev.fflags) |
687 | warnx("unknown event 0x%x\\n", ev.fflags); | | 688 | warnx("unknown event 0x%x\\n", ev.fflags); |
688 | } | | 689 | } |
689 | } | | 690 | } |
690 | .Ed | | 691 | .Ed |
691 | .Sh ERRORS | | 692 | .Sh ERRORS |
692 | The | | 693 | The |
693 | .Fn kqueue | | 694 | .Fn kqueue |
694 | function fails if: | | 695 | function fails if: |
695 | .Bl -tag -width Er | | 696 | .Bl -tag -width Er |
696 | .It Bq Er EMFILE | | 697 | .It Bq Er EMFILE |
697 | The per-process descriptor table is full. | | 698 | The per-process descriptor table is full. |
698 | .It Bq Er ENFILE | | 699 | .It Bq Er ENFILE |
699 | The system file table is full. | | 700 | The system file table is full. |
700 | .It Bq Er ENOMEM | | 701 | .It Bq Er ENOMEM |
701 | The kernel failed to allocate enough memory for the kernel queue. | | 702 | The kernel failed to allocate enough memory for the kernel queue. |
702 | .El | | 703 | .El |
703 | .Pp | | 704 | .Pp |
704 | The | | 705 | The |
705 | .Fn kevent | | 706 | .Fn kevent |
706 | function fails if: | | 707 | function fails if: |
707 | .Bl -tag -width Er | | 708 | .Bl -tag -width Er |
708 | .It Bq Er EACCES | | 709 | .It Bq Er EACCES |
709 | The process does not have permission to register a filter. | | 710 | The process does not have permission to register a filter. |
710 | .It Bq Er EBADF | | 711 | .It Bq Er EBADF |
711 | The specified descriptor is invalid. | | 712 | The specified descriptor is invalid. |
712 | .It Bq Er EFAULT | | 713 | .It Bq Er EFAULT |
713 | There was an error reading or writing the | | 714 | There was an error reading or writing the |
714 | .Va kevent | | 715 | .Va kevent |
715 | structure. | | 716 | structure. |
716 | .It Bq Er EINTR | | 717 | .It Bq Er EINTR |
717 | A signal was delivered before the timeout expired and before any | | 718 | A signal was delivered before the timeout expired and before any |
718 | events were placed on the kqueue for return. | | 719 | events were placed on the kqueue for return. |
719 | All changes contained in the | | 720 | All changes contained in the |
720 | .Fa changelist | | 721 | .Fa changelist |
721 | are applied before returning this error. | | 722 | are applied before returning this error. |
722 | .It Bq Er EINVAL | | 723 | .It Bq Er EINVAL |
723 | The specified time limit or filter is invalid. | | 724 | The specified time limit or filter is invalid. |
724 | .It Bq Er ENOENT | | 725 | .It Bq Er ENOENT |
725 | The event could not be found to be modified or deleted. | | 726 | The event could not be found to be modified or deleted. |
726 | .It Bq Er ENOMEM | | 727 | .It Bq Er ENOMEM |
727 | No memory was available to register the event. | | 728 | No memory was available to register the event. |
728 | .It Bq Er EOPNOTSUPP | | 729 | .It Bq Er EOPNOTSUPP |
729 | This type of file descriptor is not supported for | | 730 | This type of file descriptor is not supported for |
730 | .Fn kevent | | 731 | .Fn kevent |
731 | operations. | | 732 | operations. |
732 | .It Bq Er ESRCH | | 733 | .It Bq Er ESRCH |
733 | The specified process to attach to does not exist. | | 734 | The specified process to attach to does not exist. |
734 | .El | | 735 | .El |
735 | .Sh SEE ALSO | | 736 | .Sh SEE ALSO |
736 | .\" .Xr aio_error 2 , | | 737 | .\" .Xr aio_error 2 , |
737 | .\" .Xr aio_read 2 , | | 738 | .\" .Xr aio_read 2 , |
738 | .\" .Xr aio_return 2 , | | 739 | .\" .Xr aio_return 2 , |
739 | .Xr fork 2 , | | 740 | .Xr fork 2 , |
740 | .Xr ioctl 2 , | | 741 | .Xr ioctl 2 , |
741 | .Xr listen 2 , | | 742 | .Xr listen 2 , |
742 | .Xr poll 2 , | | 743 | .Xr poll 2 , |
743 | .Xr read 2 , | | 744 | .Xr read 2 , |
744 | .Xr select 2 , | | 745 | .Xr select 2 , |
745 | .Xr sigaction 2 , | | 746 | .Xr sigaction 2 , |
746 | .Xr unlink 2 , | | 747 | .Xr unlink 2 , |
747 | .Xr write 2 , | | 748 | .Xr write 2 , |
748 | .Xr signal 3 , | | 749 | .Xr signal 3 , |
749 | .Xr timespec 3 , | | 750 | .Xr timespec 3 , |
750 | .Xr kfilter_register 9 , | | 751 | .Xr kfilter_register 9 , |
751 | .Xr knote 9 | | 752 | .Xr knote 9 |
752 | .Rs | | 753 | .Rs |
753 | .%A Jonathan Lemon | | 754 | .%A Jonathan Lemon |
754 | .%T "Kqueue: A Generic and Scalable Event Notification Facility" | | 755 | .%T "Kqueue: A Generic and Scalable Event Notification Facility" |
755 | .%I USENIX Association | | 756 | .%I USENIX Association |
756 | .%B Proceedings of the FREENIX Track: 2001 USENIX Annual Technical Conference | | 757 | .%B Proceedings of the FREENIX Track: 2001 USENIX Annual Technical Conference |
757 | .%D June 25-30, 2001 | | 758 | .%D June 25-30, 2001 |
758 | .%U http://www.usenix.org/event/usenix01/freenix01/full_papers/lemon/lemon.pdf | | 759 | .%U http://www.usenix.org/event/usenix01/freenix01/full_papers/lemon/lemon.pdf |
759 | .Re | | 760 | .Re |
760 | .Sh HISTORY | | 761 | .Sh HISTORY |
761 | The | | 762 | The |
762 | .Fn kqueue | | 763 | .Fn kqueue |
763 | and | | 764 | and |
764 | .Fn kevent | | 765 | .Fn kevent |
765 | functions first appeared in | | 766 | functions first appeared in |
766 | .Fx 4.1 , | | 767 | .Fx 4.1 , |
767 | and then in | | 768 | and then in |
768 | .Nx 2.0 . | | 769 | .Nx 2.0 . |
769 | The | | 770 | The |
770 | .Fn kqueue1 | | 771 | .Fn kqueue1 |
771 | function first appeared in | | 772 | function first appeared in |
772 | .Nx 6.0 . | | 773 | .Nx 6.0 . |
773 | .Pp | | 774 | .Pp |
774 | The | | 775 | The |
775 | .Fn EV_SET | | 776 | .Fn EV_SET |
776 | macro was protected from evaluating multiple times the first argument in | | 777 | macro was protected from evaluating multiple times the first argument in |
777 | .Nx 8.0 . | | 778 | .Nx 8.0 . |
778 | .Pp | | 779 | .Pp |
779 | The | | 780 | The |
780 | .Va udata | | 781 | .Va udata |
781 | type was changed from intptr_t to void * in | | 782 | type was changed from intptr_t to void * in |
782 | .Nx 10.0 . | | 783 | .Nx 10.0 . |