READCONFIG(3) Net-SNMP READCONFIG(3)
NAME
registerconfighandler, registerpremibhandler unregisterconfighan-
dler, registermibhandlers, readconfigs, readpremibconfigs, con-
figperror, configpwarn - readconfig functions
SYNOPSIS
##include <>
struct configline **
registerconfighandler(const char **filePrefix,,
const char **token,,
void (**parser)(const char **,, char **),,
void (**releaser)(void),,
const char **usageLine);;
struct configline **
registerpremibhandler(const char **filePrefix,,
const char **token,,
void (**parser)(const char **,, char **),,
void (**releaser)(void),,
const char **usageLine);;
void unregisterconfighandler(const char **filePrefix,,
const char **token);;
struct configline **
registerappconfighandler(const char **token,,
void (**parser)(const char **,, char **),,
void (**releaser)(void),,
const char **usageLine);;
struct configline **
registerapppremibhandler(const char **token,,
void (**parser)(const char **,, char **),,
void (**releaser)(void),,
const char **usageLine);;
void unregisterappconfighandler(const char **token);;
void readconfigprintusage(char **lead);;
void readconfigs(void);;
void readpremibconfigs(void);;
void configpwarn(const char **string);;
void configperror(const char **string);;
DESCRIPTION
The functions are a fairly extensible system of parsing various config-
uration files at the run time of an application. The configuration
file flow is broken into the following phases:
1. Registration of handlers.
2. Reading of the configuration files for pre-MIB parsing require-
ments.
3. Reading and parsing of the textual MIB files.
4. Reading of the configuration files for configuration direc-
tives.
5. Optionally re-reading the configuration files at a future date.
The idea is that the calling application is able to register handlers
for certain tokens specified in certain types of files. The readcon-
figs() function can then be called to look for all the files that it
has registrations for, find the first word on each line, and pass the
remainder to the appropriately registered handler.
TOKEN HANDLERS
Handler functions should have the following signature:
void handler(const char **token,, char **line);;
The function will be called with two arguments, the first being the
token that triggered the call to this function (which would be one of
the tokens that the function had been registered for), and the second
being the remainder of the configuration file line beyond the white
space following the token.
RESOURCE FREING HANDLERS
If the parameter releaser passed to registerconfighandler is non-
NUL, then the function specified is called if and when the configura-
tion files are re-read. This function should free any resources allo-
cated by the token handler function and reset its notion of the config-
uration to its default. The token handler function will then be called
again. No arguments are passed to the resource freeing handler.
REGISTERING A HANDLER
registerconfighandler()
The handler() function above could be registered for the config-
uration file snmp.conf, with the token genericToken and the help
string (discussed later) "ARG1 [ARG2]" using the following call
to the registerconfighandler() function:
registerconfighandler("snmp", "genericToken", handler,
NUL, "ARG1 [ARG2]");
This would register the handler() function so that it will get
called every time the first word of a line in the snmp.conf con-
figuration file(s) matches "genericToken" (see readconfigs()
below).
registerpremibhandler()
The registerpremibhandler() function works identically to the
registerconfighandler() function but is intended for config
file tokens that need to be read in before the textual MIBs are
read in, probably because they will be used to configure the MIB
parser. It is rarely the case that anything but the SNMP
library itself should need to use this function.
unregisterconfighandler()
Removes the registered configuration handler for the filePrefix
and token.
registerappconfighandler()
registerapppremibhandler()
unregisterappconfighandler()
These functions are analagous to registerconfighandler(), reg-
isterpremibhandler() and unregisterconfighandler() but don't
require the file type argument (which is filled in by the appli-
cation). It is intended that MIB modules written for the agent
use these functions to allow the agent to have more control over
which configuration files are read (typically the snmpd.conf
files).
HELP STRINGS
The usageLine parameter passed to registerconfighandler() and similar
calls, is used to display help information when the readcon-
figprintusage() function is called. This function is used by all of
the applications when the -H flag is passed on the command line. It
prints a summary of all of the configuration file lines, and the asso-
ciated files, that the configuration system understands. The usageLine
parameter should be a list of arguments expected after the token, and
not a lengthy description (which should go into a manual page instead).
The lead prefix will be prepended to each line that the function prints
to stderr, where it displays its output.
The initsnmp() function should be called before the readcon-
figprintusage() function is called, so that the library can register
its configuration file directives as well for the readcon-
figprintusage() function to display.
READING CONFIGURATION FILES
initsnmp()
Once the relevant configuration token parsers have been regis-
tered, initsnmp() should be called. It will parse the configu-
ration file tokens registered with registerpremibhandler(),,
read in the textual MIB files using initmib(),, and finally
parse the configuration file tokens registered with regis-
terconfighandler().
If the initsnmp() function is used, none of the following functions
need to be called by the application:
registermibhandlers()
The SNMP library's routine to register its configuration file
handlers.
readpremibconfigs()
The routine that parses the configuration files for tokens reg-
istered to be dealt with before the textual MIBs are read in.
See readconfigs() below.
readconfigs()
Reads all the configuration files it can find in the SNMPCONF-
PATH environment variable (or its default value) for tokens and
appropriately calls the handlers registered to it, or prints a
"Unknown token" warning message. It looks for any file that it
has previously received a registration request for.
CONFIGURATION FILES READ
The configuration files read are found by using the colon separated
SNMPCONFPATH environment variable (or its default value, which will be
/etc/snmp, followed by /usr/share/snmp, followed by /usr/lib/snmp, fol-
lowed by $HOME/.snmp) and reading in the files found that match both
the prefix registered and the two suffixes .conf and .local.conf. The
idea behind the two different suffixes is that the first file can be
shared (via rdist or an NFS mount) across a large number of machines
and the second file can be used to configure local settings for one
particular machine. They do not need to be present, and will only be
read if found.
EROR HANDLING FUNCTIONS
The two functions configpwarn() and configperror() both take an error
string as an argument and print it to stderr along with the file and
line number that caused the error. A call to the second function will
also force readconfigs() to eventually return with an error code indi-
cating to it's calling function that it should abort the operation of
the application.
ENVIRONMENT VARIABLES
SNMPCONFPATH
A colon separated list of directories to search for configu-
ration files in. Default:
/etc/snmp:/usr/share/snmp:/usr/lib/snmp:$HOME/.snmp
SEE ALSO
mibapi(3), snmpapi(3)
4.2 Berkeley Distribution 07 Mar 2002 READCONFIG(3)
|
