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 March 27, 2017
  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_DEFINE name func arg priority
  36 .Fn EVENTHANDLER_INVOKE name ...
  37 .Ft eventhandler_tag
  38 .Fn EVENTHANDLER_REGISTER name func arg priority
  39 .Fn EVENTHANDLER_DEREGISTER name tag
  40 .Ft eventhandler_tag
  41 .Fo eventhandler_register
  42 .Fa "struct eventhandler_list *list"
  43 .Fa "const char *name"
  44 .Fa "void *func"
  45 .Fa "void *arg"
  46 .Fa "int priority"
  47 .Fc
  48 .Ft void
  49 .Fo eventhandler_deregister
  50 .Fa "struct eventhandler_list *list"
  51 .Fa "eventhandler_tag tag"
  52 .Fc
  53 .Ft "struct eventhandler_list *"
  54 .Fn eventhandler_find_list "const char *name"
  55 .Ft void
  56 .Fn eventhandler_prune_list "struct eventhandler_list *list"
  57 .Sh DESCRIPTION
  58 The
  59 .Nm
  60 mechanism provides a way for kernel subsystems to register interest in
  61 kernel events and have their callback functions invoked when these
  62 events occur.
  63 .Pp
  64 Callback functions are invoked in order of priority.
  65 The relative priority of each callback among other callbacks
  66 associated with an event is given by argument
  67 .Fa priority ,
  68 which is an integer ranging from
  69 .Dv EVENTHANDLER_PRI_FIRST
  70 (highest priority), to
  71 .Dv EVENTHANDLER_PRI_LAST
  72 (lowest priority).
  73 The symbol
  74 .Dv EVENTHANDLER_PRI_ANY
  75 may be used if the handler does not have a specific priority
  76 associated with it.
  77 .Pp
  78 The normal way to use this subsystem is via the macro interface.
  79 The macros that can be used for working with event handlers and callback
  80 function lists are:
  81 .Bl -tag -width indent
  82 .It Fn EVENTHANDLER_DECLARE
  83 This macro declares an event handler named by argument
  84 .Fa name
  85 with callback functions of type
  86 .Fa type .
  87 .It Fn EVENTHANDLER_DEFINE
  88 This macro uses
  89 .Xr SYSINIT 9
  90 to register a callback function
  91 .Fa func
  92 with event handler
  93 .Fa name .
  94 When invoked, function
  95 .Fa func
  96 will be invoked with argument
  97 .Fa arg
  98 as its first parameter along with any additional parameters passed in
  99 via macro
 100 .Fn EVENTHANDLER_INVOKE
 101 (see below).
 102 .It Fn EVENTHANDLER_REGISTER
 103 This macro registers a callback function
 104 .Fa func
 105 with event handler
 106 .Fa name .
 107 When invoked, function
 108 .Fa func
 109 will be invoked with argument
 110 .Fa arg
 111 as its first parameter along with any additional parameters passed in
 112 via macro
 113 .Fn EVENTHANDLER_INVOKE
 114 (see below).
 115 If registration is successful,
 116 .Fn EVENTHANDLER_REGISTER
 117 returns a cookie of type
 118 .Vt eventhandler_tag .
 119 .It Fn EVENTHANDLER_DEREGISTER
 120 This macro removes a previously registered callback associated with tag
 121 .Fa tag
 122 from the event handler named by argument
 123 .Fa name .
 124 .It Fn EVENTHANDLER_INVOKE
 125 This macro is used to invoke all the callbacks associated with event
 126 handler
 127 .Fa name .
 128 This macro is a variadic one.
 129 Additional arguments to the macro after the
 130 .Fa name
 131 parameter are passed as the second and subsequent arguments to each
 132 registered callback function.
 133 .El
 134 .Pp
 135 The macros are implemented using the following functions:
 136 .Bl -tag -width indent
 137 .It Fn eventhandler_register
 138 The
 139 .Fn eventhandler_register
 140 function is used to register a callback with a given event.
 141 The arguments expected by this function are:
 142 .Bl -tag -width ".Fa priority"
 143 .It Fa list
 144 A pointer to an existing event handler list, or
 145 .Dv NULL .
 146 If
 147 .Fa list
 148 is
 149 .Dv NULL ,
 150 the event handler list corresponding to argument
 151 .Fa name
 152 is used.
 153 .It Fa name
 154 The name of the event handler list.
 155 .It Fa func
 156 A pointer to a callback function.
 157 Argument
 158 .Fa arg
 159 is passed to the callback function
 160 .Fa func
 161 as its first argument when it is invoked.
 162 .It Fa priority
 163 The relative priority of this callback among all the callbacks
 164 registered for this event.
 165 Valid values are those in the range
 166 .Dv EVENTHANDLER_PRI_FIRST
 167 to
 168 .Dv EVENTHANDLER_PRI_LAST .
 169 .El
 170 .Pp
 171 The
 172 .Fn eventhandler_register
 173 function returns a
 174 .Fa tag
 175 that can later be used with
 176 .Fn eventhandler_deregister
 177 to remove the particular callback function.
 178 .It Fn eventhandler_deregister
 179 The
 180 .Fn eventhandler_deregister
 181 function removes the callback associated with tag
 182 .Fa tag
 183 from the event handler list pointed to by
 184 .Fa list .
 185 This function is safe to call from inside an event handler
 186 callback.
 187 .It Fn eventhandler_find_list
 188 The
 189 .Fn eventhandler_find_list
 190 function returns a pointer to event handler list structure corresponding
 191 to event
 192 .Fa name .
 193 .It Fn eventhandler_prune_list
 194 The
 195 .Fn eventhandler_prune_list
 196 function removes all deregistered callbacks from the event list
 197 .Fa list .
 198 .El
 199 .Ss Kernel Event Handlers
 200 The following event handlers are present in the kernel:
 201 .Bl -tag -width indent
 202 .It Vt acpi_sleep_event
 203 Callbacks invoked when the system is being sent to sleep.
 204 .It Vt acpi_wakeup_event
 205 Callbacks invoked when the system is being woken up.
 206 .It Vt app_coredump_start
 207 Callbacks invoked at start of application core dump.
 208 .It Vt app_coredump_progress
 209 Callbacks invoked during progress of application core dump.
 210 .It Vt app_coredump_finish
 211 Callbacks invoked at finish of application core dump.
 212 .It Vt app_coredump_error
 213 Callbacks invoked on error of application core dump.
 214 .It Vt bpf_track
 215 Callbacks invoked when a BPF listener attaches to/detaches from network interface.
 216 .It Vt cpufreq_levels_changed
 217 Callback invoked when cpu frequency levels have changed.
 218 .It Vt cpufreq_post_change
 219 Callback invoked after cpu frequency has changed.
 220 .It Vt cpufreq_pre_change
 221 Callback invoked before cpu frequency has changed.
 222 .It Vt dcons_poll
 223 Callback invoked to poll for dcons changes.
 224 .It Vt dev_clone
 225 Callbacks invoked when a new entry is created under
 226 .Pa /dev .
 227 .It Vt group_attach_event
 228 Callback invoked when an interfance has been added to an interface group.
 229 .It Vt group_change_event
 230 Callback invoked when an change has been made to an interface group.
 231 .It Vt group_detach_event
 232 Callback invoked when an interfance has been removed from an interface group.
 233 .It Vt ifaddr_event
 234 Callbacks invoked when an address is set up on a network interface.
 235 .It Vt if_clone_event
 236 Callbacks invoked when an interface is cloned.
 237 .It Vt iflladdr_event
 238 Callback invoked when an if link layer address event has happened.
 239 .It Vt ifnet_arrival_event
 240 Callbacks invoked when a new network interface appears.
 241 .It Vt ifnet_departure_event
 242 Callbacks invoked when a network interface is taken down.
 243 .It Vt ifnet_link_event
 244 Callback invoked when an interfance link event has happened.
 245 .It Vt kld_load
 246 Callbacks invoked after a linker file has been loaded.
 247 .It Vt kld_unload
 248 Callbacks invoked after a linker file has been successfully unloaded.
 249 .It Vt kld_unload_try
 250 Callbacks invoked before a linker file is about to be unloaded.
 251 These callbacks may be used to return an error and prevent the unload from
 252 proceeding.
 253 .It Vt lle_event
 254 Callback invoked when an link layer event has happened.
 255 .It Vt nmbclusters_change
 256 Callback invoked when the number of mbuf clusters has changed.
 257 .It Vt nmbufs_change
 258 Callback invoked when the number of mbufs has changed.
 259 .It Vt maxsockets_change
 260 Callback invoked when the maximum number of sockets has changed.
 261 .It Vt mountroot
 262 Callback invoked when root has been mounted.
 263 .It Vt power_profile_change
 264 Callbacks invoked when the power profile of the system changes.
 265 .It Vt power_resume
 266 Callback invoked when the system has resumed.
 267 .It Vt power_suspend
 268 Callback invoked just before the system is suspended.
 269 .It Vt process_ctor
 270 Callback invoked when a process is created.
 271 .It Vt process_dtor
 272 Callback invoked when a process is destroyed.
 273 .It Vt process_exec
 274 Callbacks invoked when a process performs an
 275 .Fn exec
 276 operation.
 277 .It Vt process_exit
 278 Callbacks invoked when a process exits.
 279 .It Vt process_fini
 280 Callback invoked when a process memory is destroyed.
 281 This is never called.
 282 .It Vt process_fork
 283 Callbacks invoked when a process forks a child.
 284 .It Vt process_init
 285 Callback invoked when a process is initalized.
 286 .It Vt random_adaptor_attach
 287 Callback invoked when a new random module has been loaded.
 288 .It Vt register_framebuffer
 289 Callback invoked when a new frame buffer is registered.
 290 .It Vt route_redirect_event
 291 Callback invoked when a route gets redirected to a new location.
 292 .It Vt shutdown_pre_sync
 293 Callbacks invoked at shutdown time, before file systems are synchronized.
 294 .It Vt shutdown_post_sync
 295 Callbacks invoked at shutdown time, after all file systems are synchronized.
 296 .It Vt shutdown_final
 297 Callbacks invoked just before halting the system.
 298 .It Vt tcp_offload_listen_start
 299 Callback invoked for TCP Offload to start listening for new connections.
 300 .It Vt tcp_offload_listen_stop
 301 Callback invoked ror TCP Offload to stop listening for new connections.
 302 .It Vt thread_ctor
 303 Callback invoked when a thread object is created.
 304 .It Vt thread_dtor
 305 Callback invoked when a thread object is destroyed.
 306 .It Vt thread_init
 307 Callback invoked when a thread object is initalized.
 308 .It Vt thread_fini
 309 Callback invoked when a thread object is deinitalized.
 310 .It Vt usb_dev_configured
 311 Callback invoked when a USB device is configured
 312 .It Vt unregister_framebuffer
 313 Callback invoked when a frame buffer is deregistered.
 314 .It Vt vfs_mounted
 315 Callback invoked when a file system is mounted.
 316 .It Vt vfs_unmounted
 317 Callback invoked when a file system is unmounted.
 318 .It Vt vlan_config
 319 Callback invoked when the vlan configuration has changed.
 320 .It Vt vlan_unconfig
 321 Callback invoked when a vlan is destroyed.
 322 .It Vt vm_lowmem
 323 Callbacks invoked when virtual memory is low.
 324 .It Vt watchdog_list
 325 Callbacks invoked when the system watchdog timer is reinitialized.
 326 .El
 327 .Sh RETURN VALUES
 328 The macro
 329 .Fn EVENTHANDLER_REGISTER
 330 and function
 331 .Fn eventhandler_register
 332 return a cookie of type
 333 .Vt eventhandler_tag ,
 334 which may be used in a subsequent call to
 335 .Fn EVENTHANDLER_DEREGISTER
 336 or
 337 .Fn eventhandler_deregister .
 338 .Pp
 339 The
 340 .Fn eventhandler_find_list
 341 function
 342 returns a pointer to an event handler list corresponding to parameter
 343 .Fa name ,
 344 or
 345 .Dv NULL
 346 if no such list was found.
 347 .Sh HISTORY
 348 The
 349 .Nm
 350 facility first appeared in
 351 .Fx 4.0 .
 352 .Sh AUTHORS
 353 This manual page was written by
 354 .An Joseph Koshy Aq Mt jkoshy@FreeBSD.org .