NAME¶
snmp_alarm_register, snmp_alarm_register_hr, snmp_alarm_unregister - alarm
functions
SYNOPSIS¶
#include <net-snmp/utilities.h>
unsigned int
snmp_alarm_register(unsigned int seconds,
unsigned int flags,
SNMPAlarmCallback *f_callback,
void *clientarg);
unsigned int
snmp_alarm_register_hr(struct timeval t,
unsigned int flags,
SNMPAlarmCallback *f_callback,
void *clientarg);
void
snmp_alarm_unregister(unsigned int reg);
DESCRIPTION¶
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.
USAGE¶
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:
void my_callback(unsigned int reg, void
*clientarg);
Then, call
snmp_alarm_register() to register your callback to be called
seconds from now. The
flags field should either be
SA_REPEAT or
NULL. If flags is set with
SA_REPEAT, then
the registered callback function will be called every
seconds. If
flags is
NULL then the function will only be called once and
then removed from the alarm system registration.
The
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.
The
snmp_alarm_register() function returns a unique
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
snmp_alarm_unregister() function. If the
snmp_alarm_register() call fails it returns zero. In particular, note
that it is entirely permissible for an alarm function to unregister itself.
The
snmp_alarm_register_hr() function is identical in operation to the
snmp_alarm_register() function, but takes a
struct timeval as a
first parameter, and schedules the callback after the period represented by
t (the letters
hr stand for "high resolution"). The
operation of this function is dependent on the provision of the
setitimer(2) system call by the operating system. If this system call
is not available, the alarm will be scheduled as if
snmp_alarm_register() had been called with a first argument equal to
the value of the
tv_sec member of
t. See, however, the notes
below.
INITIALIZATION¶
The
init_snmp() function initialises the snmp_alarm subsystem by calling
init_snmp_alarm() and then
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.
NOTES¶
The default behaviour of the snmp_alarm subsystem is to request
SIGALRM
signals from the operating system via the
alarm(2) or
setitimer(2) system calls. This has the disadvantage, however, that no
other part of the application can use the
SIGLARM functionality (or, if
some other part of the application
does use the
SIGALRM
functionality, the snmp_alarm subsystem will not work correctly).
If your application runs a
select(2)-based event loop, however, there is
no need to use
SIGALRM for the snmp_alarm subsystem, leaving it
available for other parts of the application. This is done by making the
following call:
netsnmp_ds_set_boolean(NETSNMP_DS_LIBRARY_ID,
NETSNMP_DS_LIB_ALARM_DONT_USE_SIG, 1);
before calling
init_snmp(). Then,
snmp_select_info() takes alarms
into account when calculating the timeout value to be used for
select(2). All you need to do is call
run_alarms() when
select(2) times out (return value of zero). This is the approach taken
in the agent; see
snmpd.c. Furthermore, when using this method, high
resolution alarms do not depend on the presence of the
setitimer(2)
system call, although overall precision is of course still determined by the
underlying operating system. Recommended.
SEE ALSO¶
netsnmp_session_api(3),
default_store(3),
alarm(2),
setitimer(2),
select(2)