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