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