1 .\" Copyright (c) 2004 Joseph Koshy
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
31 .Nd kernel event handling functions
33 .In sys/eventhandler.h
34 .Fn EVENTHANDLER_DECLARE name type
35 .Fn EVENTHANDLER_INVOKE name ...
37 .Fn EVENTHANDLER_REGISTER name func arg priority
38 .Fn EVENTHANDLER_DEREGISTER name tag
40 .Fo eventhandler_register
41 .Fa "struct eventhandler_list *list"
42 .Fa "const char *name"
48 .Fo eventhandler_deregister
49 .Fa "struct eventhandler_list *list"
50 .Fa "eventhandler_tag tag"
52 .Ft "struct eventhandler_list *"
53 .Fn eventhandler_find_list "const char *name"
55 .Fn eventhandler_prune_list "struct eventhandler_list *list"
59 mechanism provides a way for kernel subsystems to register interest in
60 kernel events and have their callback functions invoked when these
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
66 .Bl -tag -width indent
67 .It Fn EVENTHANDLER_DECLARE
68 This macro declares an event handler named by argument
70 with callback functions of type
72 .It Fn EVENTHANDLER_REGISTER
73 This macro registers a callback function
77 When invoked, function
79 will be invoked with argument
81 as its first parameter along with any additional parameters passed in
83 .Fn EVENTHANDLER_INVOKE
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
89 which is an integer ranging from
90 .Dv EVENTHANDLER_PRI_FIRST
91 (highest priority), to
92 .Dv EVENTHANDLER_PRI_LAST
95 .Dv EVENTHANDLER_PRI_ANY
96 may be used if the handler does not have a specific priority
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
105 from the event handler named by argument
107 .It Fn EVENTHANDLER_INVOKE
108 This macro is used to invoke all the callbacks associated with event
111 This macro is a variadic one.
112 Additional arguments to the macro after the
114 parameter are passed as the second and subsequent arguments to each
115 registered callback function.
118 The macros are implemented using the following functions:
119 .Bl -tag -width indent
120 .It Fn eventhandler_register
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"
127 A pointer to an existing event handler list, or
133 the event handler list corresponding to argument
137 The name of the event handler list.
139 A pointer to a callback function.
142 is passed to the callback function
144 as its first argument when it is invoked.
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
151 .Dv EVENTHANDLER_PRI_LAST .
155 .Fn eventhandler_register
158 that can later be used with
159 .Fn eventhandler_deregister
160 to remove the particular callback function.
161 .It Fn eventhandler_deregister
163 .Fn eventhandler_deregister
164 function removes the callback associated with tag
166 from the event handler list pointed to by
168 This function is safe to call from inside an event handler
170 .It Fn eventhandler_find_list
172 .Fn eventhandler_find_list
173 function returns a pointer to event handler list structure corresponding
176 .It Fn eventhandler_prune_list
178 .Fn eventhandler_prune_list
179 function removes all deregistered callbacks from the event list
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 app_coredump_start
190 Callbacks invoked at start of application core dump.
191 .It Vt app_coredump_progress
192 Callbacks invoked during progress of application core dump.
193 .It Vt app_coredump_finish
194 Callbacks invoked at finish of application core dump.
195 .It Vt app_coredump_error
196 Callbacks invoked on error of application core dump.
198 Callbacks invoked when a BPF listener attaches to/detaches from network interface.
199 .It Vt cpufreq_levels_changed
200 Callback invoked when cpu frequence levels have changed.
201 .It Vt cpufreq_post_change
202 Callback invoked after cpu frequence has changed.
203 .It Vt cpufreq_pre_change
204 Callback invoked before cpu frequence has changed
206 Callback invoked to poll for dcons changes.
208 Callbacks invoked when a new entry is created under
210 .It Vt group_attach_event
211 Callback invoked when an interfance has been added to an interface group.
212 .It Vt group_change_event
213 Callback invoked when an change has been made to an interface group.
214 .It Vt group_detach_event
215 Callback invoked when an interfance has been removed from an interface group.
217 Callbacks invoked when an address is set up on a network interface.
218 .It Vt if_clone_event
219 Callbacks invoked when an interface is cloned.
220 .It Vt iflladdr_event
221 Callback invoked when an if link layer address event has happened.
222 .It Vt ifnet_arrival_event
223 Callbacks invoked when a new network interface appears.
224 .It Vt ifnet_departure_event
225 Callbacks invoked when a network interface is taken down.
226 .It Vt ifnet_link_event
227 Callback invoked when an interfance link event has happened.
229 Callbacks invoked after a linker file has been loaded.
231 Callbacks invoked after a linker file has been successfully unloaded.
232 .It Vt kld_unload_try
233 Callbacks invoked before a linker file is about to be unloaded.
234 These callbacks may be used to return an error and prevent the unload from
237 Callback invoked when an link layer event has happened.
238 .It Vt nmbclusters_change
239 Callback invoked when the number of mbuf clusters has changed.
241 Callback invoked when the number of mbufs has changed.
242 .It Vt maxsockets_change
243 Callback invoked when the maximum number of sockets has changed.
245 Callback invoked when root has been mounted.
246 .It Vt power_profile_change
247 Callbacks invoked when the power profile of the system changes.
249 Callback invoked when the system has resumed.
251 Callback invoked just before the system is suspended.
253 Callback invoked when a process is created.
255 Callback invoked when a process is destroyed.
257 Callbacks invoked when a process performs an
261 Callbacks invoked when a process exits.
263 Callback invoked when a process memory is destroyed.
264 This is never called.
266 Callbacks invoked when a process forks a child.
268 Callback invoked when a process is initalized.
269 .It Vt random_adaptor_attach
270 Callback invoked when a new random module has been loaded.
271 .It Vt register_framebuffer
272 Callback invoked when a new frame buffer is registered.
273 .It Vt route_redirect_event
274 Callback invoked when a route gets redirected to a new location.
275 .It Vt shutdown_pre_sync
276 Callbacks invoked at shutdown time, before file systems are synchronized.
277 .It Vt shutdown_post_sync
278 Callbacks invoked at shutdown time, after all file systems are synchronized.
279 .It Vt shutdown_final
280 Callbacks invoked just before halting the system.
281 .It Vt tcp_offload_listen_start
282 Callback invoked for TCP Offload to start listening for new connections.
283 .It Vt tcp_offload_listen_stop
284 Callback invoked ror TCP Offload to stop listening for new connections.
286 Callback invoked when a thread object is created.
288 Callback invoked when a thread object is destroyed.
290 Callback invoked when a thread object is initalized.
292 Callback invoked when a thread object is deinitalized.
293 .It Vt usb_dev_configured
294 Callback invoked when a USB device is configured
295 .It Vt unregister_framebuffer
296 Callback invoked when a frame buffer is deregistered.
298 Callback invoked when a file system is mounted.
300 Callback invoked when a file system is unmounted.
302 Callback invoked when the vlan configuration has changed.
304 Callback invoked when a vlan is destroyed.
306 Callbacks invoked when virtual memory is low.
308 Callbacks invoked when the system watchdog timer is reinitialized.
312 .Fn EVENTHANDLER_REGISTER
314 .Fn eventhandler_register
315 return a cookie of type
316 .Vt eventhandler_tag ,
317 which may be used in a subsequent call to
318 .Fn EVENTHANDLER_DEREGISTER
320 .Fn eventhandler_deregister .
323 .Fn eventhandler_find_list
325 returns a pointer to an event handler list corresponding to parameter
329 if no such list was found.
333 facility first appeared in
336 This manual page was written by
337 .An Joseph Koshy Aq Mt jkoshy@FreeBSD.org .