1.\" 2.\" Copyright (c) 2004 Joseph Koshy 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.\" $FreeBSD: src/share/man/man9/EVENTHANDLER.9,v 1.4 2005/10/11 16:05:35 keramida Exp $ 27.\" 28.Dd March 31, 2007 29.Dt EVENTHANDLER 9 30.Os 31.Sh NAME 32.Nm EVENTHANDLER_DECLARE , 33.Nm EVENTHANDLER_INVOKE , 34.Nm EVENTHANDLER_REGISTER , 35.Nm EVENTHANDLER_DEREGISTER , 36.Nm eventhandler_register , 37.Nm eventhandler_deregister , 38.Nm eventhandler_find_list 39.Nd kernel event handling functions 40.Sh SYNOPSIS 41.In sys/eventhandler.h 42.Fn EVENTHANDLER_DECLARE name type 43.Fn EVENTHANDLER_INVOKE name ... 44.Ft eventhandler_tag 45.Fn EVENTHANDLER_REGISTER name func arg priority 46.Fn EVENTHANDLER_DEREGISTER name tag 47.Ft eventhandler_tag 48.Fo eventhandler_register 49.Fa "struct eventhandler_list *list" 50.Fa "const char *name" 51.Fa "void *func" 52.Fa "void *arg" 53.Fa "int priority" 54.Fc 55.Ft void 56.Fo eventhandler_deregister 57.Fa "struct eventhandler_list *list" 58.Fa "eventhandler_tag tag" 59.Fc 60.Ft "struct eventhandler_list *" 61.Fn eventhandler_find_list "const char *name" 62.Sh DESCRIPTION 63The 64.Nm 65mechanism provides a way for kernel subsystems to register interest in 66kernel events and have their callback functions invoked when these 67events occur. 68.Pp 69The normal way to use this subsystem is via the macro interface. 70The macros that can be used for working with event handlers and callback 71function lists are: 72.Bl -tag -width indent 73.It Fn EVENTHANDLER_DECLARE 74This macro declares an event handler named by argument 75.Fa name 76with callback functions of type 77.Fa type . 78.It Fn EVENTHANDLER_REGISTER 79This macro registers a callback function 80.Fa func 81with event handler 82.Fa name . 83When invoked, function 84.Fa func 85will be invoked with argument 86.Fa arg 87as its first parameter along with any additional parameters passed in 88via macro 89.Fn EVENTHANDLER_INVOKE 90(see below). 91Callback functions are invoked in order of priority. 92The relative priority of each callback among other callbacks 93associated with an event is given by argument 94.Fa priority , 95which is an integer ranging from 96.Dv EVENTHANDLER_PRI_FIRST 97(highest priority), to 98.Dv EVENTHANDLER_PRI_LAST 99(lowest priority). 100The symbol 101.Dv EVENTHANDLER_PRI_ANY 102may be used if the handler does not have a specific priority 103associated with it. 104If registration is successful, 105.Fn EVENTHANDLER_REGISTER 106returns a cookie of type 107.Vt eventhandler_tag . 108.It Fn EVENTHANDLER_DEREGISTER 109This macro removes a previously registered callback associated with tag 110.Fa tag 111from the event handler named by argument 112.Fa name . 113.It Fn EVENTHANDLER_INVOKE 114This macro is used to invoke all the callbacks associated with event 115handler 116.Fa name . 117This macro is a variadic one. 118Additional arguments to the macro after the 119.Fa name 120parameter are passed as the second and subsequent arguments to each 121registered callback function. 122.El 123.Pp 124The macros are implemented using the following functions: 125.Bl -tag -width indent 126.It Fn eventhandler_register 127The 128.Fn eventhandler_register 129function is used to register a callback with a given event. 130The arguments expected by this function are: 131.Bl -tag -width ".Fa priority" 132.It Fa list 133A pointer to an existing event handler list, or 134.Dv NULL . 135If 136.Fa list 137is 138.Dv NULL , 139the event handler list corresponding to argument 140.Fa name 141is used. 142.It Fa name 143The name of the event handler list. 144.It Fa func 145A pointer to a callback function. 146Argument 147.Fa arg 148is passed to the callback function 149.Fa func 150as its first argument when it is invoked. 151.It Fa priority 152The relative priority of this callback among all the callbacks 153registered for this event. 154Valid values are those in the range 155.Dv EVENTHANDLER_PRI_FIRST 156to 157.Dv EVENTHANDLER_PRI_LAST . 158.El 159.Pp 160The 161.Fn eventhandler_register 162function returns a 163.Fa tag 164that can later be used with 165.Fn eventhandler_deregister 166to remove the particular callback function. 167.It Fn eventhandler_deregister 168The 169.Fn eventhandler_deregister 170function removes the callback associated with tag 171.Fa tag 172from the event handler list pointed to by 173.Fa list . 174This function is safe to call from inside an event handler 175callback. 176.It Fn eventhandler_find_list 177The 178.Fn eventhandler_find_list 179function returns a pointer to event handler list structure corresponding 180to event 181.Fa name . 182.El 183.Ss Kernel Event Handlers 184The following event handlers are present in the kernel: 185.Bl -tag -width indent 186.It Vt acpi_sleep_event 187Callbacks invoked when the system is being sent to sleep. 188.It Vt acpi_wakeup_event 189Callbacks invoked when the system is being woken up. 190.It Vt dev_clone 191Callbacks invoked when a new entry is created under 192.Pa /dev . 193.It Vt ifaddr_event 194Callbacks invoked when an address is set up on a network interface. 195.It Vt if_clone_event 196Callbacks invoked when an interface is cloned. 197.It Vt ifnet_attach_event 198Callbacks invoked when a new network interface appears. 199.It Vt ifnet_detach_event 200Callbacks invoked when a network interface is removed. 201.It Vt power_profile_change 202Callbacks invoked when the power profile of the system changes. 203.It Vt shutdown_pre_sync 204Callbacks invoked at shutdown time, before file systems are synchronized. 205.It Vt shutdown_post_sync 206Callbacks invoked at shutdown time, after all file systems are synchronized. 207.It Vt shutdown_final 208Callbacks invoked just before halting the system. 209.El 210.Sh RETURN VALUES 211The macro 212.Fn EVENTHANDLER_REGISTER 213and function 214.Fn eventhandler_register 215return a cookie of type 216.Vt eventhandler_tag , 217which may be used in a subsequent call to 218.Fn EVENTHANDLER_DEREGISTER 219or 220.Fn eventhandler_deregister . 221.Pp 222The 223.Fn eventhandler_find_list 224function 225returns a pointer to an event handler list corresponding to parameter 226.Fa name , 227or 228.Dv NULL 229if no such list was found. 230.Sh HISTORY 231The 232.Nm 233facility first appeared in 234.Fx 4.0 . 235.Sh AUTHORS 236This manual page was written by 237.An Joseph Koshy Aq Mt jkoshy@FreeBSD.org . 238