1READ_CONFIG(3)                     Net-SNMP                     READ_CONFIG(3)
2
3
4

NAME

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

SYNOPSIS

11       #include <net-snmp/config_api.h>
12
13       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
20       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
27       void unregister_config_handler(const char *filePrefix,
28                            const char *token);
29
30       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
36       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
42       void unregister_app_config_handler(const char *token);
43
44       void read_config_print_usage(char *lead);
45
46       void read_configs(void);
47
48       void read_premib_configs(void);
49
50       void config_pwarn(const char *string);
51       void config_perror(const char *string);
52
53

DESCRIPTION

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
59           1.  Registration of handlers.
60
61           2.  Reading of the configuration files for pre-MIB parsing require‐
62               ments.
63
64           3.  Reading and parsing of the textual MIB files.
65
66           4.  Reading of the configuration  files  for  configuration  direc‐
67               tives.
68
69           5.  Optionally re-reading the configuration files at a future date.
70
71       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

TOKEN HANDLERS

78       Handler functions should have the following signature:
79
80              void handler(const char *token, char *line);
81
82       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

RESOURCE FREEING HANDLERS

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

REGISTERING A HANDLER

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
103                     register_config_handler("snmp",  "genericToken", handler,
104                     NULL, "ARG1 [ARG2]");
105
106              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
111       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
119       unregister_config_handler()
120              Removes the registered configuration handler for the  filePrefix
121              and token.
122
123
124       register_app_config_handler()
125
126       register_app_premib_handler()
127
128       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

HELP STRINGS

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
149       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

READING CONFIGURATION FILES

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
163       If the init_snmp() function is used, none of  the  following  functions
164       need to be called by the application:
165
166       register_mib_handlers()
167              The  SNMP  library's  routine to register its configuration file
168              handlers.
169
170       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
175       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

CONFIGURATION FILES READ

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

ERROR HANDLING FUNCTIONS

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

ENVIRONMENT VARIABLES

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

SEE ALSO

209       mib_api(3), snmp_api(3)
210
211
212
2134.2 Berkeley Distribution         07 Mar 2002                   READ_CONFIG(3)
Impressum