NAME

       smiInit,  smiExit,  smiSetErrorLevel, smiGetFlags, smiSetFlags, smiLoadModule, smiGetPath,
       smiSetPath, smiReadConfig - SMI library configuration routines

SYNOPSIS

       #include <smi.h>

       int smiInit(const char *tag);

       int smiExit();

       void smiSetErrorLevel(int level);

       int smiGetFlags();

       void smiSetFlags(int userflags);

       char *smiLoadModule(char *module);

       int smiIsLoaded(char *module);

       char *smiGetPath();

       int smiSetPath(char *path);

       int smiSetSeverity(char *pattern, int severity);

       int smiReadConfig(char *filename, const char *tag);

       void smiSetErrorHandler(SmiErrorHandler *smiErrorHandler);

       typedef void (SmiErrorHandler) (char *path, int line,
                           int severity, char *msg, char *tag);

DESCRIPTION

       These functions provide some initialization and adjustment operations for the SMI library.

       The smiInit() function should be the first SMI  function  called  in  an  application.  It
       initializes its internal structures. If tag is not NULL, the global configuration file and
       (on UNIX systems) a user configuration file are read implicitly, if existent.  All  global
       statements  and  those  statements  with  a  tag (a ``tag: '' prefix) that matches the tag
       argument are executed.  (see also CONFIGURATION FILES below).  smiInit() returns  zero  on
       success, or otherwise a negative value.

       The  smiInit()  function  can  also  be used to support multiple sets of MIB data. In this
       case, the tag argument may be prepended by a colon and a name to  differentiate  the  data
       sets.  Any library function call subsequent to an smiInit("tag:dataset") call is using the
       specified data set.

       The smiExit() function should be called when the  application  no  longer  needs  any  SMI
       information to release any allocated SMI resources.

       The  smiSetErrorLevel()  function  sets the pedantic level (0-9) of the SMI parsers of the
       SMI library, currently SMIv1/v2 and SMIng.  The higher the level, the louder it complains.
       Values  up  to  3  should  be  regarded  as  errors,  higher level could be interpreted as
       warnings.  But note that this classification is some kind of personal taste.  The  default
       level is 0, since usually only MIB checkers want to tune a higher level.

       The  smiGetFlags()  and  smiSetFlags()  functions  allow  to  fetch,  modify, and set some
       userflags that control the SMI library's behaviour.  If SMI_FLAG_ERRORS  is  not  set,  no
       error  messages  are  printed at all to keep the SMI library totally quiet, which might be
       mandatory for some applications. If SMI_FLAG_STATS is set, the library prints some  module
       statistics.  If  SMI_FLAG_RECURSIVE  is  set,  the  library also complains about errors in
       modules that are read due to import statements. If SMI_FLAG_NODESCR is set, no description
       and references strings are stored in memory. This may save a huge amount of memory in case
       of applications that do not need this information.

       The smiSetSeverity() function allows to set the severity  of  all  error  that  have  name
       prefixed by pattern to the value severity.

       The  smiLoadModule()  function  specifies  an  additional  MIB module that the application
       claims to know or an additional file path to read.  Only after  a  module  is  made  known
       through this function, iterating retrieval functions and retrieval functions without fully
       qualified identifiers will return results from this module.  smiLoadModule()  returns  the
       name of the loaded module, of NULL if it could not be loaded.

       The  smiIsLoaded() function returns a positive value if the module named module is already
       loaded, or zero otherwise.

       The smiGetPath() and smiSetPath() functions allow to fetch, modify, and set the path  that
       is  used to search MIB modules.  smiGetPath() returns a copy of the current search path in
       the form "DIR1:DIR2:...", or NULL if no path is set.  The  application  should  free  this
       string if it is no longer needed. smiSetPath() sets the search path to path.

       The smiReadConfig() function reads the configuration file filename.  All global statements
       in the configuration file and those statements with  a  tag  (a  ``tag:  ''  prefix)  that
       matches the tag argument, if present, are executed.

       The  smiSetErrorHandler() function allows to set a callback function that is called by the
       MIB parsers deviating from the builtin default error handler, that prints  error  messages
       to  stderr.  The  error  handler has to comply with the SmiErrorHandler function type. The
       path, line, severity, msg, and tag arguements carry the module's pathname, the line number
       within  the  module,  the error severity level, a textual error message, and a short error
       name of the error being reported.

MODULE LOCATIONS

       The SMI library may retrieve MIB modules from different  kinds  of  resources.  Currently,
       SMIv1/v2  and  SMIng module files are supported.  If in an smiLoadModule() function call a
       module is specified by a path name (identified by containing at least  one  dot  or  slash
       character),  this  is  assumed  to  be  the  exact file to read. Otherwise, if a module is
       identified by its plain module name, the correspondant file (either SMIv1/2 or  SMIng)  is
       searched      along      a      path.      This      path      is     initialized     with
       /usr/share/mibs/ietf:/usr/share/mibs/iana:/usr/share/mibs/irtf:/usr/share/mibs/site:/usr/share/mibs/tubs:/usr/share/pibs/ietf:/usr/share/pibs/site:/usr/share/pibs/tubs.
       Afterwards  the  optional  global  and  user  configuration  files  are  parsed for `path'
       commands, and finally the optional SMIPATH environment variable is evaluated.  The  `path'
       command argument and the environment variable either start with a path separator character
       (`:' on UNIX-like systems, `;' on MS-Windows systems) to append to the path, or end with a
       path separator character to prepend to the path, or otherwise completely replace the path.
       The path can also be controlled  by  the  smiGetPath()  and  smiSetPath()  functions  (see
       above).

       When files are searched by a given module name, they might have no extension or one of the
       extensions `.my', `.smiv2', `.sming', `.mib', or `.txt'. However, the MIB module  language
       is identified by the file's content, not by its file name extension.

CONFIGURATION FILES

       SMI  library  configuration  files read at initialization and on demand by smiReadConfig()
       have a simple line oriented syntax. Empty lines and those starting with `#'  are  ignored.
       Other  lines  start with an optional tag (prepended by a colon), followed by a command and
       options dependent on the command. Tags are used to limit the scope of a command  to  those
       applications that are using this tag.

       The  load  command  is  used  to  preload a given MIB module. If multiple modules shall be
       preloaded, multiple load commands must be used.

       The path command allows to prepend or append components to the MIB module search  path  or
       to modify it completely (see also MODULE LOCATIONS above).

       The  cache  command  allows to add an additional directory for MIB module lookup as a last
       resort. The first argument specifies the directory and the rest of the line starting  from
       the  second  argument  specifies  the caching method, which is invoked with the MIB module
       name appended if the module is found neither in one of the regular directories nor in  the
       cache directory beforehand.

       The level command sets the error level.

       The  hide  command  allows  to  tune  the list of errors that are reported.  It raises all
       errors with names prefixed by the given pattern to severity level 9. [Currently, there  is
       no way to list the error names. RTFS: error.c.]

       Example configuration:

         #
         # $HOME/.smirc
         #

         # add a private directory
         path :/usr/home/strauss/lib/mibs

         # don't show any errors by default
         level 0

         # preload some basic modules
         load SNMPv2-SMI
         load SNMPv2-TC
         load SNMPv2-CONF

         # want to make smilint shout
         smilint: level 8

         # but please don't claim about
         # any names longer than 32 chars
         smilint: hide namelength-32

         tcpdump: load DISMAN-SCRIPT-MIB

         smiquery: load IF-MIB
         smiquery: load DISMAN-SCRIPT-MIB

FILES

       /etc/smi.conf    global configuration file
       $HOME/.smirc               user configuration file
       ${prefix}/include/smi.h   SMI library header file
       /usr/share/mibs/     SMI module repository directory

SEE ALSO

       libsmi(3), smi.h

AUTHOR

       (C) 1999-2001 Frank Strauss, TU Braunschweig, Germany <strauss@ibr.cs.tu-bs.de>