diff options
Diffstat (limited to 'share/man/man9/EVENTHANDLER.9')
| -rw-r--r-- | share/man/man9/EVENTHANDLER.9 | 248 |
1 files changed, 248 insertions, 0 deletions
diff --git a/share/man/man9/EVENTHANDLER.9 b/share/man/man9/EVENTHANDLER.9 new file mode 100644 index 000000000000..ed83018d763c --- /dev/null +++ b/share/man/man9/EVENTHANDLER.9 @@ -0,0 +1,248 @@ +.\" Copyright (c) 2004 Joseph Koshy +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" $FreeBSD$ +.\" +.Dd January 7, 2005 +.Dt EVENTHANDLER 9 +.Os +.Sh NAME +.Nm EVENTHANDLER +.Nd kernel event handling functions +.Sh SYNOPSIS +.In sys/eventhandler.h +.Fn EVENTHANDLER_DECLARE name type +.Fn EVENTHANDLER_INVOKE name ... +.Ft eventhandler_tag +.Fn EVENTHANDLER_REGISTER name func arg priority +.Fn EVENTHANDLER_DEREGISTER name tag +.Ft eventhandler_tag +.Fo eventhandler_register +.Fa "struct eventhandler_list *list" +.Fa "const char *name" +.Fa "void *func" +.Fa "void *arg" +.Fa "int priority" +.Fc +.Ft void +.Fo eventhandler_deregister +.Fa "struct eventhandler_list *list" +.Fa "eventhandler_tag tag" +.Fc +.Ft "struct eventhandler_list *" +.Fn eventhandler_find_list "const char *name" +.Ft void +.Fn eventhandler_prune_list "struct eventhandler_list *list" +.Sh DESCRIPTION +The +.Nm +mechanism provides a way for kernel subsystems to register interest in +kernel events and have their callback functions invoked when these +events occur. +.Pp +The normal way to use this subsystem is via the macro interface. +The macros that can be used for working with event handlers and callback +function lists are: +.Bl -tag -width indent +.It Fn EVENTHANDLER_DECLARE +This macro declares an event handler named by argument +.Fa name +with callback functions of type +.Fa type . +.It Fn EVENTHANDLER_REGISTER +This macro registers a callback function +.Fa func +with event handler +.Fa name . +When invoked, function +.Fa func +will be invoked with argument +.Fa arg +as its first parameter along with any additional parameters passed in +via macro +.Fn EVENTHANDLER_INVOKE +(see below). +Callback functions are invoked in order of priority. +The relative priority of each callback among other callbacks +associated with an event is given by argument +.Fa priority , +which is an integer ranging from +.Dv EVENTHANDLER_PRI_FIRST +(highest priority), to +.Dv EVENTHANDLER_PRI_LAST +(lowest priority). +The symbol +.Dv EVENTHANDLER_PRI_ANY +may be used if the handler does not have a specific priority +associated with it. +If registration is successful, +.Fn EVENTHANDLER_REGISTER +returns a cookie of type +.Vt eventhandler_tag . +.It Fn EVENTHANDLER_DEREGISTER +This macro removes a previously registered callback associated with tag +.Fa tag +from the event handler named by argument +.Fa name . +.It Fn EVENTHANDLER_INVOKE +This macro is used to invoke all the callbacks associated with event +handler +.Fa name . +This macro is a variadic one. +Additional arguments to the macro after the +.Fa name +parameter are passed as the second and subsequent arguments to each +registered callback function. +.El +.Pp +The macros are implemented using the following functions: +.Bl -tag -width indent +.It Fn eventhandler_register +The +.Fn eventhandler_register +function is used to register a callback with a given event. +The arguments expected by this function are: +.Bl -tag -width ".Fa priority" +.It Fa list +A pointer to an existing event handler list, or +.Dv NULL . +If +.Fa list +is +.Dv NULL , +the event handler list corresponding to argument +.Fa name +is used. +.It Fa name +The name of the event handler list. +.It Fa func +A pointer to a callback function. +Argument +.Fa arg +is passed to the callback function +.Fa func +as its first argument when it is invoked. +.It Fa priority +The relative priority of this callback among all the callbacks +registered for this event. +Valid values are those in the range +.Dv EVENTHANDLER_PRI_FIRST +to +.Dv EVENTHANDLER_PRI_LAST . +.El +.Pp +The +.Fn eventhandler_register +function returns a +.Fa tag +that can later be used with +.Fn eventhandler_deregister +to remove the particular callback function. +.It Fn eventhandler_deregister +The +.Fn eventhandler_deregister +function removes the callback associated with tag +.Fa tag +from the event handler list pointed to by +.Fa list . +This function is safe to call from inside an event handler +callback. +.It Fn eventhandler_find_list +The +.Fn eventhandler_find_list +function returns a pointer to event handler list structure corresponding +to event +.Fa name . +.It Fn eventhandler_prune_list +The +.Fn eventhandler_prune_list +function removes all deregistered callbacks from the event list +.Fa list . +.El +.Ss Kernel Event Handlers +The following event handlers are present in the kernel: +.Bl -tag -width indent +.It Vt acpi_sleep_event +Callbacks invoked when the system is being sent to sleep. +.It Vt acpi_wakeup_event +Callbacks invoked when the system is being woken up. +.It Vt dev_clone +Callbacks invoked when a new entry is created under +.Pa /dev . +.It Vt ifaddr_event +Callbacks invoked when an address is set up on a network interface. +.It Vt if_clone_event +Callbacks invoked when an interface is cloned. +.It Vt ifnet_arrival_event +Callbacks invoked when a new network interface appears. +.It Vt ifnet_departure_event +Callbacks invoked when a network interface is taken down. +.It Vt power_profile_change +Callbacks invoked when the power profile of the system changes. +.It Vt process_exec +Callbacks invoked when a process performs an +.Fn exec +operation. +.It Vt process_exit +Callbacks invoked when a process exits. +.It Vt process_fork +Callbacks invoked when a process forks a child. +.It Vt shutdown_pre_sync +Callbacks invoked at shutdown time, before file systems are synchronized. +.It Vt shutdown_post_sync +Callbacks invoked at shutdown time, after all file systems are synchronized. +.It Vt shutdown_final +Callbacks invoked just before halting the system. +.It Vt vm_lowmem +Callbacks invoked when virtual memory is low. +.It Vt watchdog_list +Callbacks invoked when the system watchdog timer is reinitialized. +.El +.Sh RETURN VALUES +The macro +.Fn EVENTHANDLER_REGISTER +and function +.Fn eventhandler_register +return a cookie of type +.Vt eventhandler_tag , +which may be used in a subsequent call to +.Fn EVENTHANDLER_DEREGISTER +or +.Fn eventhandler_deregister . +.Pp +The +.Fn eventhandler_find_list +function +returns a pointer to an event handler list corresponding to parameter +.Fa name , +or +.Dv NULL +if no such list was found. +.Sh HISTORY +The +.Nm +facility first appeared in +.Fx 4.0 . +.Sh AUTHORS +This manual page was written by +.An Joseph Koshy Aq jkoshy@FreeBSD.org . |