userapps/opensource/net-snmp/man/read_config.3.def

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