SNMP_ALARM(3) Net-SNMP SNMP_ALARM(3)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 mecha‐
nism for multiple parts of an application to register function call‐
backs to happen at a particular time in the future.
USAGE
The usage is fairly simple and straight-forward: Simply create a func‐
tion 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 registra‐
tion.
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 call‐
ing 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) sys‐
tem 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 oper‐
ating system. Recommended.
SEE ALSOnetsnmp_session_api(3), default_store(3), alarm(2), setitimer(2),
select(2)V5.6 01 Aug 2002 SNMP_ALARM(3)
