48ef243364
descriptions of items from each other and have related things appear in the same nesting 'level'. The .Fn function/macro, and bump document date. Reviewed by: jkoshy
249 lines
7.2 KiB
Groff
249 lines
7.2 KiB
Groff
.\" 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 a 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 .
|