1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
|
.\" Copyright 2006,2011 John-Mark Gurney
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd March 26, 2012
.Dt KQUEUE 9
.Os
.Sh NAME
.Nm kqueue_add_filteropts , kqueue_del_filteropts ,
.Nm kqfd_register ,
.Nm knote_fdclose ,
.Nm knlist_init , knlist_init_mtx , knlist_init_rw_reader ,
.Nm knlist_add , knlist_remove , knlist_remove_inevent , knlist_empty ,
.Nm knlist_clear , knlist_delete , knlist_destroy ,
.Nm KNOTE_LOCKED , KNOTE_UNLOCKED
.Nd "event delivery subsystem"
.Sh SYNOPSIS
.In sys/event.h
.Ft int
.Fn kqueue_add_filteropts "int filt" "struct filterops *filtops"
.Ft int
.Fn kqueue_del_filteropts "int filt"
.Ft int
.Fn kqfd_register "int fd" "struct kevent *kev" "struct thread *td" "int waitok"
.Ft void
.Fn knote_fdclose "struct thread *td" "int fd"
.Ft void
.Fo knlist_init
.Fa "struct knlist *knl"
.Fa "void *lock"
.Fa "void \*[lp]*kl_lock\*[rp]\*[lp]void *\*[rp]"
.Fa "void \*[lp]*kl_unlock\*[rp]\*[lp]void *\*[rp]"
.Fa "int \*[lp]*kl_locked\*[rp]\*[lp]void *\*[rp]"
.Fc
.Ft void
.Fn knlist_init_mtx "struct knlist *knl" "struct mtx *lock"
.Ft void
.Fn knlist_init_rw_reader "struct knlist *knl" "struct rwlock *lock"
.Ft void
.Fn knlist_add "struct knlist *knl" "struct knote *kn" "int islocked"
.Ft void
.Fn knlist_remove "struct knlist *knl" "struct knote *kn" "int islocked"
.Ft void
.Fn knlist_remove_inevent "struct knlist *knl" "struct knote *kn"
.Ft int
.Fn knlist_empty "struct knlist *knl"
.Ft void
.Fn knlist_clear "struct knlist *knl" "int islocked"
.Ft void
.Fn knlist_delete "struct knlist *knl" "struct thread *td" "int islocked"
.Ft void
.Fn knlist_destroy "struct knlist *knl"
.Ft void
.Fn KNOTE_LOCKED "struct knlist *knl" "long hint"
.Ft void
.Fn KNOTE_UNLOCKED "struct knlist *knl" "long hint"
.Sh DESCRIPTION
The functions
.Fn kqueue_add_filteropts
and
.Fn kqueue_del_filteropts
allow for the addition and removal of a filter type.
The filter is statically defined by the
.Dv EVFILT_*
macros.
The function
.Fn kqueue_add_filteropts
will make
.Fa filt
available.
The
.Vt "struct filterops"
has the following members:
.Bl -tag -width ".Va f_attach"
.It Va f_isfd
If
.Va f_isfd
is set,
.Va ident
in
.Vt "struct kevent"
is taken to be a file descriptor.
In this case, the
.Vt knote
passed into
.Va f_attach
will have the
.Va kn_fp
member initialized to the
.Vt "struct file *"
that represents the file descriptor.
.It Va f_attach
The
.Va f_attach
function will be called when attaching a
.Vt knote
to the object.
The method should call
.Fn knlist_add
to add the
.Vt knote
to the list that was initialized with
.Fn knlist_init .
The call to
.Fn knlist_add
is only necessary if the object can have multiple
.Vt knotes
associated with it.
If there is no
.Vt knlist
to call
.Fn knlist_add
with, the function
.Va f_attach
must clear the
.Dv KN_DETACHED
bit of
.Va kn_status
in the
.Vt knote .
The function shall return 0 on success, or appropriate error for the failure,
such as when the object is being destroyed, or does not exist.
During
.Va f_attach ,
it is valid to change the
.Va kn_fops
pointer to a different pointer.
This will change the
.Va f_event
and
.Va f_detach
functions called when processing the
.Vt knote .
.It Va f_detach
The
.Va f_detach
function will be called to detach the
.Vt knote
if the
.Vt knote
has not already been detached by a call to
.Fn knlist_remove ,
.Fn knlist_remove_inevent
or
.Fn knlist_delete .
The list
.Fa lock
will not be held when this function is called.
.It Va f_event
The
.Va f_event
function will be called to update the status of the
.Vt knote .
If the function returns 0, it will be assumed that the object is not
ready (or no longer ready) to be woken up.
The
.Fa hint
argument will be 0 when scanning
.Vt knotes
to see which are triggered.
Otherwise, the
.Fa hint
argument will be the value passed to either
.Dv KNOTE_LOCKED
or
.Dv KNOTE_UNLOCKED .
The
.Va kn_data
value should be updated as necessary to reflect the current value, such as
number of bytes available for reading, or buffer space available for writing.
If the note needs to be removed,
.Fn knlist_remove_inevent
must be called.
The function
.Fn knlist_remove_inevent
will remove the note from the list, the
.Va f_detach
function will not be called and the
.Vt knote
will not be returned as an event.
.Pp
Locks
.Em must not
be acquired in
.Va f_event .
If a lock is required in
.Va f_event ,
it must be obtained in the
.Fa kl_lock
function of the
.Vt knlist
that the
.Va knote
was added to.
.El
.Pp
The function
.Fn kqfd_register
will register the
.Vt kevent
on the kqueue file descriptor
.Fa fd .
If it is safe to sleep,
.Fa waitok
should be set.
.Pp
The function
.Fn knote_fdclose
is used to delete all
.Vt knotes
associated with
.Fa fd .
Once returned, there will no longer be any
.Vt knotes
associated with the
.Fa fd .
The
.Vt knotes
removed will never be returned from a
.Xr kevent 2
call, so if userland uses the
.Vt knote
to track resources, they will be leaked.
The
.Fn FILEDESC_LOCK
lock must be held over the call to
.Fn knote_fdclose
so that file descriptors cannot be added or removed.
.Pp
The
.Fn knlist_*
family of functions are for managing
.Vt knotes
associated with an object.
A
.Vt knlist
is not required, but is commonly used.
If used, the
.Vt knlist
must be initialized with either
.Fn knlist_init ,
.Fn knlist_init_mtx
or
.Fn knlist_init_rw_reader .
The
.Vt knlist
structure may be embedded into the object structure.
The
.Fa lock
will be held over
.Va f_event
calls.
.Pp
For the
.Fn knlist_init
function, if
.Fa lock
is
.Dv NULL ,
a shared global lock will be used and the remaining arguments must be
.Dv NULL .
The function pointers
.Fa kl_lock , kl_unlock
and
.Fa kl_locked
will be used to manipulate the argument
.Fa lock .
If any of the function pointers are
.Dv NULL ,
a function operating on
.Dv MTX_DEF
style
.Xr mutex 9
locks will be used instead.
.Pp
The function
.Fn knlist_init_mtx
may be used to initialize a
.Vt knlist
when
.Fa lock
is a
.Dv MTX_DEF
style
.Xr mutex 9
lock.
.Pp
The function
.Fn knlist_init_rw_reader
may be used to initialize a
.Vt knlist
when
.Fa lock
is a
.Xr rwlock 9
read lock.
Lock is acquired via
.Fn rw_rlock
function.
.Pp
The function
.Fn knlist_empty
returns true when there are no
.Vt knotes
on the list.
The function requires that the
.Fa lock
be held when called.
.Pp
The function
.Fn knlist_clear
removes all
.Vt knotes
from the list.
The
.Fa islocked
argument declares if the
.Fa lock
has been acquired.
All
.Vt knotes
will have
.Dv EV_ONESHOT
set so that the
.Vt knote
will be returned and removed during the next scan.
The
.Va f_detach
function will be called when the
.Vt knote
is deleted during the next scan.
This function must not be used when
.Va f_isfd
is set in
.Vt "struct filterops" ,
as the
.Fa td
argument of
.Fn fdrop
will be
.Dv NULL .
.Pp
The function
.Fn knlist_delete
removes and deletes all
.Vt knotes
on the list.
The function
.Va f_detach
will not be called, and the
.Vt knote
will not be returned on the next scan.
Using this function could leak userland resources if a process uses the
.Vt knote
to track resources.
.Pp
Both the
.Fn knlist_clear
and
.Fn knlist_delete
functions may sleep.
They also may release the
.Fa lock
to wait for other
.Vt knotes
to drain.
.Pp
The
.Fn knlist_destroy
function is used to destroy a
.Vt knlist .
There must be no
.Vt knotes
associated with the
.Vt knlist
.Po Fn knlist_empty
returns true
.Pc
and no more
.Vt knotes
may be attached to the object.
A
.Vt knlist
may be emptied by calling
.Fn knlist_clear
or
.Fn knlist_delete .
.Pp
The macros
.Fn KNOTE_LOCKED
and
.Fn KNOTE_UNLOCKED
are used to notify
.Vt knotes
about events associated with the object.
It will iterate over all
.Vt knotes
on the list calling the
.Va f_event
function associated with the
.Vt knote .
The macro
.Fn KNOTE_LOCKED
must be used if the lock associated with the
.Fa knl
is held.
The function
.Fn KNOTE_UNLOCKED
will acquire the lock before iterating over the list of
.Vt knotes .
.Sh RETURN VALUES
The function
.Fn kqueue_add_filteropts
will return zero on success,
.Er EINVAL
in the case of an invalid
.Fa filt ,
or
.Er EEXIST
if the filter has already been installed.
.Pp
The function
.Fn kqueue_del_filteropts
will return zero on success,
.Er EINVAL
in the case of an invalid
.Fa filt ,
or
.Er EBUSY
if the filter is still in use.
.Pp
The function
.Fn kqfd_register
will return zero on success,
.Er EBADF
if the file descriptor is not a kqueue, or any of the possible values returned
by
.Xr kevent 2 .
.Sh SEE ALSO
.Xr kevent 2 ,
.Xr kqueue 2
.Sh AUTHORS
This
manual page was written by
.An John-Mark Gurney Aq Mt jmg@FreeBSD.org .
|