read_config.3.def
上传用户:wxp200602
上传日期:2007-10-30
资源大小:4028k
文件大小:9k
- .TH READ_CONFIG 3 "07 Mar 2002" "" "Net-SNMP"
- .UC 5
- .SH 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
- .SH SYNOPSIS
- .B #include <net-snmp/config_api.h>
- .PP
- .B struct config_line *
- .br
- .BI " register_config_handler(const char *" filePrefix ",
- .br
- .BI " const char *" token ,
- .br
- .BI " void (*" parser ")(const char *, char *),"
- .br
- .BI " void (*" releaser ")(void),"
- .br
- .BI " const char *"usageLine ");"
- .PP
- .B struct config_line *
- .br
- .BI " register_premib_handler(const char *" filePrefix ",
- .br
- .BI " const char *" token ,
- .br
- .BI " void (*" parser ")(const char *, char *),"
- .br
- .BI " void (*" releaser ")(void),"
- .br
- .BI " const char *" usageLine ");"
- .PP
- .BI "void unregister_config_handler(const char *" filePrefix ","
- .br
- .BI " const char *" token ");"
- .PP
- .B struct config_line *
- .br
- .BI " register_app_config_handler(const char *" token ,
- .br
- .BI " void (*" parser ")(const char *, char *),"
- .br
- .BI " void (*" releaser ")(void),"
- .br
- .BI " const char *"usageLine ");"
- .PP
- .B struct config_line *
- .br
- .BI " register_app_premib_handler(const char *" token ,
- .br
- .BI " void (*" parser ")(const char *, char *),"
- .br
- .BI " void (*" releaser ")(void),"
- .br
- .BI " const char *" usageLine ");"
- .PP
- .BI "void unregister_app_config_handler(const char *" token ");"
- .PP
- .BI "void read_config_print_usage(char *" lead ");"
- .PP
- .B "void read_configs(void);"
- .PP
- .B "void read_premib_configs(void);"
- .PP
- .BI "void config_pwarn(const char *" string ");"
- .br
- .BI "void config_perror(const char *" string ");"
- .SH DESCRIPTION
- The functions are a fairly extensible system of parsing various
- configuration files at the run time of an application. The
- configuration file flow is broken into the following phases:
- .RS 4
- .TP 4
- 1.
- Registration of handlers.
- .TP
- 2.
- Reading of the configuration files for pre-MIB parsing requirements.
- .TP
- 3.
- Reading and parsing of the textual MIB files.
- .TP
- 4.
- Reading of the configuration files for configuration directives.
- .TP
- 5.
- Optionally re-reading the configuration files at a future date.
- .RE
- .PP
- The idea is that the calling application is able to register
- .I handlers
- for certain
- .I tokens
- specified in certain types of
- .I files.
- The
- .B 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.
- .SH TOKEN HANDLERS
- .PP
- Handler functions should have the following signature:
- .PP
- .RS
- .BI "void handler(const char *" token ", char *" line ");"
- .RE
- .PP
- 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.
- .SH RESOURCE FREEING HANDLERS
- .PP
- If the parameter
- .I releaser
- passed to
- .B 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.
- .SH REGISTERING A HANDLER
- .TP
- .B register_config_handler()
- The
- .B handler()
- function above could be registered for the configuration file
- .I snmp.conf,
- with the token
- .I genericToken
- and the help string (discussed later)
- .I """ARG1 [ARG2]"""
- using the following call to the
- .B register_config_handler()
- function:
- .PP
- .RS
- .RS
- register_config_handler("snmp", "genericToken", handler, NULL, "ARG1 [ARG2]");
- .RE
- .RE
- .IP
- This would register the
- .B handler()
- function so that it will get called every time the first word of a
- line in the
- .I snmp.conf
- configuration file(s) matches "genericToken" (see
- .B read_configs()
- below).
- .TP
- .B register_premib_handler()
- The
- .B register_premib_handler()
- function works identically to the
- .B 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.
- .TP
- .B unregister_config_handler()
- Removes the registered configuration handler for the
- .I filePrefix
- and
- .IR token .
- .TP
- .B register_app_config_handler()
- .TP
- .B register_app_premib_handler()
- .TP
- .B unregister_app_config_handler()
- These functions are analagous to
- .BR register_config_handler() ", " register_premib_handler() " and "
- .B unregister_config_handler()
- but don't require the file type argument (which is filled in by the
- application). 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
- .I snmpd.conf
- files).
- .SH HELP STRINGS
- .PP
- The
- .I usageLine
- parameter passed to
- .B register_config_handler()
- and similar calls, is used to display help information when the
- .B read_config_print_usage()
- function is called. This function is used by all of the applications
- when the
- .B -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
- .I 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
- .I lead
- prefix will be prepended to each line that the function prints to
- stderr, where it displays its output.
- .PP
- The
- .B init_snmp()
- function should be called before the
- .B read_config_print_usage()
- function is called, so that the library can register its configuration
- file directives as well for the
- .B read_config_print_usage()
- function to display.
- .SH READING CONFIGURATION FILES
- .TP
- .B init_snmp()
- Once the relevant configuration token parsers have been registered,
- .B init_snmp()
- should be called. It will parse the configuration file tokens
- registered with
- .B register_premib_handler(),
- read in the textual MIB files using
- .B init_mib(),
- and finally parse the configuration file tokens registered with
- .BR register_config_handler() .
- .PP
- If the
- .B init_snmp()
- function is used, none of the following functions need to be called by
- the application:
- .TP
- .B register_mib_handlers()
- The SNMP library's routine to register its configuration file
- handlers.
- .TP
- .B read_premib_configs()
- The routine that parses the configuration files for tokens registered
- to be dealt with before the textual MIBs are read in. See
- .B read_configs()
- below.
- .TP
- .B read_configs()
- Reads all the configuration files it can find in the
- .I 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.
- .SH CONFIGURATION FILES READ
- .PP
- The configuration files read are found by using the colon separated
- .I SNMPCONFPATH
- environment variable (or its default value, which will be
- SYSCONFDIR/snmp, followed by
- DATADIR/snmp, followed by LIBDIR/snmp, followed by $HOME/.snmp) and
- reading in the files found that match both the prefix registered and
- the two suffixes
- .I .conf
- and
- .I .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.
- .SH ERROR HANDLING FUNCTIONS
- .PP
- The two functions
- .B config_pwarn()
- and
- .B 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
- .B read_configs()
- to eventually return with an error code indicating to it's calling
- function that it should abort the operation of the application.
- .SH "ENVIRONMENT VARIABLES"
- .TP 10
- SNMPCONFPATH
- A colon separated list of directories to search for configuration
- files in.
- Default: SYSCONFDIR/snmp:DATADIR/snmp:LIBDIR/snmp:$HOME/.snmp
- .SH "SEE ALSO"
- .BR mib_api "(3), " snmp_api (3)
- ." Local Variables:
- ." mode: nroff
- ." End: