This document is a Mac OS X manual page. Manual pages are a command-line technology for providing documentation. You can view these manual pages locally using the man(1) command. These manual pages come from many different sources, and thus, have a variety of writing styles.

For more information about the manual page format, see the manual page for manpages(5).

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 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  call-back callback
       back  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() func-tion, function,
       tion, 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 appli-cation application
       cation 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
       snmp_api(3), default_store(3), snmp_select_info(3), alarm(2), setitimer(2), select(2)



4.2 Berkeley Distribution                        07 Mar 2002                                   SNMP_ALARM(3)