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.Fn knlist_init_mtx 265or 266.Fn knlist_init_rw_reader . 267The 268.Vt knlist 269structure may be embedded into the object structure. 270The 271.Fa lock 272will be held over 273.Va f_event 274calls. 275.Pp 276For the 277.Fn knlist_init 278function, if 279.Fa lock 280is 281.Dv NULL , 282a shared global lock will be used and the remaining arguments must be 283.Dv NULL . 284The function pointers 285.Fa kl_lock , kl_unlock 286and 287.Fa kl_locked 288will be used to manipulate the argument 289.Fa lock . 290If any of the function pointers are 291.Dv NULL , 292a function operating on 293.Dv MTX_DEF 294style 295.Xr mutex 9 296locks will be used instead. 297.Pp 298The function 299.Fn knlist_init_mtx 300may be used to initialize a 301.Vt knlist 302when 303.Fa lock 304is a 305.Dv MTX_DEF 306style 307.Xr mutex 9 308lock. 309.Pp 310The function 311.Fn knlist_init_rw_reader 312may be used to initialize a 313.Vt knlist 314when 315.Fa lock 316is a 317.Xr rwlock 9 318read lock. 319Lock is acquired via 320.Fn rw_rlock 321function. 322.Pp 323The function 324.Fn knlist_empty 325returns true when there are no 326.Vt knotes 327on the list. 328The function requires that the 329.Fa lock 330be held when called. 331.Pp 332The function 333.Fn knlist_clear 334removes all 335.Vt knotes 336from the list. 337The 338.Fa islocked 339argument declares if the 340.Fa lock 341has been acquired. 342All 343.Vt knotes 344will have 345.Dv EV_ONESHOT 346set so that the 347.Vt knote 348will be returned and removed during the next scan. 349The 350.Va f_detach 351function will be called when the 352.Vt knote 353is deleted during the next scan. 354This function must not be used when 355.Va f_isfd 356is set in 357.Vt "struct filterops" , 358as the 359.Fa td 360argument of 361.Fn fdrop 362will be 363.Dv NULL . 364.Pp 365The function 366.Fn knlist_delete 367removes and deletes all 368.Vt knotes 369on the list. 370The function 371.Va f_detach 372will not be called, and the 373.Vt knote 374will not be returned on the next scan. 375Using this function could leak userland resources if a process uses the 376.Vt knote 377to track resources. 378.Pp 379Both the 380.Fn knlist_clear 381and 382.Fn knlist_delete 383functions may sleep. 384They also may release the 385.Fa lock 386to wait for other 387.Vt knotes 388to drain. 389.Pp 390The 391.Fn knlist_destroy 392function is used to destroy a 393.Vt knlist . 394There must be no 395.Vt knotes 396associated with the 397.Vt knlist 398.Po Fn knlist_empty 399returns true 400.Pc 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 Mt jmg@FreeBSD.org . 468