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