lib/smi_config.3.in

   1 .\"
   2 .\" $Id: smi_config.3.in 4432 2006-05-29 16:21:11Z strauss $
   3 .\"
   4 .TH smi_config 3  "August 22, 2001" "IBR" "SMI Management Information Library"
   5 .SH NAME
   6 .\" START OF MAN PAGE COPIES
   7 smiInit,
   8 smiExit,
   9 smiSetErrorLevel,
  10 smiGetFlags,
  11 smiSetFlags,
  12 smiLoadModule,
  13 smiGetPath,
  14 smiSetPath,
  15 smiReadConfig
  16 .\" END OF MAN PAGE COPIES
  17 \- SMI library
  18 configuration routines
  19 .SH SYNOPSIS
  20 .nf
  21 .B #include <smi.h>
  22 .RS
  23 .RE
  24 .sp
  25 .BI
  26 .RE
  27 .sp
  28 .BI "int smiInit(const char *" tag );
  29 .RE
  30 .sp
  31 .B "int smiExit();"
  32 .RE
  33 .sp
  34 .BI "void smiSetErrorLevel(int " level );
  35 .RE
  36 .sp
  37 .BI "int smiGetFlags();"
  38 .RE
  39 .sp
  40 .BI "void smiSetFlags(int " userflags );
  41 .RE
  42 .sp
  43 .BI "char *smiLoadModule(char *" module );
  44 .RE
  45 .sp
  46 .BI "int smiIsLoaded(char *" module );
  47 .RE
  48 .sp
  49 .BI "char *smiGetPath();"
  50 .RE
  51 .sp
  52 .BI "int smiSetPath(char *" path );
  53 .RE
  54 .sp
  55 .BI "int smiSetSeverity(char *" pattern ", int " severity );
  56 .RE
  57 .sp
  58 .BI "int smiReadConfig(char *" filename ", const char *" tag );
  59 .RE
  60 .sp
  61 .BI "void smiSetErrorHandler(SmiErrorHandler *" smiErrorHandler );
  62 .RE
  63
  64 typedef void (SmiErrorHandler) (char *path, int line,
  65                                 int severity, char *msg, char *tag);
  66
  67 .fi
  68 .SH DESCRIPTION
  69 These functions provide some initialization and adjustment operations
  70 for the SMI library.
  71 .PP
  72 The \fBsmiInit()\fP function should be the first SMI function called
  73 in an application. It initializes its internal structures. If \fItag\fP is
  74 not NULL, the global configuration file and (on UNIX systems)
  75 a user configuration file are read implicitly, if existent. All
  76 global statements and those statements with a tag (a ``tag: '' prefix) that
  77 matches the \fBtag\fP argument are executed.
  78 (see also CONFIGURATION FILES below).
  79 \fBsmiInit()\fP returns zero on success, or otherwise a negative value.
  80 .PP
  81 The \fBsmiInit()\fP function can also be used to support multiple sets
  82 of MIB data. In this case, the \fBtag\fP argument may be prepended by
  83 a colon and a name to differentiate the data sets. Any library
  84 function call subsequent to an \fBsmiInit("tag:dataset")\fP call is
  85 using the specified data set.
  86 .PP
  87 The \fBsmiExit()\fP function should be called when the application
  88 no longer needs any SMI information to release any allocated SMI
  89 resources.
  90 .PP
  91 The \fBsmiSetErrorLevel()\fP function sets the pedantic level (0-9) of
  92 the SMI parsers of the SMI library, currently SMIv1/v2 and SMIng.
  93 The higher the level, the louder it complains. Values up to 3
  94 should be regarded as errors, higher level could be interpreted as
  95 warnings.  But note that this classification is some kind of personal
  96 taste.  The default level is 0, since usually only MIB checkers want
  97 to tune a higher level.
  98 .PP
  99 The \fBsmiGetFlags()\fP and \fBsmiSetFlags()\fP functions allow to
 100 fetch, modify, and set some \fIuserflags\fP that control the SMI
 101 library's behaviour.  If \fBSMI_FLAG_ERRORS\fP is not set, no error messages
 102 are printed at all to keep the SMI library totally quiet, which might
 103 be mandatory for some applications. If \fBSMI_FLAG_STATS\fP is set, the
 104 library prints some module statistics. If \fBSMI_FLAG_RECURSIVE\fP is set,
 105 the library also complains about errors in modules that are read due
 106 to import statements. If \fBSMI_FLAG_NODESCR\fP is set, no description
 107 and references strings are stored in memory. This may save a huge amount
 108 of memory in case of applications that do not need this information.
 109 .PP
 110 The \fBsmiSetSeverity()\fP function allows to set the severity of
 111 all error that have name prefixed by \fBpattern\fP to the value \fBseverity\fP.
 112 .PP
 113 The \fBsmiLoadModule()\fP function specifies an additional MIB \fImodule\fP
 114 that the application claims to know or an additional file path to read.
 115 Only after a
 116 module is made known through this function, iterating retrieval
 117 functions and retrieval functions without fully qualified identifiers
 118 will return results from this module. \fBsmiLoadModule()\fP returns the
 119 name of the loaded module, of NULL if it could not be loaded.
 120 .PP
 121 The \fBsmiIsLoaded()\fP function returns a positive value if the
 122 module named \fImodule\fP is already loaded, or zero otherwise.
 123 .PP
 124 The \fBsmiGetPath()\fP and \fBsmiSetPath()\fP functions allow to
 125 fetch, modify, and set the path that is used to search MIB modules.
 126 \fBsmiGetPath()\fP returns a copy of the current search path in the
 127 form "DIR1:DIR2:...", or NULL if no path is set.
 128 The application should free this string if it is
 129 no longer needed. \fBsmiSetPath()\fP sets the search path to
 130 \fIpath\fP.
 131 .PP
 132 The \fBsmiReadConfig()\fP function reads the configuration file \fIfilename\fP.
 133 All global statements in the configuration file and those statements with
 134 a tag (a ``tag: '' prefix) that matches the \fBtag\fP argument, if present,
 135 are executed.
 136 .PP
 137 The \fBsmiSetErrorHandler()\fP function allows to set a callback function
 138 that is called by the MIB parsers deviating from the builtin default
 139 error handler, that prints error messages to stderr. The error handler
 140 has to comply with the \fBSmiErrorHandler\fP function type. The \fBpath\fP,
 141 \fBline\fP, \fBseverity\fP, \fBmsg\fP, and \fPtag\fP arguements carry the
 142 module's pathname, the line number within the module, the error severity
 143 level, a textual error message, and a short error name of the error being
 144 reported.
 145 .SH "MODULE LOCATIONS"
 146 The SMI library may retrieve MIB modules from different kinds of
 147 resources. Currently, SMIv1/v2 and SMIng module files are supported.
 148 If in an \fBsmiLoadModule()\fP function call a module is specified by
 149 a path name (identified by containing at least one dot or slash character),
 150 this
 151 is assumed to be the exact file to read. Otherwise, if a module is identified
 152 by its plain module name, the correspondant file (either SMIv1/2 or
 153 SMIng) is searched along a path. This path is initialized with @smipath@.
 154 Afterwards the optional global and user configuration files are parsed for
 155 `path' commands, and finally the optional \fBSMIPATH\fP environment variable
 156 is evaluated. The `path' command argument and the environment variable
 157 either start with a path separator character (`:' on UNIX-like systems, `;'
 158 on MS-Windows systems) to append
 159 to the path, or end with a path separator character to prepend to the path,
 160 or otherwise completely replace the path.
 161 The path can also be controlled by the \fBsmiGetPath()\fP
 162 and \fBsmiSetPath()\fP functions (see above).
 163 .PP
 164 When files are searched by a given module name, they might have no
 165 extension or one of the extensions `.my', `.smiv2', `.sming', `.mib',
 166 or `.txt'. However, the
 167 MIB module language is identified by the file's content, not by its
 168 file name extension.
 169 .SH "CONFIGURATION FILES"
 170 SMI library configuration files read at initialization and on demand
 171 by \fBsmiReadConfig()\fP have a simple line oriented syntax. Empty lines
 172 and those starting with `#' are ignored. Other lines start with an optional
 173 tag (prepended by a colon),
 174 followed by a command and options dependent on the command. Tags
 175 are used to limit the scope of a command to those applications that are
 176 using this tag.
 177 .PP
 178 The \fBload\fP command is used to preload a given MIB module. If multiple
 179 modules shall be preloaded, multiple \fBload\fP commands must be used.
 180 .PP
 181 The \fBpath\fP command allows to prepend or append components to the
 182 MIB module search path or to modify it completely (see
 183 also MODULE LOCATIONS above).
 184 .PP
 185 The \fBcache\fP command allows to add an additional directory for
 186 MIB module lookup as a last resort. The first argument specifies the
 187 directory and the rest of the line starting from the second argument
 188 specifies the caching method, which is invoked with the MIB module
 189 name appended if the module is found neither in one of the regular directories
 190 nor in the cache directory beforehand.
 191 .PP
 192 The \fBlevel\fP command sets the error level.
 193 .PP
 194 The \fBhide\fP command allows to tune the list of errors that are reported.
 195 It raises all errors with names prefixed by the given pattern to severity
 196 level 9. [Currently, there is no way to list the error names. RTFS: error.c.]
 197 .PP
 198 Example configuration:
 199 .nf
 200
 201   #
 202   # $HOME/.smirc
 203   #
 204
 205   # add a private directory
 206   path :/usr/home/strauss/lib/mibs
 207
 208   # don't show any errors by default
 209   level 0
 210
 211   # preload some basic modules
 212   load SNMPv2-SMI
 213   load SNMPv2-TC
 214   load SNMPv2-CONF
 215
 216   # want to make smilint shout
 217   smilint: level 8
 218
 219   # but please don't claim about
 220   # any names longer than 32 chars
 221   smilint: hide namelength-32
 222
 223   tcpdump: load DISMAN-SCRIPT-MIB
 224
 225   smiquery: load IF-MIB
 226   smiquery: load DISMAN-SCRIPT-MIB
 227 .fi
 228 .SH "FILES"
 229 .nf
 230 @sysconfdir@/smi.conf    global configuration file
 231 $HOME/.smirc               user configuration file
 232 @includedir@/smi.h   SMI library header file
 233 @mibdir@/     SMI module repository directory
 234 .fi
 235 .SH "SEE ALSO"
 236 .BR libsmi "(3), "
 237 .BR smi.h
 238 .SH "AUTHOR"
 239 (C) 1999-2001 Frank Strauss, TU Braunschweig, Germany <strauss@ibr.cs.tu-bs.de>
 240 .br