1 .\" Copyright 2006,2011 John-Mark Gurney
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
31 .Nm kqueue_add_filteropts , kqueue_del_filteropts ,
34 .Nm knlist_init , knlist_init_mtx , knlist_init_rw_reader ,
35 .Nm knlist_add , knlist_remove , knlist_remove_inevent , knlist_empty ,
36 .Nm knlist_clear , knlist_delete , knlist_destroy ,
37 .Nm KNOTE_LOCKED , KNOTE_UNLOCKED
38 .Nd "event delivery subsystem"
42 .Fn kqueue_add_filteropts "int filt" "struct filterops *filtops"
44 .Fn kqueue_del_filteropts "int filt"
46 .Fn kqfd_register "int fd" "struct kevent *kev" "struct thread *td" "int waitok"
48 .Fn knote_fdclose "struct thread *td" "int fd"
51 .Fa "struct knlist *knl"
53 .Fa "void \*[lp]*kl_lock\*[rp]\*[lp]void *\*[rp]"
54 .Fa "void \*[lp]*kl_unlock\*[rp]\*[lp]void *\*[rp]"
55 .Fa "int \*[lp]*kl_locked\*[rp]\*[lp]void *\*[rp]"
58 .Fn knlist_init_mtx "struct knlist *knl" "struct mtx *lock"
60 .Fn knlist_init_rw_reader "struct knlist *knl" "struct rwlock *lock"
62 .Fn knlist_add "struct knlist *knl" "struct knote *kn" "int islocked"
64 .Fn knlist_remove "struct knlist *knl" "struct knote *kn" "int islocked"
66 .Fn knlist_remove_inevent "struct knlist *knl" "struct knote *kn"
68 .Fn knlist_empty "struct knlist *knl"
70 .Fn knlist_clear "struct knlist *knl" "int islocked"
72 .Fn knlist_delete "struct knlist *knl" "struct thread *td" "int islocked"
74 .Fn knlist_destroy "struct knlist *knl"
76 .Fn KNOTE_LOCKED "struct knlist *knl" "long hint"
78 .Fn KNOTE_UNLOCKED "struct knlist *knl" "long hint"
81 .Fn kqueue_add_filteropts
83 .Fn kqueue_del_filteropts
84 allow for the addition and removal of a filter type.
85 The filter is statically defined by the
89 .Fn kqueue_add_filteropts
94 .Vt "struct filterops"
95 has the following members:
96 .Bl -tag -width ".Va f_attach"
104 is taken to be a file descriptor.
111 member initialized to the
113 that represents the file descriptor.
117 function will be called when attaching a
120 The method should call
124 to the list that was initialized with
128 is only necessary if the object can have multiple
143 The function shall return 0 on success, or appropriate error for the failure,
144 such as when the object is being destroyed, or does not exist.
147 it is valid to change the
149 pointer to a different pointer.
154 functions called when processing the
159 function will be called to detach the
163 has not already been detached by a call to
165 .Fn knlist_remove_inevent
170 will not be held when this function is called.
174 function will be called to update the status of the
176 If the function returns 0, it will be assumed that the object is not
177 ready (or no longer ready) to be woken up.
180 argument will be 0 when scanning
182 to see which are triggered.
185 argument will be the value passed to either
191 value should be updated as necessary to reflect the current value, such as
192 number of bytes available for reading, or buffer space available for writing.
193 If the note needs to be removed,
194 .Fn knlist_remove_inevent
197 .Fn knlist_remove_inevent
198 will remove the note from the list, the
200 function will not be called and the
202 will not be returned as an event.
208 If a lock is required in
210 it must be obtained in the
223 on the kqueue file descriptor
225 If it is safe to sleep,
231 is used to delete all
235 Once returned, there will no longer be any
241 removed will never be returned from a
243 call, so if userland uses the
245 to track resources, they will be leaked.
248 lock must be held over the call to
250 so that file descriptors cannot be added or removed.
254 family of functions are for managing
256 associated with an object.
259 is not required, but is commonly used.
262 must be initialized with either
266 .Fn knlist_init_rw_reader .
269 structure may be embedded into the object structure.
282 a shared global lock will be used and the remaining arguments must be
284 The function pointers
285 .Fa kl_lock , kl_unlock
288 will be used to manipulate the argument
290 If any of the function pointers are
292 a function operating on
296 locks will be used instead.
300 may be used to initialize a
311 .Fn knlist_init_rw_reader
312 may be used to initialize a
325 returns true when there are no
328 The function requires that the
339 argument declares if the
348 will be returned and removed durning the next scan.
351 function will be called when the
353 is deleted durning the next scan.
354 This function must not be used when
357 .Vt "struct filterops" ,
367 removes and deletes all
372 will not be called, and the
374 will not be returned on the next scan.
375 Using this function could leak user land resources if a process uses the
384 They also may release the
392 function is used to destroy a
402 may be attached to the object.
405 may be emptied by calling
416 about events associated with the object.
417 It will iterate over all
419 on the list calling the
421 function associated with the
425 must be used if the lock associated with the
430 will acquire the lock before iterating over the list of
434 .Fn kqueue_add_filteropts
435 will return zero on success,
437 in the case of an invalid
441 if the filter has already been installed.
444 .Fn kqueue_del_filteropts
445 will return zero on success,
447 in the case of an invalid
451 if the filter is still in use.
455 will return zero on success,
457 if the file descriptor is not a kqueue, or any of the possible values returned
465 manual page was written by
466 .An John-Mark Gurney Aq jmg@FreeBSD.org .