1CONFIG_API(3) Net-SNMP CONFIG_API(3)
2
6 register_config_handler, register_premib_handler unregister_config_han‐
7 dler, register_mib_handlers, read_configs, read_premib_configs, con‐
8 fig_perror, config_pwarn - config_api functions
9
11 #include <net-snmp/config_api.h>
12 struct config_line *
14 register_config_handler(const char *filePrefix,
15 const char *token,
16 void (*parser)(const char *, char *),
17 void (*releaser)(void),
18 const char *usageLine);
19 struct config_line *
21 register_premib_handler(const char *filePrefix,
22 const char *token,
23 void (*parser)(const char *, char *),
24 void (*releaser)(void),
25 const char *usageLine);
26 void register_mib_handlers(void);
28 void unregister_config_handler(const char *filePrefix,
30 const char *token);
31 void unregister_all_config_handlers(void);
33 Application Handlers
35 struct config_line *
36 register_app_config_handler(const char *token,
37 void (*parser)(const char *, char *),
38 void (*releaser)(void),
39 const char *usageLine);
40 struct config_line *
42 register_app_premib_handler(const char *token,
43 void (*parser)(const char *, char *),
44 void (*releaser)(void),
45 const char *usageLine);
46 void unregister_app_config_handler(const char *token);
48 Reading Configuration Files
50 void read_premib_configs(void);
51 void read_configs(void);
52 Help Strings and Errors
54 void read_config_print_usage(char *lead);
55 void config_pwarn(const char *string);
56 void config_perror(const char *string);
57
60 The functions are a fairly extensible system of parsing various config‐
61 uration files at the run time of an application. The configuration
62 file flow is broken into the following phases:
63 1. Registration of handlers.
65 2. Reading of the configuration files for pre-MIB parsing require‐
67 ments.
68 3. Reading and parsing of the textual MIB files.
70 4. Reading of the configuration files for configuration direc‐
72 tives.
73 5. Optionally re-reading the configuration files at a future date.
75 The idea is that the calling application is able to register handlers
77 for certain tokens specified in certain named configuration files. The
78 read_configs() function can then be called to look for all relevant
79 configuration files, match the first word on each line against the list
80 of registered tokens and pass the remainder of the line to the appro‐
81 priate registered handler.
82
84 register_config_handler()
85 Registers a configuration handler routine, which should be
86 called to process configuration directives starting with the
87 specified token. For example:
88 register_config_handler("snmp", "exampleToken", exam‐
90 ple_handler, NULL, "ARG1 [ARG2]");
91 would register the example_handler() function so that it will
93 get called every time the first word of a line in the snmp.conf
94 configuration file(s) matches "exampleToken".
95 Calling the appropriate handlers to process the configuration
96 file directives is the responsibility of read_configs() (see
97 below).
98 register_premib_handler()
100 Similar to the register_config_handler() function, but the reg‐
101 istered handler routine will be called before the textual MIBs
102 are read in. This is typically used for tokens that will affect
103 the configuration of the MIB parser, and will normally only be
104 used within the SNMP library itself.
105 register_mib_handlers()
107 Initialisation routine to register the internal SNMP library
108 configuration handlers.
109 unregister_config_handler()
111 Removes the registered configuration handler for the specified
112 filePrefix and token.
113 unregister_all_config_handlers()
115 Removes all registered configuration handlers.
116 Token Handlers
119 Handler functions should have the following signature:
120 void handler(const char *token, char *line);
122 The function will be called with two arguments, the first being the
124 token that triggered the call to this function (i.e. the token used
125 when registering the handler), and the second being the remainder of
126 the configuration file line (i.e. everything following the white space
127 following the matched token).
128 Freeing Handlers
131 If the token handler function dynamically allocates resources when pro‐
132 cessing a configuration entry, then these may need to be released
133 before re-reading the configuration files. If the fourth parameter (
134 releaser ) passed to register_config_handler is non-NULL, then this
135 specifies a function to be called before re-reading the configuration
136 files. This function should free any resources allocated by the token
137 handler function and reset its notion of the configuration to its
138 default. The token handler function can then safely be called again.
139 No arguments are passed to the resource freeing handler.
140 Note that this function is not called when the handler is unregistered
141 individually (but is called as part of unregister_all_config_handlers()
142 ).
143 Application Handlers
146 register_app_config_handler()
147 register_app_premib_handler()
149 unregister_app_config_handler()
151 These functions are analagous to register_config_handler(), reg‐
152 ister_premib_handler() and unregister_config_handler() but do
153 not require the file type argument (which is filled in by the
154 application). It is intended that MIB modules written for the
155 agent use these functions to allow the agent to have more con‐
156 trol over which configuration files are read (typically the
157 snmpd.conf files).
158
160 read_premib_configs()
161 read_configs()
163 These routines process the configuration files found in the con‐
164 figuration search path (see below). For each entry, the handler
165 registered for that configuration token is called.
166 read_premib_configs() is run before the MIB files are read in, and pro‐
168 cesses those configuration tokens registered using register_premib_han‐
169 dler() (or register_app_premib_handler() ). All other entries are
170 ignored.
171 read_configs() is run after the MIB files have been read in, and pro‐
173 cesses those configuration tokens registered using register_config_han‐
174 dler() (or register_app_config_handler() ). If it encounters a config‐
175 uration token for which no handler has been registered (either pre- or
176 post-mib), then it will display a warning message, and continue pro‐
177 cessing with the next line of the configuration file.
178 Configuration Search Path
180 The configuration files to be read are found by searching a list of
181 configuration directories for appropriately named files. In each such
182 directory, the library will look for files named
183 snmp.conf,
184 snmp.local.conf, app.conf, app.local.conf, (where app is the appica‐
185 tion-specific filePrefix used to register configuration handlers). It
186 is not necessary for any or all of these files to be present in each
187 directory. Missing files will be silently skipped.
188 The idea behind the two different suffixes is that the first file can
189 be shared (via rdist or an NFS mount) across a large number of machines
190 and the second file can be used to configure local settings for one
191 particular machine.
192 The default list of directories to search is /etc/snmp, followed by
194 /usr/share/snmp, followed by /usr/lib(64)/snmp, followed by
195 $HOME/.snmp. This list can be changed by setting the environmental
196 variable SNMPCONFPATH to be a (colon separated) list of directories to
197 search.
198 init_snmp()
200 The normal mode of operation would be to register the application-spe‐
201 cific configuration handlers, and then invoke init_snmp(). This would
202 call the routines listed above to register the internal library config‐
203 uration handlers, process any configuration tokens registered with reg‐
204 ister_premib_handler(), read in the textual MIB files using init_mib(),
205 and finally parse the configuration file tokens registered with regis‐
206 ter_config_handler().
207 If the init_snmp() function is used, none of these functions need to be
209 explicitly called by the application.
210
212 The usageLine parameter passed to register_config_handler() and similar
213 calls, is used to display help information when the read_con‐
214 fig_print_usage() function is called. This function is used by all of
215 the applications when the -H flag is passed on the command line. It
216 prints a summary of all of the configuration file lines, and the asso‐
217 ciated files, that the configuration system understands. The usageLine
218 parameter should be a list of arguments expected after the token, and
219 not a lengthy description (which should go into a manual page instead).
220 The lead prefix will be prepended to each line that the function prints
221 to stderr, where it displays its output.
222 The init_snmp() function should be called before the read_con‐
224 fig_print_usage() function is called, so that the library can register
225 its configuration file directives as well for the read_con‐
226 fig_print_usage() function to display.
227 Error Handling Functions
229 The two functions config_pwarn() and config_perror() both take an error
230 string as an argument and print it to stderr along with the file and
231 line number that caused the error. A call to the second function will
232 also force read_configs() to eventually return with an error code indi‐
233 cating to it's calling function that it should abort the operation of
234 the application.
235
237 SNMPCONFPATH
238 A colon separated list of directories to search for configu‐
239 ration files in. Default:
240 /etc/snmp:/usr/share/snmp:/usr/lib(64)/snmp:$HOME/.snmp
241
243 mib_api(3), snmp_api(3)
2444.2 Berkeley Distribution 07 Mar 2002 CONFIG_API(3)