READCONFIG(3) Net-SNMP READCONFIG(3)

NAME
       registerconfighandler, registerpremibhandler unregisterconfighan-
       dler, registermibhandlers,  readconfigs,  readpremibconfigs,  con-
       figperror, configpwarn - readconfig functions

SYNOPSIS
       ##iinncclluuddee <>

       ssttrruucctt ccoonnffiigglliinnee **
         rreeggiisstteerrccoonnffiigghhaannddlleerr((ccoonnsstt cchhaarr **filePrefix,,
                            ccoonnsstt cchhaarr **token,,
                            vvooiidd ((**parser))((ccoonnsstt cchhaarr **,, cchhaarr **)),,
                            vvooiidd ((**releaser))((vvooiidd)),,
                            ccoonnsstt cchhaarr **usageLine));;

       ssttrruucctt ccoonnffiigglliinnee **
         rreeggiisstteerrpprreemmiibbhhaannddlleerr((ccoonnsstt cchhaarr **filePrefix,,
                            ccoonnsstt cchhaarr **token,,
                            vvooiidd ((**parser))((ccoonnsstt cchhaarr **,, cchhaarr **)),,
                            vvooiidd ((**releaser))((vvooiidd)),,
                            ccoonnsstt cchhaarr **usageLine));;

       vvooiidd uunnrreeggiisstteerrccoonnffiigghhaannddlleerr((ccoonnsstt cchhaarr **filePrefix,,
                            ccoonnsstt cchhaarr **token));;

       ssttrruucctt ccoonnffiigglliinnee **
         rreeggiisstteerraappppccoonnffiigghhaannddlleerr((ccoonnsstt cchhaarr **token,,
                            vvooiidd ((**parser))((ccoonnsstt cchhaarr **,, cchhaarr **)),,
                            vvooiidd ((**releaser))((vvooiidd)),,
                            ccoonnsstt cchhaarr **usageLine));;

       ssttrruucctt ccoonnffiigglliinnee **
         rreeggiisstteerraapppppprreemmiibbhhaannddlleerr((ccoonnsstt cchhaarr **token,,
                            vvooiidd ((**parser))((ccoonnsstt cchhaarr **,, cchhaarr **)),,
                            vvooiidd ((**releaser))((vvooiidd)),,
                            ccoonnsstt cchhaarr **usageLine));;

       vvooiidd uunnrreeggiisstteerraappppccoonnffiigghhaannddlleerr((ccoonnsstt cchhaarr **token));;

       vvooiidd rreeaaddccoonnffiiggpprriinnttuussaaggee((cchhaarr **lead));;

       vvooiidd rreeaaddccoonnffiiggss((vvooiidd));;

       vvooiidd rreeaaddpprreemmiibbccoonnffiiggss((vvooiidd));;

       vvooiidd ccoonnffiiggppwwaarrnn((ccoonnsstt cchhaarr **string));;
       vvooiidd ccoonnffiiggppeerrrroorr((ccoonnsstt cchhaarr **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 rreeaaddccoonn-
       ffiiggss(()) 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.

TTOOKKEENN HHAANNDDLLEERRSS
       Handler functions should have the following signature:

              vvooiidd hhaannddlleerr((ccoonnsstt cchhaarr **token,, cchhaarr **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.

RREESSOOUURRCCEE FFRREEEEIINNGG HHAANNDDLLEERRSS
       If the parameter releaser passed  to  rreeggiisstteerrccoonnffiigghhaannddlleerr  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.

RREEGGIISSTTEERRIINNGG AA HHAANNDDLLEERR
       rreeggiisstteerrccoonnffiigghhaannddlleerr(())
              The hhaannddlleerr(()) 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 rreeggiisstteerrccoonnffiigghhaannddlleerr(()) function:

                     registerconfighandler("snmp", "genericToken",  handler,
                     NULL, "ARG1 [ARG2]");

              This  would  register the hhaannddlleerr(()) 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 rreeaaddccoonnffiiggss(())
              below).

       rreeggiisstteerrpprreemmiibbhhaannddlleerr(())
              The rreeggiisstteerrpprreemmiibbhhaannddlleerr(()) function works identically to  the
              rreeggiisstteerrccoonnffiigghhaannddlleerr(())  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.

       uunnrreeggiisstteerrccoonnffiigghhaannddlleerr(())
              Removes  the registered configuration handler for the filePrefix
              and token.


       rreeggiisstteerraappppccoonnffiigghhaannddlleerr(())

       rreeggiisstteerraapppppprreemmiibbhhaannddlleerr(())

       uunnrreeggiisstteerraappppccoonnffiigghhaannddlleerr(())
              These functions are analagous to rreeggiisstteerrccoonnffiigghhaannddlleerr(()), rreegg-
              iisstteerrpprreemmiibbhhaannddlleerr(()) and uunnrreeggiisstteerrccoonnffiigghhaannddlleerr(()) 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).

HHEELLPP SSTTRRIINNGGSS
       The usageLine parameter passed to rreeggiisstteerrccoonnffiigghhaannddlleerr(()) and similar
       calls,   is  used  to  display  help  information  when  the  rreeaaddccoonn-
       ffiiggpprriinnttuussaaggee(()) function is called.  This function is used by all  of
       the  applications  when  the -HH 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   iinniittssnnmmpp(())  function  should  be  called  before  the  rreeaaddccoonn-
       ffiiggpprriinnttuussaaggee(()) function is called, so that the library can  register
       its   configuration   file   directives   as  well  for  the  rreeaaddccoonn-
       ffiiggpprriinnttuussaaggee(()) function to display.

READING CONFIGURATION FILES       iinniittssnnmmpp(())
              Once the relevant configuration token parsers have  been  regis-
              tered, iinniittssnnmmpp(()) should be called.  It will parse the configu-
              ration file tokens  registered  with  rreeggiisstteerrpprreemmiibbhhaannddlleerr(()),,
              read  in  the  textual  MIB  files using iinniittmmiibb(()),, and finally
              parse the  configuration  file  tokens  registered  with  rreeggiiss-
              tteerrccoonnffiigghhaannddlleerr(()).

       If  the  iinniittssnnmmpp(())  function is used, none of the following functions
       need to be called by the application:

       rreeggiisstteerrmmiibbhhaannddlleerrss(())
              The SNMP library's routine to register  its  configuration  file
              handlers.

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

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

EERRRROORR HHAANNDDLLIINNGG FFUUNNCCTTIIOONNSS
       The two functions ccoonnffiiggppwwaarrnn(()) and ccoonnffiiggppeerrrroorr(()) 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 rreeaaddccoonnffiiggss(()) 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
       mmiibbaappii(3), ssnnmmppaappii(3)



4.2 Berkeley Distribution         07 Mar 2002                   READCONFIG(3)