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