manpagez: man pages & more
man config_perror(3)
Home | html | info | man
read_config(3)                     Net-SNMP                     read_config(3)




NAME

       register_config_handler, register_premib_handler unregister_config_han-
       dler, register_mib_handlers,  read_configs,  read_premib_configs,  con-
       fig_perror, config_pwarn - read_config functions


SYNOPSIS

       #include <net-snmp/config_api.h>

       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 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 read_con-
       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 FREEING HANDLERS

       If the parameter releaser passed  to  register_config_handler  is  non-
       NULL,  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

       register_config_handler()
              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 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 in the snmp.conf con-
              figuration  file(s)  matches  "genericToken" (see read_configs()
              below).

       register_premib_handler()
              The register_premib_handler() function works identically 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 to register_config_handler(), reg-
              ister_premib_handler() and unregister_config_handler() 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 register_config_handler() and similar
       calls,   is  used  to  display  help  information  when  the  read_con-
       fig_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  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   init_snmp()  function  should  be  called  before  the  read_con-
       fig_print_usage() function is called, so that the library can  register
       its   configuration   file   directives   as  well  for  the  read_con-
       fig_print_usage() function to display.


READING CONFIGURATION FILES

       init_snmp()
              Once the relevant configuration token parsers have  been  regis-
              tered, init_snmp() should be called.  It will parse the configu-
              ration file tokens  registered  with  register_premib_handler(),
              read  in  the  textual  MIB  files using init_mib(), and finally
              parse the  configuration  file  tokens  registered  with  regis-
              ter_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  configuration  file
              handlers.

       read_premib_configs()
              The  routine that parses the configuration files for tokens reg-
              istered to be dealt with before the textual MIBs  are  read  in.
              See read_configs() below.

       read_configs()
              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.


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_configs() 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

       mib_api(3), snmp_api(3)



4.2 Berkeley Distribution         07 Mar 2002                   read_config(3)

Mac OS X 10.6 - Generated Thu Sep 17 20:22:28 CDT 2009
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.