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


       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 Handler

       register_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.

              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 Files

       init_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.

              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  /etc/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
       rdisted across a large number of machines and  the  second
       file  can be used to configure local settings for one par­
       ticular 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:
                 /etc/snmp:/usr/lib/snmp:$HOME/.snmp


SEE ALSO

       mib_api(3), snmp_api(3)


Man(1) output converted with man2html