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