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 November 23, 2004 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. 64.Pp 65The macro 66.Fn EVENTHANDLER_DECLARE 67declares an event handler named by argument 68.Fa name 69with callback functions of type 70.Fa type . 71.Pp 72The macro 73.Fn EVENTHANDLER_REGISTER 74registers a callback function 75.Fa func 76with event handler 77.Fa name . 78When invoked, function 79.Fa func 80will be invoked with argument 81.Fa arg 82as its first parameter along with any additional parameters passed in 83via macro 84.Fn EVENTHANDLER_INVOKE 85(see below). 86Callback functions are invoked in order of priority. 87The relative priority of this callback among other callbacks 88associated with this event is given by argument 89.Fa priority , 90which is an integer ranging from 91.Dv EVENTHANDLER_PRI_FIRST 92(highest priority), to 93.Dv EVENTHANDLER_PRI_LAST 94(lowest priority). 95The symbol 96.Dv EVENTHANDLER_PRI_ANY 97may be used if the handler does not have a specific priority 98associated with it. 99If registration is successful, 100.Fn EVENTHANDLER_REGISTER 101returns a cookie of type 102.Vt eventhandler_tag . 103.Pp 104The macro 105.Fn EVENTHANDLER_DEREGISTER 106removes a previously registered callback associated with 107tag 108.Fa tag 109from the event handler named by argument 110.Fa name . 111.Pp 112The macro 113.Fn EVENTHANDLER_INVOKE 114is used to invoke all the callbacks associated with event handler 115.Fa name . 116This macro is a variadic one. 117Additional arguments to the macro after the 118.Fa name 119parameter are passed as the second and subsequent arguments to each 120registered callback function. 121.Pp 122The macros are implemented using the following functions: 123.Pp 124The function 125.Fn eventhandler_register 126is used to register a callback with a given event. 127The argument 128.Fa list 129is pointer to an existing event handler list, or 130.Dv NULL . 131If argument 132.Fa list 133is 134.Dv NULL , 135the event handler list corresponding to argument 136.Fa name 137is used. 138Argument 139.Fa func 140is a pointer to a callback function. 141Argument 142.Fa arg 143is a passed in to callback function 144.Fa func 145as its first argument when it is invoked. 146Argument 147.Fa priority 148ranges from 149.Dv EVENTHANDLER_PRI_FIRST 150to 151.Dv EVENTHANDLER_PRI_LAST , 152and determines the relative priority of this callback among all the 153callbacks registered for this event. 154.Pp 155Function 156.Fn eventhandler_deregister 157removes the callback associated with tag 158.Fa tag 159from the event handler list pointed to by 160.Fa list . 161This function is safe to call from inside an event handler 162callback. 163.Pp 164Function 165.Fn eventhandler_find_list 166returns a pointer to event handler list structure corresponding to 167event 168.Fa name . 169.Pp 170Function 171.Fn eventhandler_prune_list 172removes all deregistered callbacks from the event list 173.Fa list . 174.Ss Kernel Event Handlers 175The following event handlers are present in the kernel: 176.Bl -tag -width indent 177.It Vt acpi_sleep_event 178Callbacks invoked when the system is being sent to sleep. 179.It Vt acpi_wakeup_event 180Callbacks invoked when the system is being woken up. 181.It Vt dev_clone 182Callbacks invoked when a new entry is created under 183.Pa /dev . 184.It Vt ifaddr_event 185Callbacks invoked when an address is set up on a network interface. 186.It Vt if_clone_event 187Callbacks invoked when an interface is cloned. 188.It Vt ifnet_arrival_event 189Callbacks invoked when a new network interface appears. 190.It Vt ifnet_departure_event 191Callbacks invoked when a network interface is taken down. 192.It Vt power_profile_change 193Callbacks invoked when the power profile of the system changes. 194.It Vt process_exec 195Callbacks invoked when a process performs an 196.Fn exec 197operation. 198.It Vt process_exit 199Callbacks invoked when a process exits. 200.It Vt process_fork 201Callbacks invoked when a process forks a child. 202.It Vt shutdown_pre_sync 203Callbacks invoked at shutdown time, before file systems are synchronized. 204.It Vt shutdown_post_sync 205Callbacks invoked at shutdown time, after all file systems are synchronized. 206.It Vt shutdown_final 207Callbacks invoked just before halting the system. 208.It Vt vm_lowmem 209Callbacks invoked when virtual memory is low. 210.It Vt watchdog_list 211Callbacks invoked when the system watchdog timer is reinitialized. 212.El 213.Sh RETURN VALUES 214The macro 215.Fn EVENTHANDLER_REGISTER 216and function 217.Fn eventhandler_register 218return a cookie of type 219.Vt eventhandler_tag , 220which may be used in a subsequent call to 221.Fn EVENTHANDLER_DEREGISTER 222or 223.Fn eventhandler_deregister . 224.Pp 225Function 226.Fn eventhandler_find_list 227returns a pointer to an event handler list corresponding to parameter 228.Fa name , 229or 230.Dv NULL 231if no such list was found. 232.Sh HISTORY 233The 234.Nm 235facility first appeared in 236.Fx 4.0 . 237.Sh AUTHORS 238This manual page was written by 239.An Joseph Koshy Aq jkoshy@FreeBSD.org . 240