share/man/man9/EVENTHANDLER.9

   1 .\"
   2 .\" Copyright (c) 2004 Joseph Koshy
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD: src/share/man/man9/EVENTHANDLER.9,v 1.4 2005/10/11 16:05:35 keramida Exp $
  27 .\" $DragonFly: src/share/man/man9/EVENTHANDLER.9,v 1.1 2007/03/31 11:21:47 swildner Exp $
  28 .\"
  29 .Dd March 31, 2007
  30 .Dt EVENTHANDLER 9
  31 .Os
  32 .Sh NAME
  33 .Nm EVENTHANDLER_DECLARE ,
  34 .Nm EVENTHANDLER_INVOKE ,
  35 .Nm EVENTHANDLER_REGISTER ,
  36 .Nm EVENTHANDLER_DEREGISTER ,
  37 .Nm eventhandler_register ,
  38 .Nm eventhandler_deregister ,
  39 .Nm eventhandler_find_list
  40 .Nd kernel event handling functions
  41 .Sh SYNOPSIS
  42 .In sys/eventhandler.h
  43 .Fn EVENTHANDLER_DECLARE name type
  44 .Fn EVENTHANDLER_INVOKE name ...
  45 .Ft eventhandler_tag
  46 .Fn EVENTHANDLER_REGISTER name func arg priority
  47 .Fn EVENTHANDLER_DEREGISTER name tag
  48 .Ft eventhandler_tag
  49 .Fo eventhandler_register
  50 .Fa "struct eventhandler_list *list"
  51 .Fa "const char *name"
  52 .Fa "void *func"
  53 .Fa "void *arg"
  54 .Fa "int priority"
  55 .Fc
  56 .Ft void
  57 .Fo eventhandler_deregister
  58 .Fa "struct eventhandler_list *list"
  59 .Fa "eventhandler_tag tag"
  60 .Fc
  61 .Ft "struct eventhandler_list *"
  62 .Fn eventhandler_find_list "const char *name"
  63 .Sh DESCRIPTION
  64 The
  65 .Nm
  66 mechanism provides a way for kernel subsystems to register interest in
  67 kernel events and have their callback functions invoked when these
  68 events occur.
  69 .Pp
  70 The normal way to use this subsystem is via the macro interface.
  71 The macros that can be used for working with event handlers and callback
  72 function lists are:
  73 .Bl -tag -width indent
  74 .It Fn EVENTHANDLER_DECLARE
  75 This macro declares an event handler named by argument
  76 .Fa name
  77 with callback functions of type
  78 .Fa type .
  79 .It Fn EVENTHANDLER_REGISTER
  80 This macro registers a callback function
  81 .Fa func
  82 with event handler
  83 .Fa name .
  84 When invoked, function
  85 .Fa func
  86 will be invoked with argument
  87 .Fa arg
  88 as its first parameter along with any additional parameters passed in
  89 via macro
  90 .Fn EVENTHANDLER_INVOKE
  91 (see below).
  92 Callback functions are invoked in order of priority.
  93 The relative priority of each callback among other callbacks
  94 associated with an event is given by argument
  95 .Fa priority ,
  96 which is an integer ranging from
  97 .Dv EVENTHANDLER_PRI_FIRST
  98 (highest priority), to
  99 .Dv EVENTHANDLER_PRI_LAST
 100 (lowest priority).
 101 The symbol
 102 .Dv EVENTHANDLER_PRI_ANY
 103 may be used if the handler does not have a specific priority
 104 associated with it.
 105 If registration is successful,
 106 .Fn EVENTHANDLER_REGISTER
 107 returns a cookie of type
 108 .Vt eventhandler_tag .
 109 .It Fn EVENTHANDLER_DEREGISTER
 110 This macro removes a previously registered callback associated with tag
 111 .Fa tag
 112 from the event handler named by argument
 113 .Fa name .
 114 .It Fn EVENTHANDLER_INVOKE
 115 This macro is used to invoke all the callbacks associated with event
 116 handler
 117 .Fa name .
 118 This macro is a variadic one.
 119 Additional arguments to the macro after the
 120 .Fa name
 121 parameter are passed as the second and subsequent arguments to each
 122 registered callback function.
 123 .El
 124 .Pp
 125 The macros are implemented using the following functions:
 126 .Bl -tag -width indent
 127 .It Fn eventhandler_register
 128 The
 129 .Fn eventhandler_register
 130 function is used to register a callback with a given event.
 131 The arguments expected by this function are:
 132 .Bl -tag -width ".Fa priority"
 133 .It Fa list
 134 A pointer to an existing event handler list, or
 135 .Dv NULL .
 136 If
 137 .Fa list
 138 is
 139 .Dv NULL ,
 140 the event handler list corresponding to argument
 141 .Fa name
 142 is used.
 143 .It Fa name
 144 The name of the event handler list.
 145 .It Fa func
 146 A pointer to a callback function.
 147 Argument
 148 .Fa arg
 149 is passed to the callback function
 150 .Fa func
 151 as its first argument when it is invoked.
 152 .It Fa priority
 153 The relative priority of this callback among all the callbacks
 154 registered for this event.
 155 Valid values are those in the range
 156 .Dv EVENTHANDLER_PRI_FIRST
 157 to
 158 .Dv EVENTHANDLER_PRI_LAST .
 159 .El
 160 .Pp
 161 The
 162 .Fn eventhandler_register
 163 function returns a
 164 .Fa tag
 165 that can later be used with
 166 .Fn eventhandler_deregister
 167 to remove the particular callback function.
 168 .It Fn eventhandler_deregister
 169 The
 170 .Fn eventhandler_deregister
 171 function removes the callback associated with tag
 172 .Fa tag
 173 from the event handler list pointed to by
 174 .Fa list .
 175 This function is safe to call from inside an event handler
 176 callback.
 177 .It Fn eventhandler_find_list
 178 The
 179 .Fn eventhandler_find_list
 180 function returns a pointer to event handler list structure corresponding
 181 to event
 182 .Fa name .
 183 .El
 184 .Ss Kernel Event Handlers
 185 The following event handlers are present in the kernel:
 186 .Bl -tag -width indent
 187 .It Vt acpi_sleep_event
 188 Callbacks invoked when the system is being sent to sleep.
 189 .It Vt acpi_wakeup_event
 190 Callbacks invoked when the system is being woken up.
 191 .It Vt dev_clone
 192 Callbacks invoked when a new entry is created under
 193 .Pa /dev .
 194 .It Vt ifaddr_event
 195 Callbacks invoked when an address is set up on a network interface.
 196 .It Vt if_clone_event
 197 Callbacks invoked when an interface is cloned.
 198 .It Vt ifnet_attach_event
 199 Callbacks invoked when a new network interface appears.
 200 .It Vt ifnet_detach_event
 201 Callbacks invoked when a network interface is removed.
 202 .It Vt power_profile_change
 203 Callbacks invoked when the power profile of the system changes.
 204 .It Vt shutdown_pre_sync
 205 Callbacks invoked at shutdown time, before file systems are synchronized.
 206 .It Vt shutdown_post_sync
 207 Callbacks invoked at shutdown time, after all file systems are synchronized.
 208 .It Vt shutdown_final
 209 Callbacks invoked just before halting the system.
 210 .El
 211 .Sh RETURN VALUES
 212 The macro
 213 .Fn EVENTHANDLER_REGISTER
 214 and function
 215 .Fn eventhandler_register
 216 return a cookie of type
 217 .Vt eventhandler_tag ,
 218 which may be used in a subsequent call to
 219 .Fn EVENTHANDLER_DEREGISTER
 220 or
 221 .Fn eventhandler_deregister .
 222 .Pp
 223 The
 224 .Fn eventhandler_find_list
 225 function
 226 returns a pointer to an event handler list corresponding to parameter
 227 .Fa name ,
 228 or
 229 .Dv NULL
 230 if no such list was found.
 231 .Sh HISTORY
 232 The
 233 .Nm
 234 facility first appeared in
 235 .Fx 4.0 .
 236 .Sh AUTHORS
 237 This manual page was written by
 238 .An Joseph Koshy Aq jkoshy@FreeBSD.org .