1SNMP_ALARM(3) Net-SNMP SNMP_ALARM(3)
2
6 snmp_alarm_register, snmp_alarm_register_hr, snmp_alarm_unregister -
7 alarm functions
8
10 #include <net-snmp/utilities.h>
11 unsigned int
13 snmp_alarm_register(unsigned int seconds,
14 unsigned int flags,
15 SNMPAlarmCallback *f_callback,
16 void *clientarg);
17 unsigned int
19 snmp_alarm_register_hr(struct timeval t,
20 unsigned int flags,
21 SNMPAlarmCallback *f_callback,
22 void *clientarg);
23 void
25 snmp_alarm_unregister(unsigned int reg);
26
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
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 void my_callback(unsigned int reg, void *clientarg);
38 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 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 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
56 itself.
57 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
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
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 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 netsnmp_ds_set_boolean(NETSNMP_DS_LIBRARY_ID,
88 NETSNMP_DS_LIB_ALARM_DONT_USE_SIG, 1);
89 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
93 (return value of zero). This is the approach taken in the agent; see
94 snmpd.c. Furthermore, when using this method, high resolution alarms
95 do 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
100 netsnmp_session_api(3), default_store(3), alarm(2), setitimer(2),
101 select(2)
102V5.9 01 Aug 2002 SNMP_ALARM(3)