home | help 
smi_config(3)	       SMI Management Information Library	   smi_config(3)

NAME
     smiInit,  smiExit,  smiSetErrorLevel, smiGetFlags, smiSetFlags, smiLoadMod-
     ule, smiGetPath, smiSetPath, smiReadConfig - SMI library configuration rou-
     tines

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 appli-
     cation.  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 state-
     ments with a tag (a ``tag: '' prefix) that matches the tag argument are ex-
     ecuted.  (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  er-
     rors,  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	applica-
     tions. 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  infor-
     mation.

     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 re-
     sults from this module. smiLoadModule() returns the name of the loaded mod-
     ule, 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  exe-
     cuted.

     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 (identi-
     fied 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/lo-
     cal/share/smi/mibs/ietf:/usr/local/share/smi/mibs/iana:/usr/lo-
     cal/share/smi/mibs/irtf:/usr/local/share/smi/mibs/site:/usr/lo-
     cal/share/smi/mibs/tubs:/usr/local/share/smi/pibs/ietf:/usr/lo-
     cal/share/smi/pibs/site:/usr/local/share/smi/pibs/tubs.  Afterwards the op-
     tional  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  sys-
     tems)  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  exten-
     sion 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	applica-
     tions 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: er-
     ror.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
     ${prefix}/etc/smi.conf    global configuration file
     $HOME/.smirc		user configuration file
     ${prefix}/include/smi.h   SMI library header file
     /usr/local/share/smi/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>

IBR				 August 22, 2001		   smi_config(3)
home | help