1 .TH SNMP_ALARM 3 "07 Mar 2002" VVERSIONINFO "Net-SNMP"
4 snmp_alarm_register, snmp_alarm_register_hr, snmp_alarm_unregister - alarm functions
6 .B #include <net-snmp/utilities.h>
10 .BI "snmp_alarm_register(unsigned int " seconds ","
12 .BI " unsigned int " flags ","
14 .BI " SNMPAlarmCallback *" f_callback ","
16 .BI " void *" clientarg ");"
20 .BI "snmp_alarm_register_hr(struct timeval " t ","
22 .BI " unsigned int " flags ","
24 .BI " SNMPAlarmCallback *" f_callback ","
26 .BI " void *" clientarg ");"
30 .BI "snmp_alarm_unregister(unsigned int " reg ");"
33 These functions implement support for a generic timer handling
34 mechanism for multiple parts of an application to register function
35 callbacks to happen at a particular time in the future.
38 The usage is fairly simple and straight-forward: Simply create a
39 function you want called back at some point in the future. The
40 function definition should be similar to:
43 .BI "void my_callback(unsigned int " reg ", void *" clientarg ");"
47 .B snmp_alarm_register()
48 to register your callback to be called
52 field should either be
58 then the registered callback function will be called every
64 then the function will only be called once and then removed from the
65 alarm system registration.
69 parameter in the registration function is used only by
70 the client function and is stored and passed back directly to them on
71 every call to the system.
74 .B snmp_alarm_register()
75 function returns a unique
77 (which is also passed as the first argument of each callback), which
78 can then be used to remove the callback from the queue at a later
79 point in the future using the
80 .B snmp_alarm_unregister()
82 .B snmp_alarm_register()
83 call fails it returns zero. In particular, note that it is entirely
84 permissible for an alarm function to unregister itself.
87 .B snmp_alarm_register_hr()
88 function is identical in operation to the
89 .B snmp_alarm_register()
92 as a first parameter, and schedules the callback after the period
97 stand for "high resolution"). The operation of this function is
98 dependent on the provision of the
100 system call by the operating system. If this system call is not
101 available, the alarm will be scheduled as if
102 .B snmp_alarm_register()
103 had been called with a first argument equal to the value of the
107 See, however, the notes below.
111 function initialises the snmp_alarm subsystem by calling
114 .B init_alarm_post_config()
115 to set up the first timer to initialise the callback function. These
116 two functions should not be used directly by applications.
118 The default behaviour of the snmp_alarm subsystem is to request
120 signals from the operating system via the
124 system calls. This has the disadvantage, however, that no other part
125 of the application can use the
127 functionality (or, if some other part of the application
131 functionality, the snmp_alarm subsystem will not work correctly).
133 If your application runs a
135 event loop, however, there is no need to use
137 for the snmp_alarm subsystem, leaving it available for other parts of
138 the application. This is done by making the following call:
141 netsnmp_ds_set_boolean(NETSNMP_DS_LIBRARY_ID,
142 NETSNMP_DS_LIB_ALARM_DONT_USE_SIG, 1);
148 .BR snmp_select_info()
149 takes alarms into account when calculating the timeout value to be
152 All you need to do is call
156 times out (return value of zero). This is the approach taken in the
159 Furthermore, when using this method, high resolution alarms do not
160 depend on the presence of the
162 system call, although overall precision is of course still determined
163 by the underlying operating system. Recommended.
165 .BR snmp_api "(3), " default_store "(3), " snmp_select_info "(3), "
166 .BR alarm "(2), " setitimer "(2), " select "(2)"