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 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 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 23.\" SUCH DAMAGE. 24.\" 25.\" $FreeBSD$ 26.\" 27.Dd December 28, 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.Pp 192Locks 193.Em must not 194be acquired in 195.Va f_event . 196If a lock is required in 197.Va f_event , 198it must be obtained in the 199.Fa kl_lock 200function of the 201.Vt knlist 202that the 203.Va knote 204was added to. 205.El 206.Pp 207The function 208.Fn kqfd_register 209will register the 210.Vt kevent 211on the kqueue file descriptor 212.Fa fd . 213If it is safe to sleep, 214.Fa waitok 215should be set. 216.Pp 217The function 218.Fn knote_fdclose 219is used to delete all 220.Vt knotes 221associated with 222.Fa fd . 223Once returned, there will no longer be any 224.Vt knotes 225associated with the 226.Fa fd . 227The 228.Vt knotes 229removed will never be returned from a 230.Xr kevent 2 231call, so if userland uses the 232.Vt knote 233to track resources, they will be leaked. 234The 235.Fn FILEDESC_LOCK 236lock must be held over the call to 237.Fn knote_fdclose 238so that file descriptors cannot be added or removed. 239.Pp 240The 241.Fn knlist_* 242family of functions are for managing 243.Vt knotes 244associated with an object. 245A 246.Vt knlist 247is not required, but is commonly used. 248If used, the 249.Vt knlist 250must be initialized with the 251.Fn knlist_init 252function. 253If 254.Fa lock 255is 256.Dv NULL , 257an internal lock will be used and the remaining arguments will be ignored. 258The 259.Fa kl_lock , kl_unlock 260and 261.Fa kl_locked 262functions will be used to manipulate a 263.Fa lock . 264If the argument is 265.Dv NULL , 266default routines operating on 267.Vt "struct mtx *" 268will be used. 269The 270.Vt knlist 271structure may be embedded into the object structure. 272The 273.Fa lock 274will be held over calls to 275.Va f_event . 276If 277.Dv NULL 278is passed for the mutex, a private mutex will be used. 279The function 280.Fn knlist_empty 281requires that a 282.Fa lock 283be held. 284The function 285.Fn knlist_clear 286is used to remove all 287.Vt knotes 288associated with the list. 289The 290.Fa islocked 291argument declares if 292.Fa lock 293has been acquired. 294All 295.Vt knotes 296will be marked as detached, and 297.Dv EV_ONESHOT 298will be set so that the 299.Vt knote 300will be deleted after the next scan. 301The 302.Fn knlist_destroy 303function is used to destroy a 304.Vt knlist . 305There must be no 306.Vt knotes 307associated with the 308.Vt knlist 309.Fn ( knlist_empty 310returns true) 311and no more 312.Vt knotes 313may be attached to the object. 314A 315.Vt knlist 316may be emptied by calling 317.Fn knlist_clear . 318.Pp 319The macros 320.Fn KNOTE_LOCKED 321and 322.Fn KNOTE_UNLOCKED 323are used to notify 324.Vt knotes 325about events associated with the object. 326It will iterate over all 327.Vt knotes 328on the list calling the 329.Va f_event 330function associated with the 331.Vt knote . 332The macro 333.Fn KNOTE_LOCKED 334must be used if the lock associated with the 335.Fa knl 336passed in is held. 337The function 338.Fn KNOTE_UNLOCKED 339will acquire the lock before iterating over the list of 340.Vt knotes . 341.Sh RETURN VALUES 342The function 343.Fn kqueue_add_filteropts 344will return zero on success, 345.Er EINVAL 346in the case of an invalid 347.Fa filt , 348or 349.Er EEXIST 350if the filter has already been installed. 351.Pp 352The function 353.Fn kqueue_del_filteropts 354will return zero on success, 355.Er EINVAL 356in the case of an invalid 357.Fa filt , 358or 359.Er EBUSY 360if the filter is still in use. 361.Pp 362The function 363.Fn kqfd_register 364will return zero on success, 365.Er EBADF 366if the file descriptor is not a kqueue, or any of the possible values returned 367by 368.Xr kevent 2 . 369.Sh SEE ALSO 370.Xr kevent 2 , 371.Xr kqueue 2 372.Sh AUTHORS 373This 374manual page was written by 375.An John-Mark Gurney Aq jmg@FreeBSD.org . 376