Manual Pages for UNIX Operating System command usage for man snmp_alarm

Net-SNMP                                            SNMP_ALARM(3)



NAME
     snmp_alarm_register,                 snmp_alarm_register_hr,
     snmp_alarm_unregister - alarm functions

SYNOPSIS
     #include 

     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  han-
     dling  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 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 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



V5.4.1              Last change: 07 Mar 2002                    1






Net-SNMP                                            SNMP_ALARM(3)



     snmp_alarm_register()  call  fails it returns zero.  In par-
     ticular, note that it is entirely permissible for  an  alarm
     function to unregister itself.

     The snmp_alarm_register_hr() function is identical in opera-
     tion  to  the  snmp_alarm_register()  function,  but takes a
     struct timeval as a first parameter, and schedules the call-
     back 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  subsys-
     tem     by     calling     init_snmp_alarm()     and    then
     init_alarm_post_config() to set up the first timer  to  ini-
     tialise  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  disad-
     vantage,  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,  how-
     ever,  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),



V5.4.1              Last change: 07 Mar 2002                    2






Net-SNMP                                            SNMP_ALARM(3)



     alarm(2), setitimer(2), select(2)

ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:

     _______________________________________________________
    |   ATTRIBUTE TYPE   |          ATTRIBUTE VALUE        |
    |____________________|__________________________________|_
    | Availability       |  system/management/snmp/net-snmp|
    |____________________|__________________________________|_
    | Interface Stability|  Volatile                       |
    |____________________|_________________________________|

NOTES
     Source for net-snmp is available on http://opensolaris.org.







































V5.4.1              Last change: 07 Mar 2002                    3