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

SNMP编程

开发平台:

Unix_Linux

  1. .TH READ_CONFIG 3 "07 Mar 2002" "" "Net-SNMP"
  2. .UC 5
  3. .SH NAME
  4. register_config_handler, register_premib_handler
  5. unregister_config_handler, register_mib_handlers, read_configs,
  6. read_premib_configs, config_perror, config_pwarn - read_config functions
  7. .SH SYNOPSIS
  8. .B #include <net-snmp/config_api.h>
  9. .PP
  10. .B struct config_line *
  11. .br
  12. .BI "  register_config_handler(const char *" filePrefix ",
  13. .br
  14. .BI "                     const char *" token ,
  15. .br
  16. .BI "                     void (*" parser ")(const char *, char *),"
  17. .br
  18. .BI "                     void (*" releaser ")(void),"
  19. .br
  20. .BI "                     const char *"usageLine ");"
  21. .PP
  22. .B struct config_line *
  23. .br
  24. .BI "  register_premib_handler(const char *" filePrefix ", 
  25. .br
  26. .BI "                     const char *" token ,
  27. .br
  28. .BI "                     void (*" parser ")(const char *, char *),"
  29. .br
  30. .BI "                     void (*" releaser ")(void),"
  31. .br
  32. .BI "                     const char *" usageLine ");"
  33. .PP
  34. .BI "void unregister_config_handler(const char *" filePrefix ","
  35. .br
  36. .BI "                     const char *" token ");"
  37. .PP
  38. .B struct config_line *
  39. .br
  40. .BI "  register_app_config_handler(const char *" token ,
  41. .br
  42. .BI "                     void (*" parser ")(const char *, char *),"
  43. .br
  44. .BI "                     void (*" releaser ")(void),"
  45. .br
  46. .BI "                     const char *"usageLine ");"
  47. .PP
  48. .B struct config_line *
  49. .br
  50. .BI "  register_app_premib_handler(const char *" token ,
  51. .br
  52. .BI "                     void (*" parser ")(const char *, char *),"
  53. .br
  54. .BI "                     void (*" releaser ")(void),"
  55. .br
  56. .BI "                     const char *" usageLine ");"
  57. .PP
  58. .BI "void unregister_app_config_handler(const char *" token ");"
  59. .PP
  60. .BI "void read_config_print_usage(char *" lead ");"
  61. .PP
  62. .B "void read_configs(void);"
  63. .PP
  64. .B "void read_premib_configs(void);"
  65. .PP
  66. .BI "void config_pwarn(const char *" string ");"
  67. .br
  68. .BI "void config_perror(const char *" string ");"
  69. .SH DESCRIPTION
  70. The functions are a fairly extensible system of parsing various
  71. configuration files at the run time of an application.  The
  72. configuration file flow is broken into the following phases:
  73. .RS 4
  74. .TP 4
  75. 1.
  76. Registration of handlers.
  77. .TP
  78. 2.
  79. Reading of the configuration files for pre-MIB parsing requirements.
  80. .TP
  81. 3.
  82. Reading and parsing of the textual MIB files.
  83. .TP
  84. 4.
  85. Reading of the configuration files for configuration directives.
  86. .TP
  87. 5.
  88. Optionally re-reading the configuration files at a future date.
  89. .RE
  90. .PP
  91. The idea is that the calling application is able to register
  92. .I handlers
  93. for certain
  94. .I tokens
  95. specified in certain types of
  96. .I files.
  97. The 
  98. .B read_configs()
  99. function can then be called to look for all the files that it has
  100. registrations for, find the first word on each line, and pass the
  101. remainder to the appropriately registered handler.
  102. .SH TOKEN HANDLERS
  103. .PP
  104. Handler functions should have the following signature:
  105. .PP
  106. .RS
  107. .BI "void handler(const char *" token ", char *" line ");"
  108. .RE
  109. .PP
  110. The function will be called with two arguments, the first being the
  111. token that triggered the call to this function (which would be one of
  112. the tokens that the function had been registered for), and the second
  113. being the remainder of the configuration file line beyond the white
  114. space following the token.
  115. .SH RESOURCE FREEING HANDLERS
  116. .PP
  117. If the parameter
  118. .I releaser
  119. passed to
  120. .B register_config_handler
  121. is non-NULL, then the function specified is called if and when the
  122. configuration files are re-read.  This function should free any
  123. resources allocated by the token handler function and reset its notion
  124. of the configuration to its default.  The token handler function will
  125. then be called again.  No arguments are passed to the resource freeing
  126. handler.
  127. .SH REGISTERING A HANDLER
  128. .TP
  129. .B register_config_handler()
  130. The
  131. .B handler()
  132. function above could be registered for the configuration file
  133. .I snmp.conf,
  134. with the token
  135. .I genericToken
  136. and the help string (discussed later)
  137. .I """ARG1 [ARG2]"""
  138. using the following call to the 
  139. .B register_config_handler()
  140. function:
  141. .PP
  142. .RS
  143. .RS
  144. register_config_handler("snmp", "genericToken", handler, NULL, "ARG1 [ARG2]");
  145. .RE
  146. .RE
  147. .IP
  148. This would register the
  149. .B handler()
  150. function so that it will get called every time the first word of a
  151. line in the 
  152. .I snmp.conf
  153. configuration file(s) matches "genericToken" (see 
  154. .B read_configs() 
  155. below).
  156. .TP
  157. .B register_premib_handler()
  158. The 
  159. .B register_premib_handler()
  160. function works identically to the 
  161. .B register_config_handler()
  162. function but is intended for config file tokens that need to be read
  163. in before the textual MIBs are read in, probably because they will be
  164. used to configure the MIB parser.  It is rarely the case that anything 
  165. but the SNMP library itself should need to use this function.
  166. .TP
  167. .B unregister_config_handler()
  168. Removes the registered configuration handler for the
  169. .I filePrefix
  170. and
  171. .IR token .
  172. .TP
  173. .B register_app_config_handler()
  174. .TP
  175. .B register_app_premib_handler()
  176. .TP
  177. .B unregister_app_config_handler()
  178. These functions are analagous to 
  179. .BR register_config_handler() ", " register_premib_handler() " and "
  180. .B unregister_config_handler()
  181. but don't require the file type argument (which is filled in by the
  182. application).  It is intended that MIB modules written for the agent
  183. use these functions to allow the agent to have more control over which
  184. configuration files are read (typically the
  185. .I snmpd.conf
  186. files).
  187. .SH HELP STRINGS
  188. .PP
  189. The
  190. .I usageLine
  191. parameter passed to
  192. .B register_config_handler()
  193. and similar calls, is used to display help information when the
  194. .B read_config_print_usage()
  195. function is called.  This function is used by all of the applications
  196. when the 
  197. .B -H
  198. flag is passed on the command line.  It prints a summary of all of the
  199. configuration file lines, and the associated files, that the
  200. configuration system understands.  The
  201. .I usageLine
  202. parameter should be a list of arguments expected after the token, and
  203. not a lengthy description (which should go into a manual page
  204. instead).  The
  205. .I lead
  206. prefix will be prepended to each line that the function prints to
  207. stderr, where it displays its output.
  208. .PP
  209. The
  210. .B init_snmp()
  211. function should be called before the
  212. .B read_config_print_usage()
  213. function is called, so that the library can register its configuration 
  214. file directives as well for the 
  215. .B read_config_print_usage()
  216. function to display.
  217. .SH READING CONFIGURATION FILES
  218. .TP
  219. .B init_snmp()
  220. Once the relevant configuration token parsers have been registered,
  221. .B init_snmp()
  222. should be called.  It will parse the configuration file tokens
  223. registered with
  224. .B register_premib_handler(),
  225. read in the textual MIB files using
  226. .B init_mib(),
  227. and finally parse the configuration file tokens registered with 
  228. .BR register_config_handler() .
  229. .PP
  230. If the 
  231. .B init_snmp()
  232. function is used, none of the following functions need to be called by 
  233. the application:
  234. .TP
  235. .B register_mib_handlers()
  236. The SNMP library's routine to register its configuration file
  237. handlers.
  238. .TP
  239. .B read_premib_configs()
  240. The routine that parses the configuration files for tokens registered
  241. to be dealt with before the textual MIBs are read in.  See 
  242. .B read_configs()
  243. below.
  244. .TP
  245. .B read_configs()
  246. Reads all the configuration files it can find in the 
  247. .I SNMPCONFPATH
  248. environment variable (or its default value) for tokens and
  249. appropriately calls the handlers registered to it, or prints a
  250. "Unknown token" warning message.  It looks for any file that it has
  251. previously received a registration request for.
  252. .SH CONFIGURATION FILES READ
  253. .PP
  254. The configuration files read are found by using the colon separated
  255. .I SNMPCONFPATH
  256. environment variable (or its default value, which will be
  257. SYSCONFDIR/snmp, followed by
  258. DATADIR/snmp, followed by LIBDIR/snmp, followed by $HOME/.snmp) and
  259. reading in the files found that match both the prefix registered and
  260. the two suffixes
  261. .I .conf
  262. and
  263. .I .local.conf.
  264. The idea behind the two different suffixes is that the first file can
  265. be shared (via rdist or an NFS mount) across a large number of
  266. machines and the second file can be used to configure local settings
  267. for one particular machine.  They do not need to be present, and will
  268. only be read if found.
  269. .SH ERROR HANDLING FUNCTIONS
  270. .PP
  271. The two functions
  272. .B config_pwarn()
  273. and
  274. .B config_perror()
  275. both take an error string as an argument and print it to stderr along
  276. with the file and line number that caused the error.  A call to the
  277. second function will also force 
  278. .B read_configs() 
  279. to eventually return with an error code indicating to it's calling
  280. function that it should abort the operation of the application.
  281. .SH "ENVIRONMENT VARIABLES"
  282. .TP 10
  283. SNMPCONFPATH
  284. A colon separated list of directories to search for configuration
  285. files in.
  286. Default: SYSCONFDIR/snmp:DATADIR/snmp:LIBDIR/snmp:$HOME/.snmp
  287. .SH "SEE ALSO"
  288. .BR mib_api "(3), " snmp_api (3)
  289. ." Local Variables:
  290. ."  mode: nroff
  291. ." End: