Add a manual page for the kernel's EVENTHANDLER facility.

Reviewed by:	ru

1 files changed, 239 insertions, 0 deletions

diff --git a/share/man/man9/EVENTHANDLER.9 b/share/man/man9/EVENTHANDLER.9
new file mode 100644
index 000000000000..40e1901e51f7
--- /dev/null
+++ b/share/man/man9/EVENTHANDLER.9
@@ -0,0 +1,239 @@
+.\" 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 November 23, 2004
+.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 "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 "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.
+.Pp
+The macro
+.Fn EVENTHANDLER_DECLARE
+declares an event handler named by argument
+.Fa name
+with callback functions of type
+.Fa type .
+.Pp
+The macro
+.Fn EVENTHANDLER_REGISTER
+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 this callback among other callbacks
+associated with this 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 .
+.Pp
+The macro
+.Fn EVENTHANDLER_DEREGISTER
+removes a previously registered callback associated with
+tag
+.Fa tag
+from the event handler named by argument
+.Fa name .
+.Pp
+The macro
+.Fn EVENTHANDLER_INVOKE
+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.
+.Pp
+The macros are implemented using the following functions:
+.Pp
+The function
+.Fn eventhandler_register
+is used to register a callback with a given event.
+The argument
+.Fa list
+is pointer to an existing event handler list, or
+.Dv NULL .
+If argument
+.Fa list
+is
+.Dv NULL ,
+the event handler list corresponding to argument
+.Fa name
+is used.
+Argument
+.Fa func
+is a pointer to a callback function.
+Argument
+.Fa arg
+is a passed in to callback function
+.Fa func
+as its first argument when it is invoked.
+Argument
+.Fa priority
+ranges from
+.Dv EVENTHANDLER_PRI_FIRST
+to
+.Dv EVENTHANDLER_PRI_LAST ,
+and determines the relative priority of this callback among all the
+callbacks registered for this event.
+.Pp
+Function
+.Fn eventhandler_deregister
+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.
+.Pp
+Function
+.Fn eventhandler_find_list
+returns a pointer to event handler list structure corresponding to
+event
+.Fa name .
+.Pp
+Function
+.Fn eventhandler_prune_list
+removes all deregistered callbacks from the event list
+.Fa list .
+.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
+Function
+.Fn eventhandler_find_list
+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 .
\ No newline at end of file