share/man/man9/knote.9

   1 .\"     $NetBSD: knote.9,v 1.11 2004/02/18 16:50:25 jdolecek Exp $
   2 .\"
   3 .\" Copyright (c) 2001, 2002, 2003 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This documentation is derived from text contributed by
   7 .\" Luke Mewburn.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .Dd February 18, 2004
  31 .Dt KNOTE 9
  32 .Os
  33 .Sh NAME
  34 .Nm knote ,
  35 .Nm KNOTE
  36 .Nd raise kernel event
  37 .Sh SYNOPSIS
  38 .In sys/event.h
  39 .Ft void
  40 .Fn knote "struct klist *list" "long hint"
  41 .Fn KNOTE "struct klist *list" "long hint"
  42 .Sh DESCRIPTION
  43 The
  44 .Fn knote
  45 function provides a hook into the kqueue kernel event notification
  46 mechanism to allow sections of the kernel to raise a kernel event
  47 in the form of a
  48 .Sq knote ,
  49 which is a
  50 .Fa struct knote
  51 as defined in
  52 .Aq Pa sys/event.h .
  53 .Pp
  54 .Fn knote
  55 takes a singly linked
  56 .Fa list
  57 of knotes, along with a
  58 .Fa hint
  59 (which is passed to the appropriate filter routine).
  60 .Fn knote
  61 then walks the
  62 .Fa list
  63 making calls to the filter routine for each knote.
  64 As each knote contains a reference to the data structure that it is
  65 attached to, the filter may choose to examine the data structure in
  66 deciding whether an event should be reported.
  67 The
  68 .Fa hint
  69 is used to pass in additional information, which may not be present in
  70 the data structure that the filter examines.
  71 .Pp
  72 If the filter decides that the event should be returned, it returns a
  73 non-zero value and
  74 .Fn knote
  75 links the knote onto the tail end of the active list in the
  76 corresponding kqueue for the application to retrieve.
  77 If the knote is already on the active list, no action is taken, but the
  78 call to the filter occurs in order to provide an opportunity for the
  79 filter to record the activity.
  80 .Pp
  81 .Fn knote
  82 must not be called from interrupt contexts running at an interrupt
  83 priority level higher than
  84 .Fn splsched .
  85 .Pp
  86 .Fn KNOTE
  87 is a macro that calls
  88 .Fn knote list hint
  89 if
  90 .Fa list
  91 is not empty.
  92 .\" .Sh ERRORS
  93 .Sh SEE ALSO
  94 .Xr kqueue 2 ,
  95 .Xr kfilter_register 9
  96 .Sh HISTORY
  97 The
  98 .Fn knote
  99 and
 100 .Fn KNOTE
 101 functions first appeared in
 102 .Fx 4.1 ,
 103 and then in
 104 .Nx 2.0 .
 105 .Sh AUTHORS
 106 The
 107 .Fn kqueue
 108 system was written by
 109 .An Jonathan Lemon Aq jlemon@FreeBSD.org .