SNMPALARM(3) Net-SNMP SNMPALARM(3)

NAME
       snmpalarmregister,  snmpalarmregisterhr,  snmpalarmunregister  -
       alarm functions

SYNOPSIS
       ##iinncclluuddee <>

       uunnssiiggnneedd iinntt
       ssnnmmppaallaarrmmrreeggiisstteerr((uunnssiiggnneedd iinntt seconds,,
                           uunnssiiggnneedd iinntt flags,,
                           SSNNMMPPAAllaarrmmCCaallllbbaacckk **fcallback,,
                           vvooiidd **clientarg));;

       uunnssiiggnneedd iinntt
       ssnnmmppaallaarrmmrreeggiisstteerrhhrr((ssttrruucctt ttiimmeevvaall t,,
                              uunnssiiggnneedd iinntt flags,,
                              SSNNMMPPAAllaarrmmCCaallllbbaacckk **fcallback,,
                              vvooiidd **clientarg));;

       vvooiidd
       ssnnmmppaallaarrmmuunnrreeggiisstteerr((uunnssiiggnneedd iinntt 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.

UUSSAAGGEE
       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:

           vvooiidd mmyyccaallllbbaacckk((uunnssiiggnneedd iinntt reg,, vvooiidd **clientarg));;

       Then, call ssnnmmppaallaarrmmrreeggiisstteerr(()) to register your callback to be called
       seconds  from now.  The flags field should either be SAREPEAT or NULL.
       If flags is set with SAREPEAT, 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 ssnnmmppaallaarrmmrreeggiisstteerr(()) 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   ssnnmmppaallaarrmmuunnrreeggiisstteerr(())   function.    If    the
       ssnnmmppaallaarrmmrreeggiisstteerr(())  call fails it returns zero.  In particular, note
       that it is entirely permissible for an  alarm  function  to  unregister
       itself.

       The  ssnnmmppaallaarrmmrreeggiisstteerrhhrr(()) function is identical in operation to the
       ssnnmmppaallaarrmmrreeggiisstteerr(()) function, but takes a struct timeval as  a  first
       parameter, and schedules the callback after the period represented by t
       (the letters hhrr stand for "high resolution").  The  operation  of  this
       function  is dependent on the provision of the sseettiittiimmeerr(2) system call
       by the operating system.  If this system call  is  not  available,  the
       alarm  will  be  scheduled  as if ssnnmmppaallaarrmmrreeggiisstteerr(()) had been called
       with a first argument equal to the value of the  tvsec  member  of  t.
       See, however, the notes below.

IINNIITTIIAALLIIZZAATTIIOONN
       The  iinniittssnnmmpp(()) function initialises the snmpalarm subsystem by call-
       ing iinniittssnnmmppaallaarrmm(()) and then iinniittaallaarrmmppoossttccoonnffiigg(()) to set  up  the
       first  timer  to initialise the callback function.  These two functions
       should not be used directly by applications.

NNOOTTEESS
       The default behaviour of the snmpalarm subsystem is to request SIGALRM
       signals from the operating system via the aallaarrmm(2) or sseettiittiimmeerr(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
       snmpalarm subsystem will not work correctly).

       If  your  application runs a sseelleecctt(2)-based event loop, however, there
       is no need to use SIGALRM for  the  snmpalarm  subsystem,  leaving  it
       available  for  other parts of the application.  This is done by making
       the following call:

       netsnmpdssetboolean(NETSNMPDSLIBRARYID,
                              NETSNMPDSLIBALARMDONTUSESIG, 1);

       before calling iinniittssnnmmpp(()).  Then, ssnnmmppsseelleeccttiinnffoo(()) takes alarms into
       account  when  calculating  the timeout value to be used for sseelleecctt(2).
       All you need to do  is  call  rruunnaallaarrmmss(())  when  sseelleecctt(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 sseettiittiimmeerr(2) system call, although
       overall precision is of course still determined by the underlying oper-
       ating system.  Recommended.

SEE ALSO
       ssnnmmppaappii(3),     ddeeffaauullttssttoorree(3),    ssnnmmppsseelleeccttiinnffoo(3),    aallaarrmm(2),
       sseettiittiimmeerr(2), sseelleecctt(2)



4.2 Berkeley Distribution         07 Mar 2002                    SNMPALARM(3)