share/man/man9/EVENTHANDLER.9

   1 .\" Copyright (c) 2004 Joseph Koshy
   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 .\" $FreeBSD$
  25 .\"
  26 .Dd August 1, 2013
  27 .Dt EVENTHANDLER 9
  28 .Os
  29 .Sh NAME
  30 .Nm EVENTHANDLER
  31 .Nd kernel event handling functions
  32 .Sh SYNOPSIS
  33 .In sys/eventhandler.h
  34 .Fn EVENTHANDLER_DECLARE name type
  35 .Fn EVENTHANDLER_INVOKE name ...
  36 .Ft eventhandler_tag
  37 .Fn EVENTHANDLER_REGISTER name func arg priority
  38 .Fn EVENTHANDLER_DEREGISTER name tag
  39 .Ft eventhandler_tag
  40 .Fo eventhandler_register
  41 .Fa "struct eventhandler_list *list"
  42 .Fa "const char *name"
  43 .Fa "void *func"
  44 .Fa "void *arg"
  45 .Fa "int priority"
  46 .Fc
  47 .Ft void
  48 .Fo eventhandler_deregister
  49 .Fa "struct eventhandler_list *list"
  50 .Fa "eventhandler_tag tag"
  51 .Fc
  52 .Ft "struct eventhandler_list *"
  53 .Fn eventhandler_find_list "const char *name"
  54 .Ft void
  55 .Fn eventhandler_prune_list "struct eventhandler_list *list"
  56 .Sh DESCRIPTION
  57 The
  58 .Nm
  59 mechanism provides a way for kernel subsystems to register interest in
  60 kernel events and have their callback functions invoked when these
  61 events occur.
  62 .Pp
  63 The normal way to use this subsystem is via the macro interface.
  64 The macros that can be used for working with event handlers and callback
  65 function lists are:
  66 .Bl -tag -width indent
  67 .It Fn EVENTHANDLER_DECLARE
  68 This macro declares an event handler named by argument
  69 .Fa name
  70 with callback functions of type
  71 .Fa type .
  72 .It Fn EVENTHANDLER_REGISTER
  73 This macro registers a callback function
  74 .Fa func
  75 with event handler
  76 .Fa name .
  77 When invoked, function
  78 .Fa func
  79 will be invoked with argument
  80 .Fa arg
  81 as its first parameter along with any additional parameters passed in
  82 via macro
  83 .Fn EVENTHANDLER_INVOKE
  84 (see below).
  85 Callback functions are invoked in order of priority.
  86 The relative priority of each callback among other callbacks
  87 associated with an event is given by argument
  88 .Fa priority ,
  89 which is an integer ranging from
  90 .Dv EVENTHANDLER_PRI_FIRST
  91 (highest priority), to
  92 .Dv EVENTHANDLER_PRI_LAST
  93 (lowest priority).
  94 The symbol
  95 .Dv EVENTHANDLER_PRI_ANY
  96 may be used if the handler does not have a specific priority
  97 associated with it.
  98 If registration is successful,
  99 .Fn EVENTHANDLER_REGISTER
 100 returns a cookie of type
 101 .Vt eventhandler_tag .
 102 .It Fn EVENTHANDLER_DEREGISTER
 103 This macro removes a previously registered callback associated with tag
 104 .Fa tag
 105 from the event handler named by argument
 106 .Fa name .
 107 .It Fn EVENTHANDLER_INVOKE
 108 This macro is used to invoke all the callbacks associated with event
 109 handler
 110 .Fa name .
 111 This macro is a variadic one.
 112 Additional arguments to the macro after the
 113 .Fa name
 114 parameter are passed as the second and subsequent arguments to each
 115 registered callback function.
 116 .El
 117 .Pp
 118 The macros are implemented using the following functions:
 119 .Bl -tag -width indent
 120 .It Fn eventhandler_register
 121 The
 122 .Fn eventhandler_register
 123 function is used to register a callback with a given event.
 124 The arguments expected by this function are:
 125 .Bl -tag -width ".Fa priority"
 126 .It Fa list
 127 A pointer to an existing event handler list, or
 128 .Dv NULL .
 129 If
 130 .Fa list
 131 is
 132 .Dv NULL ,
 133 the event handler list corresponding to argument
 134 .Fa name
 135 is used.
 136 .It Fa name
 137 The name of the event handler list.
 138 .It Fa func
 139 A pointer to a callback function.
 140 Argument
 141 .Fa arg
 142 is passed to the callback function
 143 .Fa func
 144 as its first argument when it is invoked.
 145 .It Fa priority
 146 The relative priority of this callback among all the callbacks
 147 registered for this event.
 148 Valid values are those in the range
 149 .Dv EVENTHANDLER_PRI_FIRST
 150 to
 151 .Dv EVENTHANDLER_PRI_LAST .
 152 .El
 153 .Pp
 154 The
 155 .Fn eventhandler_register
 156 function returns a
 157 .Fa tag
 158 that can later be used with
 159 .Fn eventhandler_deregister
 160 to remove the particular callback function.
 161 .It Fn eventhandler_deregister
 162 The
 163 .Fn eventhandler_deregister
 164 function removes the callback associated with tag
 165 .Fa tag
 166 from the event handler list pointed to by
 167 .Fa list .
 168 This function is safe to call from inside an event handler
 169 callback.
 170 .It Fn eventhandler_find_list
 171 The
 172 .Fn eventhandler_find_list
 173 function returns a pointer to event handler list structure corresponding
 174 to event
 175 .Fa name .
 176 .It Fn eventhandler_prune_list
 177 The
 178 .Fn eventhandler_prune_list
 179 function removes all deregistered callbacks from the event list
 180 .Fa list .
 181 .El
 182 .Ss Kernel Event Handlers
 183 The following event handlers are present in the kernel:
 184 .Bl -tag -width indent
 185 .It Vt acpi_sleep_event
 186 Callbacks invoked when the system is being sent to sleep.
 187 .It Vt acpi_wakeup_event
 188 Callbacks invoked when the system is being woken up.
 189 .It Vt dev_clone
 190 Callbacks invoked when a new entry is created under
 191 .Pa /dev .
 192 .It Vt ifaddr_event
 193 Callbacks invoked when an address is set up on a network interface.
 194 .It Vt if_clone_event
 195 Callbacks invoked when an interface is cloned.
 196 .It Vt ifnet_arrival_event
 197 Callbacks invoked when a new network interface appears.
 198 .It Vt ifnet_departure_event
 199 Callbacks invoked when a network interface is taken down.
 200 .It Vt bpf_track
 201 Callbacks invoked when a BPF listener attaches to/detaches from network interface.
 202 .It Vt kld_load
 203 Callbacks invoked after a linker file has been loaded.
 204 .It Vt kld_unload
 205 Callbacks invoked after a linker file has been successfully unloaded.
 206 .It Vt kld_unload_try
 207 Callbacks invoked before a linker file is about to be unloaded.
 208 These callbacks may be used to return an error and prevent the unload from
 209 proceeding.
 210 .It Vt power_profile_change
 211 Callbacks invoked when the power profile of the system changes.
 212 .It Vt process_exec
 213 Callbacks invoked when a process performs an
 214 .Fn exec
 215 operation.
 216 .It Vt process_exit
 217 Callbacks invoked when a process exits.
 218 .It Vt process_fork
 219 Callbacks invoked when a process forks a child.
 220 .It Vt shutdown_pre_sync
 221 Callbacks invoked at shutdown time, before file systems are synchronized.
 222 .It Vt shutdown_post_sync
 223 Callbacks invoked at shutdown time, after all file systems are synchronized.
 224 .It Vt shutdown_final
 225 Callbacks invoked just before halting the system.
 226 .It Vt vm_lowmem
 227 Callbacks invoked when virtual memory is low.
 228 .It Vt watchdog_list
 229 Callbacks invoked when the system watchdog timer is reinitialized.
 230 .El
 231 .Sh RETURN VALUES
 232 The macro
 233 .Fn EVENTHANDLER_REGISTER
 234 and function
 235 .Fn eventhandler_register
 236 return a cookie of type
 237 .Vt eventhandler_tag ,
 238 which may be used in a subsequent call to
 239 .Fn EVENTHANDLER_DEREGISTER
 240 or
 241 .Fn eventhandler_deregister .
 242 .Pp
 243 The
 244 .Fn eventhandler_find_list
 245 function
 246 returns a pointer to an event handler list corresponding to parameter
 247 .Fa name ,
 248 or
 249 .Dv NULL
 250 if no such list was found.
 251 .Sh HISTORY
 252 The
 253 .Nm
 254 facility first appeared in
 255 .Fx 4.0 .
 256 .Sh AUTHORS
 257 This manual page was written by
 258 .An Joseph Koshy Aq jkoshy@FreeBSD.org .