Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help

       snmp_alarm_register,  snmp_alarm_register_hr,  snmp_alarm_unregister  -
       alarm functions

       #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);

       snmp_alarm_unregister(unsigned int reg);

       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.

       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-

       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 it-

       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.

       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.

       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:


       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  (re-
       turn  value of zero).  This is the approach taken in the	agent; see sn-
       mpd.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.

       netsnmp_session_api(3),	default_store(3),  alarm(2), setitimer(2), se-

V5.9				  01 Aug 2002			 SNMP_ALARM(3)


Want to link to this manual page? Use this URL:

home | help