171 lines
4.5 KiB
Modula-2
171 lines
4.5 KiB
Modula-2
.TH SNMP_ALARM 3 "01 Aug 2002" VVERSIONINFO "Net-SNMP"
|
|
.SH NAME
|
|
snmp_alarm_register,
|
|
snmp_alarm_register_hr,
|
|
snmp_alarm_unregister - alarm functions
|
|
.SH SYNOPSIS
|
|
.B #include <net-snmp/utilities.h>
|
|
.PP
|
|
.B "unsigned int"
|
|
.br
|
|
.BI "snmp_alarm_register(unsigned int " seconds ","
|
|
.br
|
|
.BI " unsigned int " flags ","
|
|
.br
|
|
.BI " SNMPAlarmCallback *" f_callback ","
|
|
.br
|
|
.BI " void *" clientarg ");"
|
|
.PP
|
|
.B "unsigned int"
|
|
.br
|
|
.BI "snmp_alarm_register_hr(struct timeval " t ","
|
|
.br
|
|
.BI " unsigned int " flags ","
|
|
.br
|
|
.BI " SNMPAlarmCallback *" f_callback ","
|
|
.br
|
|
.BI " void *" clientarg ");"
|
|
.PP
|
|
.B "void
|
|
.br
|
|
.BI "snmp_alarm_unregister(unsigned int " reg ");"
|
|
.SH DESCRIPTION
|
|
.PP
|
|
These functions implement support for a generic timer handling
|
|
mechanism for multiple parts of an application to register function
|
|
callbacks to happen at a particular time in the future.
|
|
.SH USAGE
|
|
.PP
|
|
The usage is fairly simple and straight-forward: Simply create a
|
|
function you want called back at some point in the future. The
|
|
function definition should be similar to:
|
|
.RS 4
|
|
.PP
|
|
.BI "void my_callback(unsigned int " reg ", void *" clientarg ");"
|
|
.RE
|
|
.PP
|
|
Then, call
|
|
.B snmp_alarm_register()
|
|
to register your callback to be called
|
|
.I seconds
|
|
from now. The
|
|
.I flags
|
|
field should either be
|
|
.I SA_REPEAT
|
|
or
|
|
.I NULL.
|
|
If flags is set with
|
|
.I SA_REPEAT,
|
|
then the registered callback function will be called every
|
|
.I seconds.
|
|
If
|
|
.I flags
|
|
is
|
|
.I NULL
|
|
then the function will only be called once and then removed from the
|
|
alarm system registration.
|
|
.PP
|
|
The
|
|
.I clientarg
|
|
parameter in the registration function is used only by
|
|
the client function and is stored and passed back directly to them on
|
|
every call to the system.
|
|
.PP
|
|
The
|
|
.B snmp_alarm_register()
|
|
function returns a unique
|
|
.I "unsigned int"
|
|
(which is also passed as the first argument of each callback), which
|
|
can then be used to remove the callback from the queue at a later
|
|
point in the future using the
|
|
.B snmp_alarm_unregister()
|
|
function. If the
|
|
.B snmp_alarm_register()
|
|
call fails it returns zero. In particular, note that it is entirely
|
|
permissible for an alarm function to unregister itself.
|
|
.PP
|
|
The
|
|
.B snmp_alarm_register_hr()
|
|
function is identical in operation to the
|
|
.B snmp_alarm_register()
|
|
function, but takes a
|
|
.I "struct timeval"
|
|
as a first parameter, and schedules the callback after the period
|
|
represented by
|
|
.I t
|
|
(the letters
|
|
.B hr
|
|
stand for "high resolution"). The operation of this function is
|
|
dependent on the provision of the
|
|
.BR setitimer (2)
|
|
system call by the operating system. If this system call is not
|
|
available, the alarm will be scheduled as if
|
|
.B snmp_alarm_register()
|
|
had been called with a first argument equal to the value of the
|
|
.I tv_sec
|
|
member of
|
|
.IR "t".
|
|
See, however, the notes below.
|
|
.SH INITIALIZATION
|
|
The
|
|
.B init_snmp()
|
|
function initialises the snmp_alarm subsystem by calling
|
|
.B init_snmp_alarm()
|
|
and then
|
|
.B init_alarm_post_config()
|
|
to set up the first timer to initialise the callback function. These
|
|
two functions should not be used directly by applications.
|
|
.SH "NOTES"
|
|
The default behaviour of the snmp_alarm subsystem is to request
|
|
.I SIGALRM
|
|
signals from the operating system via the
|
|
.BR alarm (2)
|
|
or
|
|
.BR setitimer (2)
|
|
system calls. This has the disadvantage, however, that no other part
|
|
of the application can use the
|
|
.I SIGLARM
|
|
functionality (or, if some other part of the application
|
|
.I does
|
|
use the
|
|
.I SIGALRM
|
|
functionality, the snmp_alarm subsystem will not work correctly).
|
|
.PP
|
|
If your application runs a
|
|
.BR select (2)-based
|
|
event loop, however, there is no need to use
|
|
.I SIGALRM
|
|
for the snmp_alarm subsystem, leaving it available for other parts of
|
|
the application. This is done by making the following call:
|
|
.PP
|
|
.nf
|
|
netsnmp_ds_set_boolean(NETSNMP_DS_LIBRARY_ID,
|
|
NETSNMP_DS_LIB_ALARM_DONT_USE_SIG, 1);
|
|
.fi
|
|
.PP
|
|
before calling
|
|
.BR "init_snmp()".
|
|
Then,
|
|
.BR snmp_select_info()
|
|
takes alarms into account when calculating the timeout value to be
|
|
used for
|
|
.BR select (2).
|
|
All you need to do is call
|
|
.BR run_alarms()
|
|
when
|
|
.BR select (2)
|
|
times out (return value of zero). This is the approach taken in the
|
|
agent; see
|
|
.IR "snmpd.c".
|
|
Furthermore, when using this method, high resolution alarms do not
|
|
depend on the presence of the
|
|
.BR setitimer (2)
|
|
system call, although overall precision is of course still determined
|
|
by the underlying operating system. Recommended.
|
|
.SH "SEE ALSO"
|
|
.BR netsnmp_session_api "(3), " default_store "(3), "
|
|
.BR alarm "(2), " setitimer "(2), " select "(2)"
|
|
.\" Local Variables:
|
|
.\" mode: nroff
|
|
.\" End:
|