Add a manual page for the kernel's EVENTHANDLER facility.
Reviewed by: ru
This commit is contained in:
jkoshy
parent
e7c2d9ca7b
commit
ae68ca377a
239
share/man/man9/EVENTHANDLER.9
Normal file
239
share/man/man9/EVENTHANDLER.9
Normal file
@ -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 .
|
||||
@ -88,6 +88,7 @@ MAN= accept_filter.9 \
|
||||
domain.9 \
|
||||
driver.9 \
|
||||
DRIVER_MODULE.9 \
|
||||
EVENTHANDLER.9 \
|
||||
extattr.9 \
|
||||
fetch.9 \
|
||||
g_access.9 \
|
||||
@ -448,6 +449,14 @@ MLINKS+=domain.9 DOMAIN_SET.9 \
|
||||
domain.9 pffindproto.9 \
|
||||
domain.9 pffindtype.9
|
||||
MLINKS+=DRIVER_MODULE.9 MULTI_DRIVER_MODULE.9
|
||||
MLINKS+=EVENTHANDLER.9 EVENTHANDLER_DECLARE.9 \
|
||||
EVENTHANDLER.9 EVENTHANDLER_DEREGISTER.9 \
|
||||
EVENTHANDLER.9 eventhandler_deregister.9 \
|
||||
EVENTHANDLER.9 EVENTHANDLER_INVOKE.9 \
|
||||
EVENTHANDLER.9 EVENTHANDLER_REGISTER.9 \
|
||||
EVENTHANDLER.9 eventhandler_register.9 \
|
||||
EVENTHANDLER.9 eventhandler_find_list.9 \
|
||||
EVENTHANDLER.9 eventhandler_prune_list.9
|
||||
MLINKS+=fetch.9 fubyte.9 \
|
||||
fetch.9 fuswintr.9 \
|
||||
fetch.9 fusword.9 \
|
||||
|
||||
Loading…
Reference in New Issue
Block a user