1.\" Copyright 2006 John-Mark Gurney |
2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 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 --- 7 unchanged lines hidden (view full) --- 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 23.\" SUCH DAMAGE. 24.\" |
25.\" $FreeBSD: head/share/man/man9/kqueue.9 163025 2006-10-05 08:42:07Z ru $ |
26.\" 27.Dd October 4, 2006 28.Dt KQUEUE 9 29.Os 30.Sh NAME |
31.Nm kqueue_add_filteropts , kqueue_del_filteropts , 32.Nm kqfd_register , 33.Nm knote_fdclose , 34.Nm knlist_add , knlist_remove , knlist_remove_inevent , knlist_empty , 35.Nm knlist_init , knlist_destroy , knlist_clear , knlist_delete , |
36.Nm KNOTE_LOCKED , KNOTE_UNLOCKED |
37.Nd "event delivery subsystem" |
38.Sh SYNOPSIS 39.In sys/event.h 40.Ft int |
41.Fn kqueue_add_filteropts "int filt" "struct filterops *filtops" |
42.Ft int 43.Fn kqueue_del_filteropts "int filt" 44.Ft int |
45.Fn kqfd_register "int fd" "struct kevent *kev" "struct thread *td" "int waitok" |
46.Ft void |
47.Fn knote_fdclose "struct thread *td" "int fd" |
48.Ft void |
49.Fn knlist_add "struct knlist *knl" "struct knote *kn" "int islocked" |
50.Ft void |
51.Fn knlist_remove "struct knlist *knl" "struct knote *kn" "int islocked" |
52.Ft void |
53.Fn knlist_remove_inevent "struct knlist *knl" "struct knote *kn" |
54.Ft int |
55.Fn knlist_empty "struct knlist *knl" |
56.Ft void |
57.Fo knlist_init 58.Fa "struct knlist *knl" 59.Fa "void *lock" 60.Fa "void \*[lp]*kl_lock\*[rp]\*[lp]void *\*[rp]" 61.Fa "void \*[lp]*kl_unlock\*[rp]\*[lp]void *\*[rp]" 62.Fa "int \*[lp]*kl_locked\*[rp]\*[lp]void *\*[rp]" 63.Fc |
64.Ft void |
65.Fn knlist_destroy "struct knlist *knl" |
66.Ft void |
67.Fn knlist_clear "struct knlist *knl" "int islocked" |
68.Ft void |
69.Fn knlist_delete "struct knlist *knl" "struct thread *td" "int islocked" |
70.Ft void |
71.Fn KNOTE_LOCKED "struct knlist *knl" "long hint" |
72.Ft void |
73.Fn KNOTE_UNLOCKED "struct knlist *knl" "long hint" |
74.Sh DESCRIPTION 75The functions 76.Fn kqueue_add_filteropts 77and 78.Fn kqueue_del_filteropts |
79allow for the addition and removal of a filter type. 80The filter is statically defined by the |
81.Dv EVFILT_* 82macros. 83The function 84.Fn kqueue_add_filteropts |
85will make 86.Fa filt 87available. 88The |
89.Vt "struct filterops" 90has the following members: 91.Bl -tag -width ".Va f_attach" 92.It Va f_isfd 93If 94.Va f_isfd 95is set, 96.Va ident 97in 98.Vt "struct kevent" 99is taken to be a file descriptor. |
100In this case, the 101.Vt knote 102passed into |
103.Va f_attach 104will have the 105.Va kn_fp |
106member initialized to the |
107.Vt "struct file *" |
108that represents the file descriptor. |
109.It Va f_attach 110The 111.Va f_attach |
112function will be called when attaching a |
113.Vt knote 114to the object. 115The method should call 116.Fn knlist_add 117to add the 118.Vt knote |
119to the list that was initialized with |
120.Fn knlist_init . 121The call to 122.Fn knlist_add |
123is only necessary if the object can have multiple 124.Vt knotes 125associated with it. |
126If there is no 127.Vt knlist 128to call 129.Fn knlist_add 130with, the function 131.Va f_attach 132must clear the 133.Dv KN_DETACHED 134bit of 135.Va kn_status 136in the |
137.Vt knote . 138The function shall return 0 on success, or appropriate error for the failure. 139During 140.Va f_attach , |
141it is valid to change the 142.Va kn_fops 143pointer to a different pointer. 144This will change the 145.Va f_event 146and 147.Va f_detach |
148functions called when processing the 149.Vt knote . |
150.It Va f_detach 151The 152.Va f_detach |
153function will be called to detach the |
154.Vt knote 155if the 156.Vt knote 157has not already been detached by a call to 158.Fn knlist_remove . 159.It Va f_event 160The 161.Va f_event |
162function will be called to update the status of the |
163.Vt knote . 164If the function returns 0, it will be assumed that the object is not 165ready (or no longer ready) to be woken up. |
166The 167.Fa hint 168argument will be 0 when scanning 169.Vt knotes 170to see which are triggered. 171Otherwise, the 172.Fa hint 173argument will be the value passed to either |
174.Dv KNOTE_LOCKED 175or 176.Dv KNOTE_UNLOCKED . 177The 178.Va kn_data 179value should be updated as necessary to reflect the current value, such as 180number of bytes available for reading, or buffer space available for writing. 181If the note needs to be removed, 182.Fn knlist_remove_inevent 183must be called. 184The function 185.Fn knlist_remove_inevent 186will remove the note from the list, the 187.Va f_detach |
188function will not be called and the 189.Vt knote |
190will not be returned as an event. 191.El 192.Pp 193The function 194.Fn kqfd_register 195will register the 196.Vt kevent 197on the kqueue file descriptor 198.Fa fd . |
199If it is safe to sleep, 200.Fa waitok 201should be set. |
202.Pp 203The function 204.Fn knote_fdclose 205is used to delete all 206.Vt knotes 207associated with 208.Fa fd . |
209Once returned, there will no longer be any |
210.Vt knotes 211associated with the 212.Fa fd . 213The 214.Vt knotes 215removed will never be returned from a 216.Xr kevent 2 217call, so if userland uses the 218.Vt knote 219to track resources, they will be leaked. 220The 221.Fn FILEDESC_LOCK |
222lock must be held over the call to |
223.Fn knote_fdclose 224so that file descriptors cannot be added or removed. 225.Pp 226The 227.Fn knlist_* |
228family of functions are for managing 229.Vt knotes 230associated with an object. |
231A |
232.Vt knlist |
233is not required, but is commonly used. 234If used, the 235.Vt knlist |
236must be initialized with the |
237.Fn knlist_init 238function. 239If 240.Fa lock 241is 242.Dv NULL , 243an internal lock will be used and the remaining arguments will be ignored. 244The 245.Fa kl_lock , kl_unlock 246and 247.Fa kl_locked |
248functions will be used to manipulate a |
249.Fa lock . 250If the argument is 251.Dv NULL , |
252default routines operating on |
253.Vt "struct mtx *" 254will be used. 255The 256.Vt knlist |
257structure may be embedded into the object structure. |
258The 259.Fa lock 260will be held over calls to |
261.Va f_event . |
262If 263.Dv NULL 264is passed for the mutex, a private mutex will be used. 265The function 266.Fn knlist_empty |
267requires that a |
268.Fa lock 269be held. 270The function 271.Fn knlist_clear |
272is used to remove all 273.Vt knotes 274associated with the list. |
275The 276.Fa islocked |
277argument declares if |
278.Fa lock |
279has been acquired. |
280All 281.Vt knotes 282will be marked as detached, and 283.Dv EV_ONESHOT 284will be set so that the 285.Vt knote 286will be deleted after the next scan. |
287The |
288.Fn knlist_destroy |
289function is used to destroy a 290.Vt knlist . |
291There must be no 292.Vt knotes 293associated with the 294.Vt knlist |
295.Fn ( knlist_empty 296returns true) 297and no more |
298.Vt knotes |
299may be attached to the object. 300A 301.Vt knlist 302may be emptied by calling 303.Fn knlist_clear . |
304.Pp |
305The macros |
306.Fn KNOTE_LOCKED 307and 308.Fn KNOTE_UNLOCKED |
309are used to notify |
310.Vt knotes |
311about events associated with the object. 312It will iterate over all 313.Vt knotes |
314on the list calling the 315.Va f_event 316function associated with the 317.Vt knote . |
318The macro |
319.Fn KNOTE_LOCKED 320must be used if the lock associated with the 321.Fa knl 322passed in is held. 323The function 324.Fn KNOTE_UNLOCKED |
325will acquire the lock before iterating over the list of 326.Vt knotes . |
327.Sh RETURN VALUES 328The function 329.Fn kqueue_add_filteropts 330will return zero on success, 331.Er EINVAL 332in the case of an invalid |
333.Fa filt , |
334or 335.Er EEXIST 336if the filter has already been installed. 337.Pp 338The function 339.Fn kqueue_del_filteropts 340will return zero on success, 341.Er EINVAL 342in the case of an invalid |
343.Fa filt , |
344or 345.Er EBUSY 346if the filter is still in use. 347.Pp 348The function 349.Fn kqfd_register 350will return zero on success, 351.Er EBADF |
352if the file descriptor is not a kqueue, or any of the possible values returned |
353by |
354.Xr kevent 2 . |
355.Sh SEE ALSO |
356.Xr kevent 2 , 357.Xr kqueue 2 |
358.Sh AUTHORS 359This 360manual page was written by 361.An John-Mark Gurney Aq jmg@FreeBSD.org . |