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