Manual Pages for UNIX Operating System command usage for man config_perror

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                    1






Net-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 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 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 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 HANDLER
     register_config_handler()
          The handler() function above could  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



SunOS 5.10          Last change: 07 Mar 2002                    2






Net-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 in
          the 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       to
          register_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 STRINGS
     The usageLine parameter passed to  register_config_handler()
     and  similar calls, is used to display help information when
     the  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                    3






Net-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  as
     well for the read_config_print_usage() function to display.

READING CONFIGURATION FILES
     init_snmp()
          Once the relevant configuration token parsers have been
          registered,  init_snmp()  should  be  called.   It will
          parse the configuration  file  tokens  registered  with
          register_premib_handler(),  read  in  the  textual  MIB
          files using init_mib(), and finally  parse  the  confi-
          guration      file      tokens      registered     with
          register_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 textual
          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/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                    4






Net-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:

     box; cbp-1 | cbp-1 l | l .  ATTRIBUTE TYPE ATTRIBUTE VALUE =
     Availability   system/management/snmp/net-snmp  =  Interface
     Stability Volatile

NOTES
     Source for net-snmp is available on http://opensolaris.org.

ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:

     _______________________________________________________
    |   ATTRIBUTE TYPE   |          ATTRIBUTE VALUE        |
    |____________________|__________________________________|_
    | Availability       |  system/management/snmp/net-snmp|
    |____________________|__________________________________|_
    | Interface Stability|  Volatile                       |
    |____________________|_________________________________|

NOTES
     Source for net-snmp is available on http://opensolaris.org.














SunOS 5.10          Last change: 07 Mar 2002                    5