snmp_alarm_register_hr(3)

1SNMP_ALARM(3)                      Net-SNMP                      SNMP_ALARM(3)
2
3
4

NAME

6       snmp_alarm_register,  snmp_alarm_register_hr,  snmp_alarm_unregister  -
7       alarm functions
8

SYNOPSIS

10       #include <net-snmp/utilities.h>
11
12       unsigned int
13       snmp_alarm_register(unsigned int seconds,
14                           unsigned int flags,
15                           SNMPAlarmCallback *f_callback,
16                           void *clientarg);
17
18       unsigned int
19       snmp_alarm_register_hr(struct timeval t,
20                              unsigned int flags,
21                              SNMPAlarmCallback *f_callback,
22                              void *clientarg);
23
24       void
25       snmp_alarm_unregister(unsigned int reg);
26

DESCRIPTION

28       These functions implement support for a generic timer  handling  mecha‐
29       nism  for  multiple  parts of an application to register function call‐
30       backs to happen at a particular time in the future.
31

USAGE

33       The usage is fairly simple and straight-forward:  Simply create a func‐
34       tion  you  want  called back at some point in the future.  The function
35       definition should be similar to:
36
37           void my_callback(unsigned int reg, void *clientarg);
38
39       Then, call snmp_alarm_register() to register your callback to be called
40       seconds  from now.  The flags field should either be SA_REPEAT or NULL.
41       If flags is set with SA_REPEAT, then the registered  callback  function
42       will  be called every seconds.  If flags is NULL then the function will
43       only be called once and then removed from the  alarm  system  registra‐
44       tion.
45
46       The  clientarg  parameter  in the registration function is used only by
47       the client function and is stored and passed back directly to  them  on
48       every call to the system.
49
50       The snmp_alarm_register() function returns a unique unsigned int (which
51       is also passed as the first argument of each callback), which can  then
52       be  used  to remove the callback from the queue at a later point in the
53       future   using   the   snmp_alarm_unregister()   function.    If    the
54       snmp_alarm_register()  call fails it returns zero.  In particular, note
55       that it is entirely permissible for an alarm function to unregister it‐
56       self.
57
58       The  snmp_alarm_register_hr() function is identical in operation to the
59       snmp_alarm_register() function, but takes a struct timeval as  a  first
60       parameter, and schedules the callback after the period represented by t
61       (the letters hr stand for "high resolution").  The  operation  of  this
62       function  is dependent on the provision of the setitimer(2) system call
63       by the operating system.  If this system call  is  not  available,  the
64       alarm  will  be  scheduled  as if snmp_alarm_register() had been called
65       with a first argument equal to the value of the  tv_sec  member  of  t.
66       See, however, the notes below.
67

INITIALIZATION

69       The  init_snmp() function initialises the snmp_alarm subsystem by call‐
70       ing init_snmp_alarm() and then init_alarm_post_config() to set  up  the
71       first  timer  to initialise the callback function.  These two functions
72       should not be used directly by applications.
73

NOTES

75       The default behaviour of the snmp_alarm subsystem is to request SIGALRM
76       signals from the operating system via the alarm(2) or setitimer(2) sys‐
77       tem calls.  This has the disadvantage, however, that no other  part  of
78       the  application  can  use the SIGLARM functionality (or, if some other
79       part of  the  application  does  use  the  SIGALRM  functionality,  the
80       snmp_alarm subsystem will not work correctly).
81
82       If  your  application runs a select(2)-based event loop, however, there
83       is no need to use SIGALRM for  the  snmp_alarm  subsystem,  leaving  it
84       available  for  other parts of the application.  This is done by making
85       the following call:
86
87       netsnmp_ds_set_boolean(NETSNMP_DS_LIBRARY_ID,
88                              NETSNMP_DS_LIB_ALARM_DONT_USE_SIG, 1);
89
90       before calling init_snmp().  Then, snmp_select_info() takes alarms into
91       account  when  calculating  the timeout value to be used for select(2).
92       All you need to do is call run_alarms() when select(2) times  out  (re‐
93       turn  value of zero).  This is the approach taken in the agent; see sn‐
94       mpd.c.  Furthermore, when using this method, high resolution alarms  do
95       not  depend  on  the presence of the setitimer(2) system call, although
96       overall precision is of course still determined by the underlying oper‐
97       ating system.  Recommended.
98

NAME

SYNOPSIS

DESCRIPTION

USAGE

INITIALIZATION

NOTES

SEE ALSO