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 durning the next scan. 349The 350.Va f_detach 351function will be called when the 352.Vt knote 353is deleted durning 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 user land 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.Fn ( knlist_empty 399returns true) 400and no more 401.Vt knotes 402may be attached to the object. 403A 404.Vt knlist 405may be emptied by calling 406.Fn knlist_clear 407or 408.Fn knlist_delete . 409.Pp 410The macros 411.Fn KNOTE_LOCKED 412and 413.Fn KNOTE_UNLOCKED 414are used to notify 415.Vt knotes 416about events associated with the object. 417It will iterate over all 418.Vt knotes 419on the list calling the 420.Va f_event 421function associated with the 422.Vt knote . 423The macro 424.Fn KNOTE_LOCKED 425must be used if the lock associated with the 426.Fa knl 427is held. 428The function 429.Fn KNOTE_UNLOCKED 430will acquire the lock before iterating over the list of 431.Vt knotes . 432.Sh RETURN VALUES 433The function 434.Fn kqueue_add_filteropts 435will return zero on success, 436.Er EINVAL 437in the case of an invalid 438.Fa filt , 439or 440.Er EEXIST 441if the filter has already been installed. 442.Pp 443The function 444.Fn kqueue_del_filteropts 445will return zero on success, 446.Er EINVAL 447in the case of an invalid 448.Fa filt , 449or 450.Er EBUSY 451if the filter is still in use. 452.Pp 453The function 454.Fn kqfd_register 455will return zero on success, 456.Er EBADF 457if the file descriptor is not a kqueue, or any of the possible values returned 458by 459.Xr kevent 2 . 460.Sh SEE ALSO 461.Xr kevent 2 , 462.Xr kqueue 2 463.Sh AUTHORS 464This 465manual page was written by 466.An John-Mark Gurney Aq jmg@FreeBSD.org . 467