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