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 August 20, 2022 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. 323This function must not be used when 324.Va f_isfd 325is set in 326.Vt "struct filterops" , 327as the 328.Fa td 329argument of 330.Fn fdrop 331will be 332.Dv NULL . 333.Pp 334The function 335.Fn knlist_delete 336removes and deletes all 337.Vt knotes 338on the list. 339The function 340.Va f_detach 341will not be called, and the 342.Vt knote 343will not be returned on the next scan. 344Using this function could leak userland resources if a process uses the 345.Vt knote 346to track resources. 347.Pp 348Both the 349.Fn knlist_clear 350and 351.Fn knlist_delete 352functions may sleep. 353They also may release the 354.Fa lock 355to wait for other 356.Vt knotes 357to drain. 358.Pp 359The 360.Fn knlist_destroy 361function is used to destroy a 362.Vt knlist . 363There must be no 364.Vt knotes 365associated with the 366.Vt knlist 367.Po Fn knlist_empty 368returns true 369.Pc 370and no more 371.Vt knotes 372may be attached to the object. 373A 374.Vt knlist 375may be emptied by calling 376.Fn knlist_clear 377or 378.Fn knlist_delete . 379.Pp 380The macros 381.Fn KNOTE_LOCKED 382and 383.Fn KNOTE_UNLOCKED 384are used to notify 385.Vt knotes 386about events associated with the object. 387It will iterate over all 388.Vt knotes 389on the list calling the 390.Va f_event 391function associated with the 392.Vt knote . 393The macro 394.Fn KNOTE_LOCKED 395must be used if the lock associated with the 396.Fa knl 397is held. 398The function 399.Fn KNOTE_UNLOCKED 400will acquire the lock before iterating over the list of 401.Vt knotes . 402.Sh RETURN VALUES 403The function 404.Fn kqueue_add_filteropts 405will return zero on success, 406.Er EINVAL 407in the case of an invalid 408.Fa filt , 409or 410.Er EEXIST 411if the filter has already been installed. 412.Pp 413The function 414.Fn kqueue_del_filteropts 415will return zero on success, 416.Er EINVAL 417in the case of an invalid 418.Fa filt , 419or 420.Er EBUSY 421if the filter is still in use. 422.Pp 423The function 424.Fn kqfd_register 425will return zero on success, 426.Er EBADF 427if the file descriptor is not a kqueue, or any of the possible values returned 428by 429.Xr kevent 2 . 430.Sh SEE ALSO 431.Xr kevent 2 , 432.Xr kqueue 2 433.Sh AUTHORS 434This 435manual page was written by 436.An John-Mark Gurney Aq Mt jmg@FreeBSD.org . 437