plucky (3) snmp_alarm.3.gz

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)