7516f87ad38ca92c4615f644cdd6084e48ce86c6
[dragonfly.git] / share / man / man9 / EVENTHANDLER.9
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 June 22, 2018
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
63 The
64 .Nm
65 mechanism provides a way for kernel subsystems to register interest in
66 kernel events and have their callback functions invoked when these
67 events occur.
68 .Pp
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
71 function lists are:
72 .Bl -tag -width indent
73 .It Fn EVENTHANDLER_DECLARE
74 This macro declares an event handler named by argument
75 .Fa name
76 with callback functions of type
77 .Fa type .
78 .It Fn EVENTHANDLER_REGISTER
79 This macro registers a callback function
80 .Fa func
81 with event handler
82 .Fa name .
83 When invoked, function
84 .Fa func
85 will be invoked with argument
86 .Fa arg
87 as its first parameter along with any additional parameters passed in
88 via macro
89 .Fn EVENTHANDLER_INVOKE
90 (see below).
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
94 .Fa priority ,
95 which is an integer ranging from
96 .Dv EVENTHANDLER_PRI_FIRST
97 (highest priority), to
98 .Dv EVENTHANDLER_PRI_LAST
99 (lowest priority).
100 The symbol
101 .Dv EVENTHANDLER_PRI_ANY
102 may be used if the handler does not have a specific priority
103 associated with it.
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
110 .Fa tag
111 from the event handler named by argument
112 .Fa name .
113 .It Fn EVENTHANDLER_INVOKE
114 This macro is used to invoke all the callbacks associated with event
115 handler
116 .Fa name .
117 This macro is a variadic one.
118 Additional arguments to the macro after the
119 .Fa name
120 parameter are passed as the second and subsequent arguments to each
121 registered callback function.
122 .El
123 .Pp
124 The macros are implemented using the following functions:
125 .Bl -tag -width indent
126 .It Fn eventhandler_register
127 The
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"
132 .It Fa list
133 A pointer to an existing event handler list, or
134 .Dv NULL .
135 If
136 .Fa list
137 is
138 .Dv NULL ,
139 the event handler list corresponding to argument
140 .Fa name
141 is used.
142 .It Fa name
143 The name of the event handler list.
144 .It Fa func
145 A pointer to a callback function.
146 Argument
147 .Fa arg
148 is passed to the callback function
149 .Fa func
150 as its first argument when it is invoked.
151 .It Fa priority
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
156 to
157 .Dv EVENTHANDLER_PRI_LAST .
158 .El
159 .Pp
160 The
161 .Fn eventhandler_register
162 function returns a
163 .Fa tag
164 that can later be used with
165 .Fn eventhandler_deregister
166 to remove the particular callback function.
167 .It Fn eventhandler_deregister
168 The
169 .Fn eventhandler_deregister
170 function removes the callback associated with tag
171 .Fa tag
172 from the event handler list pointed to by
173 .Fa list .
174 This function is safe to call from inside an event handler
175 callback.
176 .It Fn eventhandler_find_list
177 The
178 .Fn eventhandler_find_list
179 function returns a pointer to event handler list structure corresponding
180 to event
181 .Fa name .
182 .El
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.
190 .It Vt dev_clone
191 Callbacks invoked when a new entry is created under
192 .Pa /dev .
193 .It Vt group_attach_event
194 Callbacks invoked when a new interface group has been created.
195 .It Vt group_change_event
196 Callbacks invoked when the members of an interface group have changed.
197 .It Vt group_detach_event
198 Callbacks invoked when an interface group has been removed due to no members.
199 .It Vt if_clone_event
200 Callbacks invoked when a new interface cloner is attached.
201 .It Vt ifaddr_event
202 Callbacks invoked when an address is set up on a network interface.
203 .It Vt ifnet_attach_event
204 Callbacks invoked when a new network interface appears.
205 .It Vt ifnet_detach_event
206 Callbacks invoked when a network interface is removed.
207 .It Vt power_profile_change
208 Callbacks invoked when the power profile of the system changes.
209 .It Vt shutdown_pre_sync
210 Callbacks invoked at shutdown time, before file systems are synchronized.
211 .It Vt shutdown_post_sync
212 Callbacks invoked at shutdown time, after all file systems are synchronized.
213 .It Vt shutdown_final
214 Callbacks invoked just before halting the system.
215 .El
216 .Sh RETURN VALUES
217 The macro
218 .Fn EVENTHANDLER_REGISTER
219 and function
220 .Fn eventhandler_register
221 return a cookie of type
222 .Vt eventhandler_tag ,
223 which may be used in a subsequent call to
224 .Fn EVENTHANDLER_DEREGISTER
225 or
226 .Fn eventhandler_deregister .
227 .Pp
228 The
229 .Fn eventhandler_find_list
230 function
231 returns a pointer to an event handler list corresponding to parameter
232 .Fa name ,
233 or
234 .Dv NULL
235 if no such list was found.
236 .Sh HISTORY
237 The
238 .Nm
239 facility first appeared in
240 .Fx 4.0 .
241 .Sh AUTHORS
242 This manual page was written by
243 .An Joseph Koshy Aq Mt jkoshy@FreeBSD.org .