share/man/man9/kqueue.9

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