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