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