READ_CONFIG(3)READ_CONFIG(3)NAME
register_config_handler, register_premib_handler unregis-
ter_config_handler, register_mib_handlers, read_configs,
read_premib_configs, config_perror, config_pwarn -
read_config functions
SYNOPSIS
#include <read_config.h>
struct config_line *
register_config_handler(char *filePrefix, char *token,
void (*parser)(char *, char *) handler,
void (*releaser) (void) freefunc,
char *usageLine)
struct config_line *
register_premib_handler(char *filePrefix, char *token,
void (*parser)(char *, char *) handler,
void (*releaser) (void) freefunc,
char *usageLine)
struct config_line *
snmpd_register_config_handler(char *token,
void (*parser)(char *, char *) handler,
void (*releaser) (void) freefunc,
char *usageLine)
void unregister_config_handler(char *filePrefix,
char *token)
void read_config_print_usage(char *lead)
void read_configs(void)
void read_premib_configs(void)DESCRIPTION
The functions are a fairly extensible system of parsing
various configuration files at the run time of an applica-
tion. The configuration file flow is broken into the fol-
lowing phases:
registration of handlers.
reading of the configuration files for pre-mib
parsing requirements.
reading of the textual mib files.
reading of the configuration files for configura-
tion directives.
optionally re-reading of the configuration files at
02 Mar 1999 1
READ_CONFIG(3)READ_CONFIG(3)
a future date.
The idea is that the calling application is able to regis-
ter handlers for certain tokens specified in certain types
of files. 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 be of the following type:
void handler(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 fol-
lowing the token.
Resource Freeing Handlers
If the read_config configuration system is called a second
time to re-read the configuration files, the optional sec-
ond handler freefunc will be called, if registered as non-
NULL, to free any resources and reset its notions to
defaults before the config handlers are called again. It
is not called with any arguments.
Registering A Handlerregister_config_handler()
The handler above could then be registered for the
configuration file snmp.conf, with the token gener-
icToken and the help string (discussed later) ARG1
ARG2 using the following call to the register_con-
fig_handler() function:
register_config_handler("snmp", "genericTo-
ken", handler, NULL, "ARG1 ARG2");
This would register the handler() function so that
it will get called every time the first word in the
snmp.conf configuration file(s) matches "genericTo-
ken" (see read_configs() below).
register_premib_handler()
The register_premib_handler() function works iden-
tically 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.
02 Mar 1999 2
READ_CONFIG(3)READ_CONFIG(3)snmpd_register_config_handler()
This function performs exactly the same job as the
register_config_handler() function, but doesn't
require the file type argument (which is filled in
by the snmpd agent). It is intended that mib mod-
ules written for the agent use this function
instead of the register_config_handler() function
directly to allow the agent to have more control
over which files the mib modules will read (which
should be the snmpd.conf files).
unregister_config_handler()
Removes the registered configuration handler for
the filePrefix and token
Help Strings
The usageLine token passed to the register_config_han-
dler(), and similar calls, is used to display help infor-
mation when the read_config_print_usage() function is
called. This function is used by all of the applications
when the -H flag is passed to the command line. It prints
a summary of all of the configuration file lines, and the
associated files, that the configuration system under-
stands. The usageLine parameter should be a list of argu-
ments expected after the token, and not a lengthy descrip-
tion (which should go into a manual page instead). The
lead prefix will be prepended to each line that the func-
tion prints to stderr, where it displays its output.
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 as
well for the read_config_print_usage() function to dis-
play.
Reading Configuration Filesinit_snmp()
The init_snmp() function call should be called
after registrations to appropriately register
parser configuration tokens, parse the configura-
tion file tokens registered with register_pre-
mib_handler(), read in the textual mib files using
init_mib(), and finally parse the configuration
file tokens registered with register_config_han-
dler().
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 it's config-
uration file handlers.
02 Mar 1999 3
READ_CONFIG(3)READ_CONFIG(3)read_premib_configs()
The routine that parses the configuration files for
tokens registered to be dealt with before the tex-
tual mibs 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
default value, which will be /usr/contrib/share/snmp, fol-
lowed by /usr/contrib/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 rdisted 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
along with the file and line number that caused the error.
A call to the second function will also force read_con-
figs() to eventually return with an error code indicating
to it's calling function that it should abort the opera-
tion of the application.
ENVIRONMENT VARIABLES
SNMPCONFPATH
A colon separated list of directories to search
for configuration files in. Default: /usr/con-
trib/share/snmp:/usr/con-
trib/lib/snmp:$HOME/.snmp
SEE ALSOmib_api(3), snmp_api(3)
02 Mar 1999 4
