xref: /freebsd/share/man/man9/EVENTHANDLER.9 (revision 8554754c7bbe3cda171378ad6305bbe8a1a94cb6)
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 March 27, 2017
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_DEFINE name func arg priority
36.Fn EVENTHANDLER_INVOKE name ...
37.Ft eventhandler_tag
38.Fn EVENTHANDLER_REGISTER name func arg priority
39.Fn EVENTHANDLER_DEREGISTER name tag
40.Ft eventhandler_tag
41.Fo eventhandler_register
42.Fa "struct eventhandler_list *list"
43.Fa "const char *name"
44.Fa "void *func"
45.Fa "void *arg"
46.Fa "int priority"
47.Fc
48.Ft void
49.Fo eventhandler_deregister
50.Fa "struct eventhandler_list *list"
51.Fa "eventhandler_tag tag"
52.Fc
53.Ft "struct eventhandler_list *"
54.Fn eventhandler_find_list "const char *name"
55.Ft void
56.Fn eventhandler_prune_list "struct eventhandler_list *list"
57.Sh DESCRIPTION
58The
59.Nm
60mechanism provides a way for kernel subsystems to register interest in
61kernel events and have their callback functions invoked when these
62events occur.
63.Pp
64Callback functions are invoked in order of priority.
65The relative priority of each callback among other callbacks
66associated with an event is given by argument
67.Fa priority ,
68which is an integer ranging from
69.Dv EVENTHANDLER_PRI_FIRST
70(highest priority), to
71.Dv EVENTHANDLER_PRI_LAST
72(lowest priority).
73The symbol
74.Dv EVENTHANDLER_PRI_ANY
75may be used if the handler does not have a specific priority
76associated with it.
77.Pp
78The normal way to use this subsystem is via the macro interface.
79The macros that can be used for working with event handlers and callback
80function lists are:
81.Bl -tag -width indent
82.It Fn EVENTHANDLER_DECLARE
83This macro declares an event handler named by argument
84.Fa name
85with callback functions of type
86.Fa type .
87.It Fn EVENTHANDLER_DEFINE
88This macro uses
89.Xr SYSINIT 9
90to register a callback function
91.Fa func
92with event handler
93.Fa name .
94When invoked, function
95.Fa func
96will be invoked with argument
97.Fa arg
98as its first parameter along with any additional parameters passed in
99via macro
100.Fn EVENTHANDLER_INVOKE
101(see below).
102.It Fn EVENTHANDLER_REGISTER
103This macro registers a callback function
104.Fa func
105with event handler
106.Fa name .
107When invoked, function
108.Fa func
109will be invoked with argument
110.Fa arg
111as its first parameter along with any additional parameters passed in
112via macro
113.Fn EVENTHANDLER_INVOKE
114(see below).
115If registration is successful,
116.Fn EVENTHANDLER_REGISTER
117returns a cookie of type
118.Vt eventhandler_tag .
119.It Fn EVENTHANDLER_DEREGISTER
120This macro removes a previously registered callback associated with tag
121.Fa tag
122from the event handler named by argument
123.Fa name .
124.It Fn EVENTHANDLER_INVOKE
125This macro is used to invoke all the callbacks associated with event
126handler
127.Fa name .
128This macro is a variadic one.
129Additional arguments to the macro after the
130.Fa name
131parameter are passed as the second and subsequent arguments to each
132registered callback function.
133.El
134.Pp
135The macros are implemented using the following functions:
136.Bl -tag -width indent
137.It Fn eventhandler_register
138The
139.Fn eventhandler_register
140function is used to register a callback with a given event.
141The arguments expected by this function are:
142.Bl -tag -width ".Fa priority"
143.It Fa list
144A pointer to an existing event handler list, or
145.Dv NULL .
146If
147.Fa list
148is
149.Dv NULL ,
150the event handler list corresponding to argument
151.Fa name
152is used.
153.It Fa name
154The name of the event handler list.
155.It Fa func
156A pointer to a callback function.
157Argument
158.Fa arg
159is passed to the callback function
160.Fa func
161as its first argument when it is invoked.
162.It Fa priority
163The relative priority of this callback among all the callbacks
164registered for this event.
165Valid values are those in the range
166.Dv EVENTHANDLER_PRI_FIRST
167to
168.Dv EVENTHANDLER_PRI_LAST .
169.El
170.Pp
171The
172.Fn eventhandler_register
173function returns a
174.Fa tag
175that can later be used with
176.Fn eventhandler_deregister
177to remove the particular callback function.
178.It Fn eventhandler_deregister
179The
180.Fn eventhandler_deregister
181function removes the callback associated with tag
182.Fa tag
183from the event handler list pointed to by
184.Fa list .
185This function is safe to call from inside an event handler
186callback.
187.It Fn eventhandler_find_list
188The
189.Fn eventhandler_find_list
190function returns a pointer to event handler list structure corresponding
191to event
192.Fa name .
193.It Fn eventhandler_prune_list
194The
195.Fn eventhandler_prune_list
196function removes all deregistered callbacks from the event list
197.Fa list .
198.El
199.Ss Kernel Event Handlers
200The following event handlers are present in the kernel:
201.Bl -tag -width indent
202.It Vt acpi_sleep_event
203Callbacks invoked when the system is being sent to sleep.
204.It Vt acpi_wakeup_event
205Callbacks invoked when the system is being woken up.
206.It Vt app_coredump_start
207Callbacks invoked at start of application core dump.
208.It Vt app_coredump_progress
209Callbacks invoked during progress of application core dump.
210.It Vt app_coredump_finish
211Callbacks invoked at finish of application core dump.
212.It Vt app_coredump_error
213Callbacks invoked on error of application core dump.
214.It Vt bpf_track
215Callbacks invoked when a BPF listener attaches to/detaches from network interface.
216.It Vt cpufreq_levels_changed
217Callback invoked when cpu frequency levels have changed.
218.It Vt cpufreq_post_change
219Callback invoked after cpu frequency has changed.
220.It Vt cpufreq_pre_change
221Callback invoked before cpu frequency has changed.
222.It Vt dcons_poll
223Callback invoked to poll for dcons changes.
224.It Vt dev_clone
225Callbacks invoked when a new entry is created under
226.Pa /dev .
227.It Vt group_attach_event
228Callback invoked when an interfance has been added to an interface group.
229.It Vt group_change_event
230Callback invoked when an change has been made to an interface group.
231.It Vt group_detach_event
232Callback invoked when an interfance has been removed from an interface group.
233.It Vt ifaddr_event
234Callbacks invoked when an address is set up on a network interface.
235.It Vt if_clone_event
236Callbacks invoked when an interface is cloned.
237.It Vt iflladdr_event
238Callback invoked when an if link layer address event has happened.
239.It Vt ifnet_arrival_event
240Callbacks invoked when a new network interface appears.
241.It Vt ifnet_departure_event
242Callbacks invoked when a network interface is taken down.
243.It Vt ifnet_link_event
244Callback invoked when an interfance link event has happened.
245.It Vt kld_load
246Callbacks invoked after a linker file has been loaded.
247.It Vt kld_unload
248Callbacks invoked after a linker file has been successfully unloaded.
249.It Vt kld_unload_try
250Callbacks invoked before a linker file is about to be unloaded.
251These callbacks may be used to return an error and prevent the unload from
252proceeding.
253.It Vt lle_event
254Callback invoked when an link layer event has happened.
255.It Vt nmbclusters_change
256Callback invoked when the number of mbuf clusters has changed.
257.It Vt nmbufs_change
258Callback invoked when the number of mbufs has changed.
259.It Vt maxsockets_change
260Callback invoked when the maximum number of sockets has changed.
261.It Vt mountroot
262Callback invoked when root has been mounted.
263.It Vt power_profile_change
264Callbacks invoked when the power profile of the system changes.
265.It Vt power_resume
266Callback invoked when the system has resumed.
267.It Vt power_suspend
268Callback invoked just before the system is suspended.
269.It Vt process_ctor
270Callback invoked when a process is created.
271.It Vt process_dtor
272Callback invoked when a process is destroyed.
273.It Vt process_exec
274Callbacks invoked when a process performs an
275.Fn exec
276operation.
277.It Vt process_exit
278Callbacks invoked when a process exits.
279.It Vt process_fini
280Callback invoked when a process memory is destroyed.
281This is never called.
282.It Vt process_fork
283Callbacks invoked when a process forks a child.
284.It Vt process_init
285Callback invoked when a process is initalized.
286.It Vt random_adaptor_attach
287Callback invoked when a new random module has been loaded.
288.It Vt register_framebuffer
289Callback invoked when a new frame buffer is registered.
290.It Vt route_redirect_event
291Callback invoked when a route gets redirected to a new location.
292.It Vt shutdown_pre_sync
293Callbacks invoked at shutdown time, before file systems are synchronized.
294.It Vt shutdown_post_sync
295Callbacks invoked at shutdown time, after all file systems are synchronized.
296.It Vt shutdown_final
297Callbacks invoked just before halting the system.
298.It Vt tcp_offload_listen_start
299Callback invoked for TCP Offload to start listening for new connections.
300.It Vt tcp_offload_listen_stop
301Callback invoked ror TCP Offload to stop listening for new connections.
302.It Vt thread_ctor
303Callback invoked when a thread object is created.
304.It Vt thread_dtor
305Callback invoked when a thread object is destroyed.
306.It Vt thread_init
307Callback invoked when a thread object is initalized.
308.It Vt thread_fini
309Callback invoked when a thread object is deinitalized.
310.It Vt usb_dev_configured
311Callback invoked when a USB device is configured
312.It Vt unregister_framebuffer
313Callback invoked when a frame buffer is deregistered.
314.It Vt vfs_mounted
315Callback invoked when a file system is mounted.
316.It Vt vfs_unmounted
317Callback invoked when a file system is unmounted.
318.It Vt vlan_config
319Callback invoked when the vlan configuration has changed.
320.It Vt vlan_unconfig
321Callback invoked when a vlan is destroyed.
322.It Vt vm_lowmem
323Callbacks invoked when virtual memory is low.
324.It Vt watchdog_list
325Callbacks invoked when the system watchdog timer is reinitialized.
326.El
327.Sh RETURN VALUES
328The macro
329.Fn EVENTHANDLER_REGISTER
330and function
331.Fn eventhandler_register
332return a cookie of type
333.Vt eventhandler_tag ,
334which may be used in a subsequent call to
335.Fn EVENTHANDLER_DEREGISTER
336or
337.Fn eventhandler_deregister .
338.Pp
339The
340.Fn eventhandler_find_list
341function
342returns a pointer to an event handler list corresponding to parameter
343.Fa name ,
344or
345.Dv NULL
346if no such list was found.
347.Sh HISTORY
348The
349.Nm
350facility first appeared in
351.Fx 4.0 .
352.Sh AUTHORS
353This manual page was written by
354.An Joseph Koshy Aq Mt jkoshy@FreeBSD.org .
355