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