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 call-
       backs 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 func-
       tion 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 avail-
       able, 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)

V5.7.2								    01 Aug 2002 						     SNMP_ALARM(3)