1.\" Copyright 2006,2011 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.Dd December 2, 2025 26.Dt KQUEUE 9 27.Os 28.Sh NAME 29.Nm kqueue_add_filteropts , kqueue_del_filteropts , 30.Nm kqfd_register , 31.Nm knote_fdclose , 32.Nm knlist_init , knlist_init_mtx , 33.Nm knlist_add , knlist_remove , knlist_empty , 34.Nm knlist_clear , knlist_delete , knlist_destroy , 35.Nm KNOTE_LOCKED , KNOTE_UNLOCKED 36.Nd "event delivery subsystem" 37.Sh SYNOPSIS 38.In sys/event.h 39.Ft int 40.Fn kqueue_add_filteropts "int filt" "struct filterops *filtops" 41.Ft int 42.Fn kqueue_del_filteropts "int filt" 43.Ft int 44.Fn kqfd_register "int fd" "struct kevent *kev" "struct thread *td" "int waitok" 45.Ft void 46.Fn knote_fdclose "struct thread *td" "int fd" 47.Ft void 48.Fo knlist_init 49.Fa "struct knlist *knl" 50.Fa "void *lock" 51.Fa "void \*[lp]*kl_lock\*[rp]\*[lp]void *\*[rp]" 52.Fa "void \*[lp]*kl_unlock\*[rp]\*[lp]void *\*[rp]" 53.Fa "int \*[lp]*kl_locked\*[rp]\*[lp]void *\*[rp]" 54.Fc 55.Ft void 56.Fn knlist_init_mtx "struct knlist *knl" "struct mtx *lock" 57.Ft void 58.Fn knlist_add "struct knlist *knl" "struct knote *kn" "int islocked" 59.Ft void 60.Fn knlist_remove "struct knlist *knl" "struct knote *kn" "int islocked" 61.Ft int 62.Fn knlist_empty "struct knlist *knl" 63.Ft void 64.Fn knlist_clear "struct knlist *knl" "int islocked" 65.Ft void 66.Fn knlist_delete "struct knlist *knl" "struct thread *td" "int islocked" 67.Ft void 68.Fn knlist_destroy "struct knlist *knl" 69.Ft void 70.Fn KNOTE_LOCKED "struct knlist *knl" "long hint" 71.Ft void 72.Fn KNOTE_UNLOCKED "struct knlist *knl" "long hint" 73.Sh DESCRIPTION 74The functions 75.Fn kqueue_add_filteropts 76and 77.Fn kqueue_del_filteropts 78allow for the addition and removal of a filter type. 79The filter is statically defined by the 80.Dv EVFILT_* 81macros. 82The function 83.Fn kqueue_add_filteropts 84will make 85.Fa filt 86available. 87The 88.Vt "struct filterops" 89has the following members: 90.Bl -tag -width ".Va f_attach" 91.It Va f_isfd 92If 93.Va f_isfd 94is set, 95.Va ident 96in 97.Vt "struct kevent" 98is taken to be a file descriptor. 99In this case, the 100.Vt knote 101passed into 102.Va f_attach 103will have the 104.Va kn_fp 105member initialized to the 106.Vt "struct file *" 107that represents the file descriptor. 108.It Va f_attach 109The 110.Va f_attach 111function will be called when attaching a 112.Vt knote 113to the object. 114The method should call 115.Fn knlist_add 116to add the 117.Vt knote 118to the list that was initialized with 119.Fn knlist_init . 120The call to 121.Fn knlist_add 122is only necessary if the object can have multiple 123.Vt knotes 124associated with it. 125If there is no 126.Vt knlist 127to call 128.Fn knlist_add 129with, the function 130.Va f_attach 131must clear the 132.Dv KN_DETACHED 133bit of 134.Va kn_status 135in the 136.Vt knote . 137The function shall return 0 on success, or appropriate error for the failure, 138such as when the object is being destroyed, or does not exist. 139During 140.Va f_attach , 141it is valid to change the 142.Va kn_fop 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 159or 160.Fn knlist_delete . 161The list 162.Fa lock 163will not be held when this function is called. 164.It Va f_event 165The 166.Va f_event 167function will be called to update the status of the 168.Vt knote . 169If the function returns 0, it will be assumed that the object is not 170ready (or no longer ready) to be woken up. 171The 172.Fa hint 173argument will be 0 when scanning 174.Vt knotes 175to see which are triggered. 176Otherwise, the 177.Fa hint 178argument will be the value passed to either 179.Dv KNOTE_LOCKED 180or 181.Dv KNOTE_UNLOCKED . 182The 183.Va kn_data 184value should be updated as necessary to reflect the current value, such as 185number of bytes available for reading, or buffer space available for writing. 186.Pp 187Locks 188.Em must not 189be acquired in 190.Va f_event . 191If a lock is required in 192.Va f_event , 193it must be obtained in the 194.Fa kl_lock 195function of the 196.Vt knlist 197that the 198.Va knote 199was added to. 200.It Va f_copy 201The 202.Va f_copy 203function is called to copy notes when the process forks. 204When 205.Dv NULL , 206the current node is not duplicated to the child process. 207Filter might set 208.Dv f_copy 209to 210.Fn knote_triv_copy 211if there is no additional handling required, besides shallow copying of the knote itself. 212.El 213.Pp 214The function 215.Fn kqfd_register 216will register the 217.Vt kevent 218on the kqueue file descriptor 219.Fa fd . 220If it is safe to sleep, 221.Fa waitok 222should be set. 223.Pp 224The function 225.Fn knote_fdclose 226is used to delete all 227.Vt knotes 228associated with 229.Fa fd . 230Once returned, there will no longer be any 231.Vt knotes 232associated with the 233.Fa fd . 234The 235.Vt knotes 236removed will never be returned from a 237.Xr kevent 2 238call, so if userland uses the 239.Vt knote 240to track resources, they will be leaked. 241The 242.Fn FILEDESC_LOCK 243lock must be held over the call to 244.Fn knote_fdclose 245so that file descriptors cannot be added or removed. 246.Pp 247The 248.Fn knlist_* 249family of functions are for managing 250.Vt knotes 251associated with an object. 252A 253.Vt knlist 254is not required, but is commonly used. 255If used, the 256.Vt knlist 257must be initialized with either 258.Fn knlist_init 259or 260.Fn knlist_init_mtx . 261The 262.Vt knlist 263structure may be embedded into the object structure. 264The 265.Fa lock 266will be held over 267.Va f_event 268calls. 269.Pp 270For the 271.Fn knlist_init 272function, if 273.Fa lock 274is 275.Dv NULL , 276a shared global lock will be used and the remaining arguments must be 277.Dv NULL . 278The function pointers 279.Fa kl_lock , kl_unlock 280and 281.Fa kl_locked 282will be used to manipulate the argument 283.Fa lock . 284If any of the function pointers are 285.Dv NULL , 286a function operating on 287.Dv MTX_DEF 288style 289.Xr mutex 9 290locks will be used instead. 291.Pp 292The function 293.Fn knlist_init_mtx 294may be used to initialize a 295.Vt knlist 296when 297.Fa lock 298is a 299.Dv MTX_DEF 300style 301.Xr mutex 9 302lock. 303.Pp 304The function 305.Fn knlist_empty 306returns true when there are no 307.Vt knotes 308on the list. 309The function requires that the 310.Fa lock 311be held when called. 312.Pp 313The function 314.Fn knlist_clear 315removes all 316.Vt knotes 317from the list. 318The 319.Fa islocked 320argument declares if the 321.Fa lock 322has been acquired. 323All 324.Vt knotes 325will have 326.Dv EV_ONESHOT 327set so that the 328.Vt knote 329will be returned and removed during the next scan. 330The 331.Va f_detach 332function will be called when the 333.Vt knote 334is deleted during the next scan. 335.Pp 336The function 337.Fn knlist_delete 338removes and deletes all 339.Vt knotes 340on the list. 341The function 342.Va f_detach 343will not be called, and the 344.Vt knote 345will not be returned on the next scan. 346Using this function could leak userland resources if a process uses the 347.Vt knote 348to track resources. 349.Pp 350Both the 351.Fn knlist_clear 352and 353.Fn knlist_delete 354functions may sleep. 355They also may release the 356.Fa lock 357to wait for other 358.Vt knotes 359to drain. 360.Pp 361The 362.Fn knlist_destroy 363function is used to destroy a 364.Vt knlist . 365There must be no 366.Vt knotes 367associated with the 368.Vt knlist 369.Po Fn knlist_empty 370returns true 371.Pc 372and no more 373.Vt knotes 374may be attached to the object. 375A 376.Vt knlist 377may be emptied by calling 378.Fn knlist_clear 379or 380.Fn knlist_delete . 381.Pp 382The macros 383.Fn KNOTE_LOCKED 384and 385.Fn KNOTE_UNLOCKED 386are used to notify 387.Vt knotes 388about events associated with the object. 389It will iterate over all 390.Vt knotes 391on the list calling the 392.Va f_event 393function associated with the 394.Vt knote . 395The macro 396.Fn KNOTE_LOCKED 397must be used if the lock associated with the 398.Fa knl 399is held. 400The function 401.Fn KNOTE_UNLOCKED 402will acquire the lock before iterating over the list of 403.Vt knotes . 404.Sh RETURN VALUES 405The function 406.Fn kqueue_add_filteropts 407will return zero on success, 408.Er EINVAL 409in the case of an invalid 410.Fa filt , 411or 412.Er EEXIST 413if the filter has already been installed. 414.Pp 415The function 416.Fn kqueue_del_filteropts 417will return zero on success, 418.Er EINVAL 419in the case of an invalid 420.Fa filt , 421or 422.Er EBUSY 423if the filter is still in use. 424.Pp 425The function 426.Fn kqfd_register 427will return zero on success, 428.Er EBADF 429if the file descriptor is not a kqueue, or any of the possible values returned 430by 431.Xr kevent 2 . 432.Sh SEE ALSO 433.Xr kevent 2 , 434.Xr kqueue 2 435.Sh AUTHORS 436This 437manual page was written by 438.An John-Mark Gurney Aq Mt jmg@FreeBSD.org . 439