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