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 18, 2023 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.El 201.Pp 202The function 203.Fn kqfd_register 204will register the 205.Vt kevent 206on the kqueue file descriptor 207.Fa fd . 208If it is safe to sleep, 209.Fa waitok 210should be set. 211.Pp 212The function 213.Fn knote_fdclose 214is used to delete all 215.Vt knotes 216associated with 217.Fa fd . 218Once returned, there will no longer be any 219.Vt knotes 220associated with the 221.Fa fd . 222The 223.Vt knotes 224removed will never be returned from a 225.Xr kevent 2 226call, so if userland uses the 227.Vt knote 228to track resources, they will be leaked. 229The 230.Fn FILEDESC_LOCK 231lock must be held over the call to 232.Fn knote_fdclose 233so that file descriptors cannot be added or removed. 234.Pp 235The 236.Fn knlist_* 237family of functions are for managing 238.Vt knotes 239associated with an object. 240A 241.Vt knlist 242is not required, but is commonly used. 243If used, the 244.Vt knlist 245must be initialized with either 246.Fn knlist_init 247or 248.Fn knlist_init_mtx . 249The 250.Vt knlist 251structure may be embedded into the object structure. 252The 253.Fa lock 254will be held over 255.Va f_event 256calls. 257.Pp 258For the 259.Fn knlist_init 260function, if 261.Fa lock 262is 263.Dv NULL , 264a shared global lock will be used and the remaining arguments must be 265.Dv NULL . 266The function pointers 267.Fa kl_lock , kl_unlock 268and 269.Fa kl_locked 270will be used to manipulate the argument 271.Fa lock . 272If any of the function pointers are 273.Dv NULL , 274a function operating on 275.Dv MTX_DEF 276style 277.Xr mutex 9 278locks will be used instead. 279.Pp 280The function 281.Fn knlist_init_mtx 282may be used to initialize a 283.Vt knlist 284when 285.Fa lock 286is a 287.Dv MTX_DEF 288style 289.Xr mutex 9 290lock. 291.Pp 292The function 293.Fn knlist_empty 294returns true when there are no 295.Vt knotes 296on the list. 297The function requires that the 298.Fa lock 299be held when called. 300.Pp 301The function 302.Fn knlist_clear 303removes all 304.Vt knotes 305from the list. 306The 307.Fa islocked 308argument declares if the 309.Fa lock 310has been acquired. 311All 312.Vt knotes 313will have 314.Dv EV_ONESHOT 315set so that the 316.Vt knote 317will be returned and removed during the next scan. 318The 319.Va f_detach 320function will be called when the 321.Vt knote 322is deleted during the next scan. 323.Pp 324The function 325.Fn knlist_delete 326removes and deletes all 327.Vt knotes 328on the list. 329The function 330.Va f_detach 331will not be called, and the 332.Vt knote 333will not be returned on the next scan. 334Using this function could leak userland resources if a process uses the 335.Vt knote 336to track resources. 337.Pp 338Both the 339.Fn knlist_clear 340and 341.Fn knlist_delete 342functions may sleep. 343They also may release the 344.Fa lock 345to wait for other 346.Vt knotes 347to drain. 348.Pp 349The 350.Fn knlist_destroy 351function is used to destroy a 352.Vt knlist . 353There must be no 354.Vt knotes 355associated with the 356.Vt knlist 357.Po Fn knlist_empty 358returns true 359.Pc 360and no more 361.Vt knotes 362may be attached to the object. 363A 364.Vt knlist 365may be emptied by calling 366.Fn knlist_clear 367or 368.Fn knlist_delete . 369.Pp 370The macros 371.Fn KNOTE_LOCKED 372and 373.Fn KNOTE_UNLOCKED 374are used to notify 375.Vt knotes 376about events associated with the object. 377It will iterate over all 378.Vt knotes 379on the list calling the 380.Va f_event 381function associated with the 382.Vt knote . 383The macro 384.Fn KNOTE_LOCKED 385must be used if the lock associated with the 386.Fa knl 387is held. 388The function 389.Fn KNOTE_UNLOCKED 390will acquire the lock before iterating over the list of 391.Vt knotes . 392.Sh RETURN VALUES 393The function 394.Fn kqueue_add_filteropts 395will return zero on success, 396.Er EINVAL 397in the case of an invalid 398.Fa filt , 399or 400.Er EEXIST 401if the filter has already been installed. 402.Pp 403The function 404.Fn kqueue_del_filteropts 405will return zero on success, 406.Er EINVAL 407in the case of an invalid 408.Fa filt , 409or 410.Er EBUSY 411if the filter is still in use. 412.Pp 413The function 414.Fn kqfd_register 415will return zero on success, 416.Er EBADF 417if the file descriptor is not a kqueue, or any of the possible values returned 418by 419.Xr kevent 2 . 420.Sh SEE ALSO 421.Xr kevent 2 , 422.Xr kqueue 2 423.Sh AUTHORS 424This 425manual page was written by 426.An John-Mark Gurney Aq Mt jmg@FreeBSD.org . 427