2 .\" Copyright (c) 2004 Joseph Koshy
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
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.
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
26 .\" $FreeBSD: src/share/man/man9/EVENTHANDLER.9,v 1.4 2005/10/11 16:05:35 keramida Exp $
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
41 .In sys/eventhandler.h
42 .Fn EVENTHANDLER_DECLARE name type
43 .Fn EVENTHANDLER_INVOKE name ...
45 .Fn EVENTHANDLER_REGISTER name func arg priority
46 .Fn EVENTHANDLER_DEREGISTER name tag
48 .Fo eventhandler_register
49 .Fa "struct eventhandler_list *list"
50 .Fa "const char *name"
56 .Fo eventhandler_deregister
57 .Fa "struct eventhandler_list *list"
58 .Fa "eventhandler_tag tag"
60 .Ft "struct eventhandler_list *"
61 .Fn eventhandler_find_list "const char *name"
65 mechanism provides a way for kernel subsystems to register interest in
66 kernel events and have their callback functions invoked when these
69 The normal way to use this subsystem is via the macro interface.
70 The macros that can be used for working with event handlers and callback
72 .Bl -tag -width indent
73 .It Fn EVENTHANDLER_DECLARE
74 This macro declares an event handler named by argument
76 with callback functions of type
78 .It Fn EVENTHANDLER_REGISTER
79 This macro registers a callback function
83 When invoked, function
85 will be invoked with argument
87 as its first parameter along with any additional parameters passed in
89 .Fn EVENTHANDLER_INVOKE
91 Callback functions are invoked in order of priority.
92 The relative priority of each callback among other callbacks
93 associated with an event is given by argument
95 which is an integer ranging from
96 .Dv EVENTHANDLER_PRI_FIRST
97 (highest priority), to
98 .Dv EVENTHANDLER_PRI_LAST
101 .Dv EVENTHANDLER_PRI_ANY
102 may be used if the handler does not have a specific priority
104 If registration is successful,
105 .Fn EVENTHANDLER_REGISTER
106 returns a cookie of type
107 .Vt eventhandler_tag .
108 .It Fn EVENTHANDLER_DEREGISTER
109 This macro removes a previously registered callback associated with tag
111 from the event handler named by argument
113 .It Fn EVENTHANDLER_INVOKE
114 This macro is used to invoke all the callbacks associated with event
117 This macro is a variadic one.
118 Additional arguments to the macro after the
120 parameter are passed as the second and subsequent arguments to each
121 registered callback function.
124 The macros are implemented using the following functions:
125 .Bl -tag -width indent
126 .It Fn eventhandler_register
128 .Fn eventhandler_register
129 function is used to register a callback with a given event.
130 The arguments expected by this function are:
131 .Bl -tag -width ".Fa priority"
133 A pointer to an existing event handler list, or
139 the event handler list corresponding to argument
143 The name of the event handler list.
145 A pointer to a callback function.
148 is passed to the callback function
150 as its first argument when it is invoked.
152 The relative priority of this callback among all the callbacks
153 registered for this event.
154 Valid values are those in the range
155 .Dv EVENTHANDLER_PRI_FIRST
157 .Dv EVENTHANDLER_PRI_LAST .
161 .Fn eventhandler_register
164 that can later be used with
165 .Fn eventhandler_deregister
166 to remove the particular callback function.
167 .It Fn eventhandler_deregister
169 .Fn eventhandler_deregister
170 function removes the callback associated with tag
172 from the event handler list pointed to by
174 This function is safe to call from inside an event handler
176 .It Fn eventhandler_find_list
178 .Fn eventhandler_find_list
179 function returns a pointer to event handler list structure corresponding
183 .Ss Kernel Event Handlers
184 The following event handlers are present in the kernel:
185 .Bl -tag -width indent
186 .It Vt acpi_sleep_event
187 Callbacks invoked when the system is being sent to sleep.
188 .It Vt acpi_wakeup_event
189 Callbacks invoked when the system is being woken up.
191 Callbacks invoked when a new entry is created under
194 Callbacks invoked when an address is set up on a network interface.
195 .It Vt if_clone_event
196 Callbacks invoked when an interface is cloned.
197 .It Vt ifnet_attach_event
198 Callbacks invoked when a new network interface appears.
199 .It Vt ifnet_detach_event
200 Callbacks invoked when a network interface is removed.
201 .It Vt power_profile_change
202 Callbacks invoked when the power profile of the system changes.
203 .It Vt shutdown_pre_sync
204 Callbacks invoked at shutdown time, before file systems are synchronized.
205 .It Vt shutdown_post_sync
206 Callbacks invoked at shutdown time, after all file systems are synchronized.
207 .It Vt shutdown_final
208 Callbacks invoked just before halting the system.
212 .Fn EVENTHANDLER_REGISTER
214 .Fn eventhandler_register
215 return a cookie of type
216 .Vt eventhandler_tag ,
217 which may be used in a subsequent call to
218 .Fn EVENTHANDLER_DEREGISTER
220 .Fn eventhandler_deregister .
223 .Fn eventhandler_find_list
225 returns a pointer to an event handler list corresponding to parameter
229 if no such list was found.
233 facility first appeared in
236 This manual page was written by
237 .An Joseph Koshy Aq Mt jkoshy@FreeBSD.org .