share/man/man9/kqueue.9

   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
  80 The functions
  81 .Fn kqueue_add_filteropts
  82 and
  83 .Fn kqueue_del_filteropts
  84 allow for the addition and removal of a filter type.
  85 The filter is statically defined by the
  86 .Dv EVFILT_*
  87 macros.
  88 The function
  89 .Fn kqueue_add_filteropts
  90 will make
  91 .Fa filt
  92 available.
  93 The
  94 .Vt "struct filterops"
  95 has the following members:
  96 .Bl -tag -width ".Va f_attach"
  97 .It Va f_isfd
  98 If
  99 .Va f_isfd
 100 is set,
 101 .Va ident
 102 in
 103 .Vt "struct kevent"
 104 is taken to be a file descriptor.
 105 In this case, the
 106 .Vt knote
 107 passed into
 108 .Va f_attach
 109 will have the
 110 .Va kn_fp
 111 member initialized to the
 112 .Vt "struct file *"
 113 that represents the file descriptor.
 114 .It Va f_attach
 115 The
 116 .Va f_attach
 117 function will be called when attaching a
 118 .Vt knote
 119 to the object.
 120 The method should call
 121 .Fn knlist_add
 122 to add the
 123 .Vt knote
 124 to the list that was initialized with
 125 .Fn knlist_init .
 126 The call to
 127 .Fn knlist_add
 128 is only necessary if the object can have multiple
 129 .Vt knotes
 130 associated with it.
 131 If there is no
 132 .Vt knlist
 133 to call
 134 .Fn knlist_add
 135 with, the function
 136 .Va f_attach
 137 must clear the
 138 .Dv KN_DETACHED
 139 bit of
 140 .Va kn_status
 141 in the
 142 .Vt knote .
 143 The function shall return 0 on success, or appropriate error for the failure,
 144 such as when the object is being destroyed, or does not exist.
 145 During
 146 .Va f_attach ,
 147 it is valid to change the
 148 .Va kn_fops
 149 pointer to a different pointer.
 150 This will change the
 151 .Va f_event
 152 and
 153 .Va f_detach
 154 functions called when processing the
 155 .Vt knote .
 156 .It Va f_detach
 157 The
 158 .Va f_detach
 159 function will be called to detach the
 160 .Vt knote
 161 if the
 162 .Vt knote
 163 has not already been detached by a call to
 164 .Fn knlist_remove ,
 165 .Fn knlist_remove_inevent
 166 or
 167 .Fn knlist_delete .
 168 The list
 169 .Fa lock
 170 will not be held when this function is called.
 171 .It Va f_event
 172 The
 173 .Va f_event
 174 function will be called to update the status of the
 175 .Vt knote .
 176 If the function returns 0, it will be assumed that the object is not
 177 ready (or no longer ready) to be woken up.
 178 The
 179 .Fa hint
 180 argument will be 0 when scanning
 181 .Vt knotes
 182 to see which are triggered.
 183 Otherwise, the
 184 .Fa hint
 185 argument will be the value passed to either
 186 .Dv KNOTE_LOCKED
 187 or
 188 .Dv KNOTE_UNLOCKED .
 189 The
 190 .Va kn_data
 191 value should be updated as necessary to reflect the current value, such as
 192 number of bytes available for reading, or buffer space available for writing.
 193 If the note needs to be removed,
 194 .Fn knlist_remove_inevent
 195 must be called.
 196 The function
 197 .Fn knlist_remove_inevent
 198 will remove the note from the list, the
 199 .Va f_detach
 200 function will not be called and the
 201 .Vt knote
 202 will not be returned as an event.
 203 .Pp
 204 Locks
 205 .Em must not
 206 be acquired in
 207 .Va f_event .
 208 If a lock is required in
 209 .Va f_event ,
 210 it must be obtained in the
 211 .Fa kl_lock
 212 function of the
 213 .Vt knlist
 214 that the
 215 .Va knote
 216 was added to.
 217 .El
 218 .Pp
 219 The function
 220 .Fn kqfd_register
 221 will register the
 222 .Vt kevent
 223 on the kqueue file descriptor
 224 .Fa fd .
 225 If it is safe to sleep,
 226 .Fa waitok
 227 should be set.
 228 .Pp
 229 The function
 230 .Fn knote_fdclose
 231 is used to delete all
 232 .Vt knotes
 233 associated with
 234 .Fa fd .
 235 Once returned, there will no longer be any
 236 .Vt knotes
 237 associated with the
 238 .Fa fd .
 239 The
 240 .Vt knotes
 241 removed will never be returned from a
 242 .Xr kevent 2
 243 call, so if userland uses the
 244 .Vt knote
 245 to track resources, they will be leaked.
 246 The
 247 .Fn FILEDESC_LOCK
 248 lock must be held over the call to
 249 .Fn knote_fdclose
 250 so that file descriptors cannot be added or removed.
 251 .Pp
 252 The
 253 .Fn knlist_*
 254 family of functions are for managing
 255 .Vt knotes
 256 associated with an object.
 257 A
 258 .Vt knlist
 259 is not required, but is commonly used.
 260 If used, the
 261 .Vt knlist
 262 must be initialized with either
 263 .Fn knlist_init ,
 264 .Fn knlist_init_mtx
 265 or
 266 .Fn knlist_init_rw_reader .
 267 The
 268 .Vt knlist
 269 structure may be embedded into the object structure.
 270 The
 271 .Fa lock
 272 will be held over
 273 .Va f_event
 274 calls.
 275 .Pp
 276 For the
 277 .Fn knlist_init
 278 function, if
 279 .Fa lock
 280 is
 281 .Dv NULL ,
 282 a shared global lock will be used and the remaining arguments must be
 283 .Dv NULL .
 284 The function pointers
 285 .Fa kl_lock , kl_unlock
 286 and
 287 .Fa kl_locked
 288 will be used to manipulate the argument
 289 .Fa lock .
 290 If any of the function pointers are
 291 .Dv NULL ,
 292 a function operating on
 293 .Dv MTX_DEF
 294 style
 295 .Xr mutex 9
 296 locks will be used instead.
 297 .Pp
 298 The function
 299 .Fn knlist_init_mtx
 300 may be used to initialize a
 301 .Vt knlist
 302 when
 303 .Fa lock
 304 is a
 305 .Dv MTX_DEF
 306 style
 307 .Xr mutex 9
 308 lock.
 309 .Pp
 310 The function
 311 .Fn knlist_init_rw_reader
 312 may be used to initialize a
 313 .Vt knlist
 314 when
 315 .Fa lock
 316 is a
 317 .Xr rwlock 9
 318 read lock.
 319 Lock is acquired via
 320 .Fn rw_rlock
 321 function.
 322 .Pp
 323 The function
 324 .Fn knlist_empty
 325 returns true when there are no
 326 .Vt knotes
 327 on the list.
 328 The function requires that the
 329 .Fa lock
 330 be held when called.
 331 .Pp
 332 The function
 333 .Fn knlist_clear
 334 removes all
 335 .Vt knotes
 336 from the list.
 337 The
 338 .Fa islocked
 339 argument declares if the
 340 .Fa lock
 341 has been acquired.
 342 All
 343 .Vt knotes
 344 will have
 345 .Dv EV_ONESHOT
 346 set so that the
 347 .Vt knote
 348 will be returned and removed durning the next scan.
 349 The
 350 .Va f_detach
 351 function will be called when the
 352 .Vt knote
 353 is deleted durning the next scan.
 354 This function must not be used when
 355 .Va f_isfd
 356 is set in
 357 .Vt "struct filterops" ,
 358 as the
 359 .Fa td
 360 argument of
 361 .Fn fdrop
 362 will be
 363 .Dv NULL .
 364 .Pp
 365 The function
 366 .Fn knlist_delete
 367 removes and deletes all
 368 .Vt knotes
 369 on the list.
 370 The function
 371 .Va f_detach
 372 will not be called, and the
 373 .Vt knote
 374 will not be returned on the next scan.
 375 Using this function could leak user land resources if a process uses the
 376 .Vt knote
 377 to track resources.
 378 .Pp
 379 Both the
 380 .Fn knlist_clear
 381 and
 382 .Fn knlist_delete
 383 functions may sleep.
 384 They also may release the
 385 .Fa lock
 386 to wait for other
 387 .Vt knotes
 388 to drain.
 389 .Pp
 390 The
 391 .Fn knlist_destroy
 392 function is used to destroy a
 393 .Vt knlist .
 394 There must be no
 395 .Vt knotes
 396 associated with the
 397 .Vt knlist
 398 .Fn ( knlist_empty
 399 returns true)
 400 and no more
 401 .Vt knotes
 402 may be attached to the object.
 403 A
 404 .Vt knlist
 405 may be emptied by calling
 406 .Fn knlist_clear
 407 or
 408 .Fn knlist_delete .
 409 .Pp
 410 The macros
 411 .Fn KNOTE_LOCKED
 412 and
 413 .Fn KNOTE_UNLOCKED
 414 are used to notify
 415 .Vt knotes
 416 about events associated with the object.
 417 It will iterate over all
 418 .Vt knotes
 419 on the list calling the
 420 .Va f_event
 421 function associated with the
 422 .Vt knote .
 423 The macro
 424 .Fn KNOTE_LOCKED
 425 must be used if the lock associated with the
 426 .Fa knl
 427 is held.
 428 The function
 429 .Fn KNOTE_UNLOCKED
 430 will acquire the lock before iterating over the list of
 431 .Vt knotes .
 432 .Sh RETURN VALUES
 433 The function
 434 .Fn kqueue_add_filteropts
 435 will return zero on success,
 436 .Er EINVAL
 437 in the case of an invalid
 438 .Fa filt ,
 439 or
 440 .Er EEXIST
 441 if the filter has already been installed.
 442 .Pp
 443 The function
 444 .Fn kqueue_del_filteropts
 445 will return zero on success,
 446 .Er EINVAL
 447 in the case of an invalid
 448 .Fa filt ,
 449 or
 450 .Er EBUSY
 451 if the filter is still in use.
 452 .Pp
 453 The function
 454 .Fn kqfd_register
 455 will return zero on success,
 456 .Er EBADF
 457 if the file descriptor is not a kqueue, or any of the possible values returned
 458 by
 459 .Xr kevent 2 .
 460 .Sh SEE ALSO
 461 .Xr kevent 2 ,
 462 .Xr kqueue 2
 463 .Sh AUTHORS
 464 This
 465 manual page was written by
 466 .An John-Mark Gurney Aq jmg@FreeBSD.org .