snmp_alarm.3.def
上传用户:wxp200602
上传日期:2007-10-30
资源大小:4028k
文件大小:5k
源码类别:

SNMP编程

开发平台:

Unix_Linux

  1. .TH SNMP_ALARM 3 "07 Mar 2002" VVERSIONINFO "Net-SNMP"
  2. .UC 5
  3. .SH NAME
  4. snmp_alarm_register, snmp_alarm_register_hr, snmp_alarm_unregister - alarm functions
  5. .SH SYNOPSIS
  6. .B #include <net-snmp/utilities.h>
  7. .PP
  8. .B "unsigned int"
  9. .br
  10. .BI "snmp_alarm_register(unsigned int " seconds ","
  11. .br
  12. .BI "                    unsigned int " flags ","
  13. .br
  14. .BI "                    SNMPAlarmCallback *" f_callback ","
  15. .br
  16. .BI "                    void *" clientarg ");"
  17. .PP
  18. .B "unsigned int"
  19. .br
  20. .BI "snmp_alarm_register_hr(struct timeval " t ","
  21. .br
  22. .BI "                       unsigned int " flags ","
  23. .br
  24. .BI "                       SNMPAlarmCallback *" f_callback ","
  25. .br
  26. .BI "                       void *" clientarg ");"
  27. .PP
  28. .B "void
  29. .br
  30. .BI "snmp_alarm_unregister(unsigned int " reg ");"
  31. .SH DESCRIPTION
  32. .PP
  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.
  36. .SH USAGE
  37. .PP
  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:
  41. .RS 4
  42. .PP
  43. .BI "void my_callback(unsigned int " reg ", void *" clientarg ");"
  44. .RE
  45. .PP
  46. Then, call
  47. .B snmp_alarm_register()
  48. to register your callback to be called
  49. .I seconds
  50. from now.  The
  51. .I flags
  52. field should either be 
  53. .I SA_REPEAT
  54. or
  55. .I NULL.
  56. If flags is set with
  57. .I SA_REPEAT,
  58. then the registered callback function will be called every
  59. .I seconds.
  60. If
  61. .I flags
  62. is
  63. .I NULL
  64. then the function will only be called once and then removed from the
  65. alarm system registration.
  66. .PP
  67. The
  68. .I clientarg
  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.
  72. .PP
  73. The 
  74. .B snmp_alarm_register()
  75. function returns a unique
  76. .I "unsigned int"
  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()
  81. function. If the
  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.
  85. .PP
  86. The
  87. .B snmp_alarm_register_hr()
  88. function is identical in operation to the
  89. .B snmp_alarm_register()
  90. function, but takes a
  91. .I "struct timeval"
  92. as a first parameter, and schedules the callback after the period
  93. represented by
  94. .I t
  95. (the letters
  96. .B hr
  97. stand for "high resolution").  The operation of this function is
  98. dependent on the provision of the
  99. .BR setitimer (2)
  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
  104. .I tv_sec
  105. member of
  106. .IR "t".
  107. See, however, the notes below.
  108. .SH INITIALIZATION
  109. The
  110. .B init_snmp()
  111. function initialises the snmp_alarm subsystem by calling 
  112. .B init_snmp_alarm()
  113. and then 
  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.
  117. .SH "NOTES"
  118. The default behaviour of the snmp_alarm subsystem is to request
  119. .I SIGALRM
  120. signals from the operating system via the
  121. .BR alarm (2)
  122. or
  123. .BR setitimer (2)
  124. system calls.  This has the disadvantage, however, that no other part
  125. of the application can use the
  126. .I SIGLARM
  127. functionality (or, if some other part of the application
  128. .I does
  129. use the
  130. .I SIGALRM
  131. functionality, the snmp_alarm subsystem will not work correctly).
  132. .PP
  133. If your application runs a 
  134. .BR select (2)-based
  135. event loop, however, there is no need to use
  136. .I SIGALRM
  137. for the snmp_alarm subsystem, leaving it available for other parts of
  138. the application.  This is done by making the following call:
  139. .PP
  140. .nf
  141. netsnmp_ds_set_boolean(NETSNMP_DS_LIBRARY_ID, 
  142.                        NETSNMP_DS_LIB_ALARM_DONT_USE_SIG, 1);
  143. .fi
  144. .PP
  145. before calling
  146. .BR "init_snmp()".
  147. Then, 
  148. .BR snmp_select_info()
  149. takes alarms into account when calculating the timeout value to be
  150. used for
  151. .BR select (2).
  152. All you need to do is call
  153. .BR run_alarms()
  154. when
  155. .BR select (2)
  156. times out (return value of zero).  This is the approach taken in the
  157. agent; see
  158. .IR "snmpd.c".
  159. Furthermore, when using this method, high resolution alarms do not
  160. depend on the presence of the
  161. .BR setitimer (2)
  162. system call, although overall precision is of course still determined
  163. by the underlying operating system.  Recommended.
  164. .SH "SEE ALSO"
  165. .BR snmp_api "(3), " default_store "(3), " snmp_select_info "(3), "
  166. .BR alarm "(2), " setitimer "(2), " select "(2)"
  167. ." Local Variables:
  168. ."  mode: nroff
  169. ." End: