manual/ucd-snmp/original/man3/read_config.3

   1 .TH READ_CONFIG 3 "02 Mar 1999"
   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 <read_config.h>
   9 .PP
  10 .B struct config_line *
  11 .br
  12 .B "  register_config_handler(char *filePrefix, char *token,"
  13 .br
  14 .B "            void (*parser)(char *, char *) handler, "
  15 .br
  16 .B "            void (*releaser) (void) freefunc,"
  17 .br
  18 .B "            char *usageLine)"
  19 .PP
  20 .B struct config_line *
  21 .br
  22 .B "  register_premib_handler(char *filePrefix, char *token,"
  23 .br
  24 .B "            void (*parser)(char *, char *) handler, "
  25 .br
  26 .B "            void (*releaser) (void) freefunc,"
  27 .br
  28 .B "            char *usageLine)"
  29 .PP
  30 .B struct config_line *
  31 .br
  32 .B "  snmpd_register_config_handler(char *token,"
  33 .br
  34 .B "            void (*parser)(char *, char *) handler, "
  35 .br
  36 .B "            void (*releaser) (void) freefunc,"
  37 .br
  38 .B "            char *usageLine)"
  39 .PP
  40 .B "void unregister_config_handler(char *filePrefix, "
  41 .br
  42 .B "            char *token)"
  43 .PP
  44 .B "void read_config_print_usage(char *lead)"
  45 .PP
  46 .B "void read_configs(void)"
  47 .PP
  48 .B "void read_premib_configs(void)"
  49 .PP
  50 .SH DESCRIPTION
  51 The functions are a fairly extensible system of parsing various
  52 configuration files at the run time of an application.  The
  53 configuration file flow is broken into the following phases:
  54 .RS
  55 .PP
  56 registration of handlers.
  57 .PP
  58 reading of the configuration files for pre-mib parsing requirements.
  59 .PP
  60 reading of the textual mib files.
  61 .PP
  62 reading of the configuration files for configuration directives.
  63 .PP
  64 optionally re-reading of the configuration files at a future date.
  65 .RE
  66 .PP
  67 The idea is that the calling application is able to register
  68 .I handlers
  69 for certain
  70 .I tokens
  71 specified in certain types of
  72 .I files.
  73 The
  74 .B read_configs()
  75 function can then be called to look for all the files that it has
  76 registrations for, find the first word on each line, and pass the
  77 remainder to the appropriately registered handler.
  78 .SH Token Handlers
  79 .PP
  80 Handler functions should be of the following type:
  81 .PP
  82 .RS
  83 void handler(char *token, char *line);
  84 .RE
  85 .PP
  86 The function will be called with two arguments, the first being the
  87 token that triggered the call to this function (which would be one of
  88 the tokens that the function had been registered for), and the second
  89 being the remainder of the configuration file line beyond the white
  90 space following the token.
  91 .SH Resource Freeing Handlers
  92 .PP
  93 If the read_config configuration system is called a second time to
  94 re-read the configuration files, the optional second handler
  95 .I freefunc
  96 will be called, if registered as non-NULL, to free any resources and
  97 reset its notions to defaults before the config handlers are called
  98 again.  It is not called with any arguments.
  99 .SH Registering A Handler
 100 .IP register_config_handler()
 101 The handler above could then be registered for the configuration file
 102 .I snmp.conf,
 103 with the token
 104 .I genericToken
 105 and the help string (discussed later)
 106 .I ARG1 ARG2
 107 using the following call to the
 108 .B register_config_handler()
 109 function:
 110 .PP
 111 .RS
 112 .RS
 113 register_config_handler("snmp", "genericToken", handler, NULL, "ARG1 ARG2");
 114 .RE
 115 .RE
 116 .IP
 117 This would register the
 118 .B handler()
 119 function so that it will get called every time the first word in the
 120 .I snmp.conf
 121 configuration file(s) matches "genericToken" (see
 122 .B read_configs()
 123 below).
 124 .IP register_premib_handler()
 125 The
 126 .B register_premib_handler()
 127 function works identically to the
 128 .B register_config_handler()
 129 function but is intended for config file tokens that need to be read
 130 in before the textual mibs are read in, probably because they will be
 131 used to configure the mib parser.  It is rarely the case that anything
 132 but the snmp library itself should need to use this function.
 133 .IP snmpd_register_config_handler()
 134 This function performs exactly the same job as the
 135 .B register_config_handler()
 136 function, but doesn't require the file type argument (which is filled
 137 in by the snmpd agent).  It is intended that mib modules written for
 138 the agent use this function instead of the
 139 .B register_config_handler()
 140 function directly to allow the agent to have more control over which
 141 files the mib modules will read (which should be the
 142 .I snmpd.conf
 143 files).
 144 .IP unregister_config_handler()
 145 Removes the registered configuration handler for the
 146 .I filePrefix
 147 and
 148 .I token
 149 .IP
 150 .SH Help Strings
 151 .PP
 152 The
 153 .I usageLine
 154 token passed to the register_config_handler(), and similar calls, is
 155 used to display help information when the
 156 .B read_config_print_usage()
 157 function is called.  This function is used by all of the applications
 158 when the
 159 .B -H
 160 flag is passed to the command line.  It prints a summary of all of the
 161 configuration file lines, and the associated files, that the
 162 configuration system understands.  The usageLine parameter should be a
 163 list of arguments expected after the token, and not a lengthy
 164 description (which should go into a manual page instead).  The
 165 .I lead
 166 prefix will be prepended to each line that the function prints to
 167 stderr, where it displays its output.
 168 .PP
 169 The
 170 .B init_snmp()
 171 function should be called before the
 172 .B read_config_print_usage()
 173 function is called, so that the library can register its configuration
 174 file directives as well for the
 175 .B read_config_print_usage()
 176 function to display.
 177 .SH Reading Configuration Files
 178 .IP init_snmp()
 179 The
 180 .B init_snmp()
 181 function call should be called after registrations to appropriately
 182 register parser configuration tokens, parse the configuration file
 183 tokens registered with
 184 .B register_premib_handler(),
 185 read in the textual mib files using
 186 .B init_mib(),
 187 and finally parse the configuration file tokens registered with
 188 .B register_config_handler().
 189 .PP
 190 If the
 191 .B init_snmp()
 192 function is used, none of the following functions need to be called by
 193 the application:
 194 .PP
 195 .IP register_mib_handlers()
 196 The snmp library's routine to register it's configuration file
 197 handlers.
 198 .IP read_premib_configs()
 199 The routine that parses the configuration files for tokens registered
 200 to be dealt with before the textual mibs are read in.  See
 201 .B read_configs()
 202 below.
 203 .IP read_configs()
 204 Reads all the configuration files it can find in the
 205 .I SNMPCONFPATH
 206 environment variable (or its default value) for tokens and
 207 appropriately calls the handlers registered to it, or prints a
 208 "Unknown token" warning message.  It looks for any file that it has
 209 previously received a registration request for.
 210 .SH Configuration Files Read
 211 .PP
 212 The configuration files read are found by using the colon separated
 213 .I SNMPCONFPATH
 214 environment variable (or its default value, which will be
 215 /usr/share/snmp, followed by /usr/lib/snmp, followed by $HOME/.snmp) and
 216 reading in the files found that match both the prefix registered and
 217 the two suffixes
 218 .I .conf
 219 and
 220 .I .local.conf.
 221 The idea behind the two different suffixes is that the first file can
 222 be rdisted across a large number of machines and the second file can
 223 be used to configure local settings for one particular machine.  They
 224 do not need to be present, and will only be read if found.
 225 .SH Error Handling Functions
 226 .PP
 227 The two functions
 228 .B config_pwarn()
 229 and
 230 .B config_perror()
 231 both take an error string as an argument and print it to stderr along
 232 with the file and line number that caused the error.  A call to the
 233 second function will also force read_configs() to eventually return
 234 with an error code indicating to it's calling function that it should
 235 abort the operation of the application.
 236 .SH "ENVIRONMENT VARIABLES"
 237 .TP 10
 238 SNMPCONFPATH
 239 A colon separated list of directories to search for configuration
 240 files in.
 241 Default: /usr/share/snmp:/usr/lib/snmp:$HOME/.snmp
 242 .SH "SEE ALSO"
 243 mib_api(3), snmp_api(3)
 244 .\" Local Variables:
 245 .\"  mode: nroff
 246 .\" End: