1READ_CONFIG(3) Net-SNMP READ_CONFIG(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 - read_config 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 unregister_config_handler(const char *filePrefix,
28 const char *token);
29 struct config_line *
31 register_app_config_handler(const char *token,
32 void (*parser)(const char *, char *),
33 void (*releaser)(void),
34 const char *usageLine);
35 struct config_line *
37 register_app_premib_handler(const char *token,
38 void (*parser)(const char *, char *),
39 void (*releaser)(void),
40 const char *usageLine);
41 void unregister_app_config_handler(const char *token);
43 void read_config_print_usage(char *lead);
45 void read_configs(void);
47 void read_premib_configs(void);
49 void config_pwarn(const char *string);
51 void config_perror(const char *string);
52
55 The functions are a fairly extensible system of parsing various config‐
56 uration files at the run time of an application. The configuration
57 file flow is broken into the following phases:
58 1. Registration of handlers.
60 2. Reading of the configuration files for pre-MIB parsing require‐
62 ments.
63 3. Reading and parsing of the textual MIB files.
65 4. Reading of the configuration files for configuration direc‐
67 tives.
68 5. Optionally re-reading the configuration files at a future date.
70 The idea is that the calling application is able to register handlers
72 for certain tokens specified in certain types of files. The read_con‐
73 figs() function can then be called to look for all the files that it
74 has registrations for, find the first word on each line, and pass the
75 remainder to the appropriately registered handler.
76
78 Handler functions should have the following signature:
79 void handler(const char *token, char *line);
81 The function will be called with two arguments, the first being the
83 token that triggered the call to this function (which would be one of
84 the tokens that the function had been registered for), and the second
85 being the remainder of the configuration file line beyond the white
86 space following the token.
87
89 If the parameter releaser passed to register_config_handler is non-
90 NULL, then the function specified is called if and when the configura‐
91 tion files are re-read. This function should free any resources allo‐
92 cated by the token handler function and reset its notion of the config‐
93 uration to its default. The token handler function will then be called
94 again. No arguments are passed to the resource freeing handler.
95
97 register_config_handler()
98 The handler() function above could be registered for the config‐
99 uration file snmp.conf, with the token genericToken and the help
100 string (discussed later) "ARG1 [ARG2]" using the following call
101 to the register_config_handler() function:
102 register_config_handler("snmp", "genericToken", handler,
104 NULL, "ARG1 [ARG2]");
105 This would register the handler() function so that it will get
107 called every time the first word of a line in the snmp.conf con‐
108 figuration file(s) matches "genericToken" (see read_configs()
109 below).
110 register_premib_handler()
112 The register_premib_handler() function works identically to the
113 register_config_handler() function but is intended for config
114 file tokens that need to be read in before the textual MIBs are
115 read in, probably because they will be used to configure the MIB
116 parser. It is rarely the case that anything but the SNMP
117 library itself should need to use this function.
118 unregister_config_handler()
120 Removes the registered configuration handler for the filePrefix
121 and token.
122 register_app_config_handler()
125 register_app_premib_handler()
127 unregister_app_config_handler()
129 These functions are analagous to register_config_handler(), reg‐
130 ister_premib_handler() and unregister_config_handler() but don't
131 require the file type argument (which is filled in by the appli‐
132 cation). It is intended that MIB modules written for the agent
133 use these functions to allow the agent to have more control over
134 which configuration files are read (typically the snmpd.conf
135 files).
136
138 The usageLine parameter passed to register_config_handler() and similar
139 calls, is used to display help information when the read_con‐
140 fig_print_usage() function is called. This function is used by all of
141 the applications when the -H flag is passed on the command line. It
142 prints a summary of all of the configuration file lines, and the asso‐
143 ciated files, that the configuration system understands. The usageLine
144 parameter should be a list of arguments expected after the token, and
145 not a lengthy description (which should go into a manual page instead).
146 The lead prefix will be prepended to each line that the function prints
147 to stderr, where it displays its output.
148 The init_snmp() function should be called before the read_con‐
150 fig_print_usage() function is called, so that the library can register
151 its configuration file directives as well for the read_con‐
152 fig_print_usage() function to display.
153
155 init_snmp()
156 Once the relevant configuration token parsers have been regis‐
157 tered, init_snmp() should be called. It will parse the configu‐
158 ration file tokens registered with register_premib_handler(),
159 read in the textual MIB files using init_mib(), and finally
160 parse the configuration file tokens registered with regis‐
161 ter_config_handler().
162 If the init_snmp() function is used, none of the following functions
164 need to be called by the application:
165 register_mib_handlers()
167 The SNMP library's routine to register its configuration file
168 handlers.
169 read_premib_configs()
171 The routine that parses the configuration files for tokens reg‐
172 istered to be dealt with before the textual MIBs are read in.
173 See read_configs() below.
174 read_configs()
176 Reads all the configuration files it can find in the SNMPCONF‐
177 PATH environment variable (or its default value) for tokens and
178 appropriately calls the handlers registered to it, or prints a
179 "Unknown token" warning message. It looks for any file that it
180 has previously received a registration request for.
181
183 The configuration files read are found by using the colon separated
184 SNMPCONFPATH environment variable (or its default value, which will be
185 /etc/snmp, followed by /usr/share/snmp, followed by /usr/lib/snmp (or
186 /usr/lib64/snmp), followed by $HOME/.snmp) and reading in the files
187 found that match both the prefix registered and the two suffixes .conf
188 and .local.conf. The idea behind the two different suffixes is that
189 the first file can be shared (via rdist or an NFS mount) across a large
190 number of machines and the second file can be used to configure local
191 settings for one particular machine. They do not need to be present,
192 and will only be read if found.
193
195 The two functions config_pwarn() and config_perror() both take an error
196 string as an argument and print it to stderr along with the file and
197 line number that caused the error. A call to the second function will
198 also force read_configs() to eventually return with an error code indi‐
199 cating to it's calling function that it should abort the operation of
200 the application.
201
203 SNMPCONFPATH
204 A colon separated list of directories to search for configu‐
205 ration files in. Default:
206 /etc/snmp:/usr/share/snmp:/usr/lib(64)/snmp:$HOME/.snmp
207
209 mib_api(3), snmp_api(3)
2104.2 Berkeley Distribution 07 Mar 2002 READ_CONFIG(3)