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.\" $DragonFly: src/share/man/man9/EVENTHANDLER.9,v 1.1 2007/03/31 11:21:47 swildner Exp $ 28.\" 29.Dd March 31, 2007 30.Dt EVENTHANDLER 9 31.Os 32.Sh NAME 33.Nm EVENTHANDLER_DECLARE , 34.Nm EVENTHANDLER_INVOKE , 35.Nm EVENTHANDLER_REGISTER , 36.Nm EVENTHANDLER_DEREGISTER , 37.Nm eventhandler_register , 38.Nm eventhandler_deregister , 39.Nm eventhandler_find_list 40.Nd kernel event handling functions 41.Sh SYNOPSIS 42.In sys/eventhandler.h 43.Fn EVENTHANDLER_DECLARE name type 44.Fn EVENTHANDLER_INVOKE name ... 45.Ft eventhandler_tag 46.Fn EVENTHANDLER_REGISTER name func arg priority 47.Fn EVENTHANDLER_DEREGISTER name tag 48.Ft eventhandler_tag 49.Fo eventhandler_register 50.Fa "struct eventhandler_list *list" 51.Fa "const char *name" 52.Fa "void *func" 53.Fa "void *arg" 54.Fa "int priority" 55.Fc 56.Ft void 57.Fo eventhandler_deregister 58.Fa "struct eventhandler_list *list" 59.Fa "eventhandler_tag tag" 60.Fc 61.Ft "struct eventhandler_list *" 62.Fn eventhandler_find_list "const char *name" 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 70The normal way to use this subsystem is via the macro interface. 71The macros that can be used for working with event handlers and callback 72function lists are: 73.Bl -tag -width indent 74.It Fn EVENTHANDLER_DECLARE 75This macro declares an event handler named by argument 76.Fa name 77with callback functions of type 78.Fa type . 79.It Fn EVENTHANDLER_REGISTER 80This macro registers a callback function 81.Fa func 82with event handler 83.Fa name . 84When invoked, function 85.Fa func 86will be invoked with argument 87.Fa arg 88as its first parameter along with any additional parameters passed in 89via macro 90.Fn EVENTHANDLER_INVOKE 91(see below). 92Callback functions are invoked in order of priority. 93The relative priority of each callback among other callbacks 94associated with an event is given by argument 95.Fa priority , 96which is an integer ranging from 97.Dv EVENTHANDLER_PRI_FIRST 98(highest priority), to 99.Dv EVENTHANDLER_PRI_LAST 100(lowest priority). 101The symbol 102.Dv EVENTHANDLER_PRI_ANY 103may be used if the handler does not have a specific priority 104associated with it. 105If registration is successful, 106.Fn EVENTHANDLER_REGISTER 107returns a cookie of type 108.Vt eventhandler_tag . 109.It Fn EVENTHANDLER_DEREGISTER 110This macro removes a previously registered callback associated with tag 111.Fa tag 112from the event handler named by argument 113.Fa name . 114.It Fn EVENTHANDLER_INVOKE 115This macro is used to invoke all the callbacks associated with event 116handler 117.Fa name . 118This macro is a variadic one. 119Additional arguments to the macro after the 120.Fa name 121parameter are passed as the second and subsequent arguments to each 122registered callback function. 123.El 124.Pp 125The macros are implemented using the following functions: 126.Bl -tag -width indent 127.It Fn eventhandler_register 128The 129.Fn eventhandler_register 130function is used to register a callback with a given event. 131The arguments expected by this function are: 132.Bl -tag -width ".Fa priority" 133.It Fa list 134A pointer to an existing event handler list, or 135.Dv NULL . 136If 137.Fa list 138is 139.Dv NULL , 140the event handler list corresponding to argument 141.Fa name 142is used. 143.It Fa name 144The name of the event handler list. 145.It Fa func 146A pointer to a callback function. 147Argument 148.Fa arg 149is passed to the callback function 150.Fa func 151as its first argument when it is invoked. 152.It Fa priority 153The relative priority of this callback among all the callbacks 154registered for this event. 155Valid values are those in the range 156.Dv EVENTHANDLER_PRI_FIRST 157to 158.Dv EVENTHANDLER_PRI_LAST . 159.El 160.Pp 161The 162.Fn eventhandler_register 163function returns a 164.Fa tag 165that can later be used with 166.Fn eventhandler_deregister 167to remove the particular callback function. 168.It Fn eventhandler_deregister 169The 170.Fn eventhandler_deregister 171function removes the callback associated with tag 172.Fa tag 173from the event handler list pointed to by 174.Fa list . 175This function is safe to call from inside an event handler 176callback. 177.It Fn eventhandler_find_list 178The 179.Fn eventhandler_find_list 180function returns a pointer to event handler list structure corresponding 181to event 182.Fa name . 183.El 184.Ss Kernel Event Handlers 185The following event handlers are present in the kernel: 186.Bl -tag -width indent 187.It Vt acpi_sleep_event 188Callbacks invoked when the system is being sent to sleep. 189.It Vt acpi_wakeup_event 190Callbacks invoked when the system is being woken up. 191.It Vt dev_clone 192Callbacks invoked when a new entry is created under 193.Pa /dev . 194.It Vt ifaddr_event 195Callbacks invoked when an address is set up on a network interface. 196.It Vt if_clone_event 197Callbacks invoked when an interface is cloned. 198.It Vt ifnet_attach_event 199Callbacks invoked when a new network interface appears. 200.It Vt ifnet_detach_event 201Callbacks invoked when a network interface is removed. 202.It Vt power_profile_change 203Callbacks invoked when the power profile of the system changes. 204.It Vt shutdown_pre_sync 205Callbacks invoked at shutdown time, before file systems are synchronized. 206.It Vt shutdown_post_sync 207Callbacks invoked at shutdown time, after all file systems are synchronized. 208.It Vt shutdown_final 209Callbacks invoked just before halting the system. 210.El 211.Sh RETURN VALUES 212The macro 213.Fn EVENTHANDLER_REGISTER 214and function 215.Fn eventhandler_register 216return a cookie of type 217.Vt eventhandler_tag , 218which may be used in a subsequent call to 219.Fn EVENTHANDLER_DEREGISTER 220or 221.Fn eventhandler_deregister . 222.Pp 223The 224.Fn eventhandler_find_list 225function 226returns a pointer to an event handler list corresponding to parameter 227.Fa name , 228or 229.Dv NULL 230if no such list was found. 231.Sh HISTORY 232The 233.Nm 234facility first appeared in 235.Fx 4.0 . 236.Sh AUTHORS 237This manual page was written by 238.An Joseph Koshy Aq jkoshy@FreeBSD.org . 239