| kqueue.9 (163014) | kqueue.9 (163025) |
|---|---|
| 1.\" Copyright 2004 John-Mark Gurney | 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 --- 7 unchanged lines hidden (view full) --- 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.\" | 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 --- 7 unchanged lines hidden (view full) --- 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 163014 2006-10-04 20:17:14Z jmg $ | 25.\" $FreeBSD: head/share/man/man9/kqueue.9 163025 2006-10-05 08:42:07Z ru $ |
| 26.\" 27.Dd October 4, 2006 28.Dt KQUEUE 9 29.Os 30.Sh NAME | 26.\" 27.Dd October 4, 2006 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 | 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 , |
| 43.Nm KNOTE_LOCKED , KNOTE_UNLOCKED | 36.Nm KNOTE_LOCKED , KNOTE_UNLOCKED |
| 44.Nd "activate knotes on a knlist" | 37.Nd "event delivery subsystem" |
| 45.Sh SYNOPSIS 46.In sys/event.h 47.Ft int | 38.Sh SYNOPSIS 39.In sys/event.h 40.Ft int |
| 48.Fn kqueue_add_filteropts "int filt" "struct filterops *" | 41.Fn kqueue_add_filteropts "int filt" "struct filterops *filtops" |
| 49.Ft int 50.Fn kqueue_del_filteropts "int filt" 51.Ft int | 42.Ft int 43.Fn kqueue_del_filteropts "int filt" 44.Ft int |
| 52.Fn kqfd_register "int fd" "struct kevent *" "struct thread *" "int waitok" | 45.Fn kqfd_register "int fd" "struct kevent *kev" "struct thread *td" "int waitok" |
| 53.Ft void | 46.Ft void |
| 54.Fn knote_fdclose "struct thread *" "int fd" | 47.Fn knote_fdclose "struct thread *td" "int fd" |
| 55.Ft void | 48.Ft void |
| 56.Fn knlist_add "struct knlist *" "struct knote *" "int islocked" | 49.Fn knlist_add "struct knlist *knl" "struct knote *kn" "int islocked" |
| 57.Ft void | 50.Ft void |
| 58.Fn knlist_remove "struct knlist *" "struct knote *" "int islocked" | 51.Fn knlist_remove "struct knlist *knl" "struct knote *kn" "int islocked" |
| 59.Ft void | 52.Ft void |
| 60.Fn knlist_remove_inevent "struct knlist *" "struct knote *" | 53.Fn knlist_remove_inevent "struct knlist *knl" "struct knote *kn" |
| 61.Ft int | 54.Ft int |
| 62.Fn knlist_empty "struct knlist *" | 55.Fn knlist_empty "struct knlist *knl" |
| 63.Ft void | 56.Ft void |
| 64.Fn knlist_init "struct knlist *" "void *lock" "void (*kl_lock)(void *)" "void (*kl_unlock)(void *) "int (*kl_locked)(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 |
| 65.Ft void | 64.Ft void |
| 66.Fn knlist_destroy "struct knlist *" | 65.Fn knlist_destroy "struct knlist *knl" |
| 67.Ft void | 66.Ft void |
| 68.Fn knlist_clear "struct knlist *" "int islocked" | 67.Fn knlist_clear "struct knlist *knl" "int islocked" |
| 69.Ft void | 68.Ft void |
| 70.Fn knlist_delete "struct knlist *" "struct thread *" "int islocked" | 69.Fn knlist_delete "struct knlist *knl" "struct thread *td" "int islocked" |
| 71.Ft void | 70.Ft void |
| 72.Fn KNOTE_LOCKED "struct knlist *" "long hint" | 71.Fn KNOTE_LOCKED "struct knlist *knl" "long hint" |
| 73.Ft void | 72.Ft void |
| 74.Fn KNOTE_UNLOCKED "struct knlist *" "long hint" | 73.Fn KNOTE_UNLOCKED "struct knlist *knl" "long hint" |
| 75.Sh DESCRIPTION 76The functions 77.Fn kqueue_add_filteropts 78and 79.Fn kqueue_del_filteropts | 74.Sh DESCRIPTION 75The functions 76.Fn kqueue_add_filteropts 77and 78.Fn kqueue_del_filteropts |
| 80allows the addition and removal of a filter type. 81The filter is staticly defined by the | 79allow for the addition and removal of a filter type. 80The filter is statically defined by the |
| 82.Dv EVFILT_* 83macros. 84The function 85.Fn kqueue_add_filteropts | 81.Dv EVFILT_* 82macros. 83The function 84.Fn kqueue_add_filteropts |
| 86will make filt available. The | 85will make 86.Fa filt 87available. 88The |
| 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. | 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. |
| 98In this case, the knote passed into | 100In this case, the 101.Vt knote 102passed into |
| 99.Va f_attach 100will have the 101.Va kn_fp | 103.Va f_attach 104will have the 105.Va kn_fp |
| 102member initalized to the | 106member initialized to the |
| 103.Vt "struct file *" | 107.Vt "struct file *" |
| 104that represense the file descriptor. | 108that represents the file descriptor. |
| 105.It Va f_attach 106The 107.Va f_attach | 109.It Va f_attach 110The 111.Va f_attach |
| 108member will be called when attaching a | 112function 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 | 113.Vt knote 114to the object. 115The method should call 116.Fn knlist_add 117to add the 118.Vt knote |
| 115to the list that was initalized with | 119to the list that was initialized with |
| 116.Fn knlist_init . 117The call to 118.Fn knlist_add | 120.Fn knlist_init . 121The call to 122.Fn knlist_add |
| 119is only necesary if the object can have multiple knotes associated with it. | 123is only necessary if the object can have multiple 124.Vt knotes 125associated 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 | 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 |
| 131.Va knote . 132The function shall return 0 on success, or appropriate errno for the failure. 133Durning 134.Va f_attach | 137.Vt knote . 138The function shall return 0 on success, or appropriate error for the failure. 139During 140.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 | 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 |
| 142members called when processing the knote. | 148functions called when processing the 149.Vt knote . |
| 143.It Va f_detach 144The 145.Va f_detach | 150.It Va f_detach 151The 152.Va f_detach |
| 146member will be called to detach the | 153function 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 | 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 |
| 155meber will be called to update the status of the | 162function 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. | 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. |
| 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 | 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 |
| 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 | 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 |
| 176member will not be called and the 177.Va knote | 188function will not be called and the 189.Vt 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 . | 190will not be returned as an event. 191.El 192.Pp 193The function 194.Fn kqfd_register 195will register the 196.Vt kevent 197on the kqueue file descriptor 198.Fa fd . |
| 187If it is safe to sleep, waitok should be set. | 199If it is safe to sleep, 200.Fa waitok 201should be set. |
| 188.Pp 189The function 190.Fn knote_fdclose 191is used to delete all 192.Vt knotes 193associated with 194.Fa fd . | 202.Pp 203The function 204.Fn knote_fdclose 205is used to delete all 206.Vt knotes 207associated with 208.Fa fd . |
| 195Once returned there will no longer be any | 209Once 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 | 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 |
| 208must be held over the call to | 222lock must 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_* | 223.Fn knote_fdclose 224so that file descriptors cannot be added or removed. 225.Pp 226The 227.Fn knlist_* |
| 214family of functions are for managing knotes associated with an object. | 228family of functions are for managing 229.Vt knotes 230associated with an object. |
| 215A | 231A |
| 216.Va knlist | 232.Vt knlist |
| 217is not required, but is commonly used. 218If used, the 219.Vt knlist | 233is not required, but is commonly used. 234If used, the 235.Vt knlist |
| 220must be initalized with the | 236must be initialized 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 | 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 |
| 232will be used to manipulate | 248functions will be used to manipulate a |
| 233.Fa lock . 234If the argument is 235.Dv NULL , | 249.Fa lock . 250If the argument is 251.Dv NULL , |
| 236a default routine operating on | 252default routines operating on |
| 237.Vt "struct mtx *" 238will be used. 239The 240.Vt knlist | 253.Vt "struct mtx *" 254will be used. 255The 256.Vt knlist |
| 241structure may be embeded in your object structure. | 257structure may be embedded into the object structure. |
| 242The 243.Fa lock 244will be held over calls to | 258The 259.Fa lock 260will be held over calls to |
| 245.Fn f_event . | 261.Va f_event . |
| 246If 247.Dv NULL 248is passed for the mutex, a private mutex will be used. 249The function 250.Fn knlist_empty | 262If 263.Dv NULL 264is passed for the mutex, a private mutex will be used. 265The function 266.Fn knlist_empty |
| 251requires that | 267requires that a |
| 252.Fa lock 253be held. 254The function 255.Fn knlist_clear | 268.Fa lock 269be held. 270The function 271.Fn knlist_clear |
| 256is used to remove all knotes associated with the list. | 272is used to remove all 273.Vt knotes 274associated with the list. |
| 257The 258.Fa islocked | 275The 276.Fa islocked |
| 259argument declares if you have the | 277argument declares if |
| 260.Fa lock | 278.Fa lock |
| 261has been aquired. | 279has been acquired. |
| 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. | 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. |
| 269The function | 287The |
| 270.Fn knlist_destroy | 288.Fn knlist_destroy |
| 271is to be used at object destruction time. | 289function is used to destroy a 290.Vt knlist . |
| 272There must be no 273.Vt knotes 274associated with the 275.Vt knlist | 291There must be no 292.Vt knotes 293associated with the 294.Vt knlist |
| 276.Fn ( knlist_clear 277be called before or 278.Fn knlist_empty 279returns true) and no more | 295.Fn ( knlist_empty 296returns true) 297and no more |
| 280.Vt knotes | 298.Vt knotes |
| 281are able to be attached to the object. | 299may be attached to the object. 300A 301.Vt knlist 302may be emptied by calling 303.Fn knlist_clear . |
| 282.Pp | 304.Pp |
| 283.Pp 284The functions | 305The macros |
| 285.Fn KNOTE_LOCKED 286and 287.Fn KNOTE_UNLOCKED | 306.Fn KNOTE_LOCKED 307and 308.Fn KNOTE_UNLOCKED |
| 288are used to notify knotes about events associated with your object. 289It will iterated over all | 309are used to notify |
| 290.Vt knotes | 310.Vt knotes |
| 311about events associated with the object. 312It will iterate over all 313.Vt knotes |
|
| 291on the list calling the 292.Va f_event 293function associated with the 294.Vt knote . | 314on the list calling the 315.Va f_event 316function associated with the 317.Vt knote . |
| 295The function | 318The macro |
| 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 | 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 |
| 302will aquire the lock before iterating over the list of 303.Ft knotes . | 325will acquire the lock before iterating over the list of 326.Vt 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 | 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 |
| 310.Fa filt | 333.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 | 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 |
| 320.Fa filt | 343.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 | 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 |
| 329if the file descriptor is not a kqueue or any of the possible values returned | 352if the file descriptor is not a kqueue, or any of the possible values returned |
| 330by | 353by |
| 331.Xr kevent . | 354.Xr kevent 2 . |
| 332.Sh SEE ALSO | 355.Sh SEE ALSO |
| 333.Xr kqueue 2 , 334.Xr kevent 2 | 356.Xr kevent 2 , 357.Xr kqueue 2 |
| 335.Sh AUTHORS 336This 337manual page was written by 338.An John-Mark Gurney Aq jmg@FreeBSD.org . | 358.Sh AUTHORS 359This 360manual page was written by 361.An John-Mark Gurney Aq jmg@FreeBSD.org . |