Net-SNMP READ_CONFIG(3)
NAME
register_config_handler, register_premib_handler
unregister_config_handler, register_mib_handlers,
read_configs, read_premib_configs, config_perror,
config_pwarn - read_config functions
SYNOPSIS
#include
struct config_line *
register_config_handler(const char *filePrefix,
const char *token, void (*parser)(const char *, char *), void (*releaser)(void), const char *usageLine);struct config_line *
register_premib_handler(const char *filePrefix,
const char *token, void (*parser)(const char *, char *), void (*releaser)(void), const char *usageLine);void unregister_config_handler(const char *filePrefix,
const char *token);struct config_line *
register_app_config_handler(const char *token,
void (*parser)(const char *, char *), void (*releaser)(void), const char *usageLine);struct config_line *
register_app_premib_handler(const char *token,
void (*parser)(const char *, char *), void (*releaser)(void), const char *usageLine);void unregister_app_config_handler(const char *token);
void read_config_print_usage(char *lead);
void read_configs(void);
void read_premib_configs(void);
void config_pwarn(const char *string);
void config_perror(const char *string);
DESCRIPTION
The functions are a fairly extensible system of parsing SunOS 5.10 Last change: 07 Mar 2002 1Net-SNMP READ_CONFIG(3)
various configuration files at the run time of an applica-
tion. The configuration file flow is broken into the fol-
lowing phases: 1. Registration of handlers.2. Reading of the configuration files for pre-MIB pars-
ing requirements. 3. Reading and parsing of the textual MIB files. 4. Reading of the configuration files for configuration directives.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 offiles. The read_configs() 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 FREEING HANDLERSIf the parameter releaser passed to register_config_handler
is non-NULL, then the function specified is called if and
when the configuration files are re-read. This function
should free any resources allocated by the token handler function and reset its notion of the configuration to its default. The token handler function will then be called again. No arguments are passed to the resource freeing handler. REGISTERING A HANDLERregister_config_handler()
The handler() function above could be registered forthe configuration file snmp.conf, with the token gener-
icToken and the help string (discussed later) "" "ARG1 [ARG2]" using the following call to the SunOS 5.10 Last change: 07 Mar 2002 2Net-SNMP READ_CONFIG(3)
register_config_handler() function:
register_config_handler("snmp", "genericToken",
handler, NULL, "ARG1 [ARG2]"); This would register the handler() function so that it will get called every time the first word of a line inthe snmp.conf configuration file(s) matches "genericTo-
ken" (see read_configs() below).
register_premib_handler()
The register_premib_handler() function works identi-
cally to the register_config_handler() 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.unregister_config_handler()
Removes the registered configuration handler for the filePrefix and token.register_app_config_handler()
register_app_premib_handler()
unregister_app_config_handler()
These functions are analagous toregister_config_handler(), register_premib_handler()
and unregister_config_handler() but don't require the
file type argument (which is filled in by the applica-
tion). 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 STRINGSThe usageLine parameter passed to register_config_handler()
and similar calls, is used to display help information whenthe read_config_print_usage() 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 associated 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. SunOS 5.10 Last change: 07 Mar 2002 3Net-SNMP READ_CONFIG(3)
The init_snmp() function should be called before the
read_config_print_usage() function is called, so that the
library can register its configuration file directives aswell for the read_config_print_usage() function to display.
READING CONFIGURATION FILESinit_snmp()
Once the relevant configuration token parsers have beenregistered, init_snmp() should be called. It will
parse the configuration file tokens registered withregister_premib_handler(), read in the textual MIB
files using init_mib(), and finally parse the confi-
guration file tokens registered withregister_config_handler().
If the init_snmp() function is used, none of the following
functions need to be called by the application:register_mib_handlers()
The SNMP library's routine to register its configura-
tion file handlers.read_premib_configs()
The routine that parses the configuration files for tokens registered to be dealt with before the textualMIBs are read in. See read_configs() below.
read_configs()
Reads all the configuration files it can find in the SNMPCONFPATH 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 defaultvalue, which will be /usr/etc/snmp, followed by /etc/net-
snmp/snmp, followed by /usr/lib/snmp, followed 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.ERROR HANDLING FUNCTIONS
The two functions config_pwarn() and config_perror() both
take an error string as an argument and print it to stderr SunOS 5.10 Last change: 07 Mar 2002 4Net-SNMP READ_CONFIG(3)
along with the file and line number that caused the error.A call to the second function will also force read_configs()
to eventually return with an error code indicating 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 configuration files in. Default:/usr/etc/snmp:/etc/net-
snmp/snmp:/usr/lib/snmp:$HOME/.snmp
SEE ALSO
mib_api(3), snmp_api(3)
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:_______________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|____________________|__________________________________|_
| Availability | system/management/snmp/net-snmp|
|____________________|__________________________________|_
| Interface Stability| Volatile ||____________________|_________________________________|
NOTESSource for net-snmp is available on http://opensolaris.org.
SunOS 5.10 Last change: 07 Mar 2002 5