'\"
'\" Copyright (c) 1994-1996 Technical University of Braunschweig.
'\" Copyright (c) 1996-1997 University of Twente.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
.so man.macros
.TH mib n "July 1997" Tnm "Tnm Tcl Extension"
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
mib \- Load and access SNMP MIB definitions.
.BE

.SH DESCRIPTION

The mib command allows to load and access SNMP MIB definitions that
are written down in MIB files according to the rules defined in the
Structure of Management Information (SMI) (RFC 1155, RFC 1212, RFC
1902 and RFC 1903). Queries are either formulated for a specific node
in the MIB tree or a specific type defined in a MIB module. The mib
command also allows to format/scan MIB values from/to their underlying
primitive representation and to compare object identifier based on
their lexicographic order.

.SH MIB NODES

A MIB node is either identified by the globally unique object
identifier in dotted notation (e.g. 1.3.6.1.2.1.1.1) or by its
globally unique fully qualified name (e.g. SNMPv2-MIB!sysDescr). Fully
qualified names are composed out of the module name, which contains
the definition of the MIB node, an exclamation mark and the label of
the MIB node.

Simple names are also accepted in addition to fully qualified names. A
simple name is a single label (e.g. sysDescr) or a sequence of labels
seperated by dots (system.sysDescr). Simple names are not necessarily
unique and should be avoided in scripts where the set of MIB objects
is not known at implementation time.

It is possible to have numerical subidentifiers appended to a node
name. These subidentifiers can specify an instance identifier for a
MIB node (e.g. SNMPv2-MIB!sysDescr.0) or they can specify a path
within the subtree defined by the node name (e.g. SNMPv2-MIB!system.1)
or both (e.g. SNMPv2-MIB!system.1.0).

It is possible to have hexadecimal sub-identifier in an object
identifier. A colon instead of a dot is used to indicate that the
following sub-identifier should be read as a hexadecimal value.  For
example, the object identifier 1.3.6.1.4.1:627:74:75:62:73 will be
converted to 1.3.6.1.4.1.1575.116.117.98.115. You can also use a dot
followed by a hexadecimal sub-identifier where the first two
characters of the sub-identifier are 0x. It is also possible to mix
both representation, e.g. 1.3.6.1.4.1.0x627:74:75:62:73.

It is suggested to use the object identifier notation as much as
possible when referring to MIB nodes in scripts. Globally unique names
(like SNMPv2-MIB!sysDescr) are also a good and fast choice. Simple
names may lead to ambiguities and can result is slower lookups if a
name can not be found in the underlying hash table. Composed simple
names (like system.sysDescr) make ambiguities less likely but they may
cause substantial overhead.

.SH MIB TYPES

Every MIB object has an associated type. The set of primitive type is
defined in the SNMP SMI (see the snmp(n) man page for a list of
supported SNMP SMI types). 

Derived types are either explicitly defined by the invocation of a
TEXTUAL-CONVENTION macro or implicitly by putting value restrictions
or enumerations in an OBJECT-TYPE macro. The Tnm extension converts
implicit type definitions into explicit type definitions in order to
handle both in a uniform way.

A type is referenced by the type name. A type name is constructed out
of the module name which contains the type definition, an exclamation
mark and the type label. A type label of an explicit type is the label
used in the TEXTUAL-CONVENTION macro. The label for an implicit type
is the capitalized label of the OBJECT-TYPE macro which was used to
define the type. For example, the string SNMPv2-TC!DisplayString
refers to the SNMPv2-TC module which defines the DisplayString textual
convention. The string IF-MIB!IfOperStatus refers to the implicit type
definition in the IF-MIB module, object ifOperStatus.

.SH MIB COMMAND

.TP
.B mib access \fInode\fR
The \fBmib access\fR command returns the maximal access allowed for a
MIB node or an empty string if there is no access defined for
\fInode\fR. The result is therefore one of the strings "",
"not-accessible", "read-only", "read-create", "read-write",
"write-only", or "accessible-for-notify". The \fInode\fR argument may
be a node name or an object identifier in one of the formats discussed
above.

.TP
.B mib children \fInode\fR
The \fBmib children\fR command returns a list of all known child nodes
of a given MIB node. The \fInode\fR argument may be a node name in one
of the formats discussed above. The format of the result depends on
the format of \fInode\fR: The result is a list of object identifier
values if \fInode\fR is an object identifier value. The result is a
list of fully qualified MIB node names if \fInode\fR is a MIB node
name.

.TP
.B mib compare \fIoid1 oid2\fR
The \fBmib compare\fR command compares two object identifier given as
\fIoid1\fR and \fIoid2\fR based on their lexicographic order. The
command returns -1, 0 or 1, depending on whether the object identifier
given by \fIoid1\fR is less than, equal to, or greater than the object
identifier given by \fIoid2\fR. The \fIoid1\fR and \fIoid2\fR arguments
may be object identifiers or a node names in one of the formats
discussed above.

.TP
.B mib description \fInode\fR
The \fBmib description\fR command returns the textual description of a
MIB node. The \fInode\fR argument may be a node name in one of the
formats discussed above. This command requires that the file
containing the MIB definition is accessible at run-time.

.TP
.B mib displayhint \fItype\fR
The \fBmib displayhint\fR command returns the display-hint associated
with \fItype\fR or an empty string if there is not display-hint
defined for \fItype\fR. The \fItype\fR argument may be a type name in
one of the formats discussed above.

.TP
.B mib enums \fItype\fR
The \fBmib enums\fR command returns the enumerations associated with
\fItype\fR or an empty string if there are no enumerations defined for
\fItype\fR. The \fItype\fR argument may be a type name in one of the
formats discussed above. The result is a flat list of labels and
associated numbers.

.TP
.B mib exists \fInodeOrType\fR
The \fBmib exists\fR command tests if \fInodeOrType\fR refers to a
known MIB node or type. The command returns 1 if \fInodeOrType\fR
exists and 0 otherwise. The \fInodeOrType\fR argument may be a node
name, a type name or an object identifier in one of the formats
discussed above.

.TP
.B mib file \fInodeOrType\fR
The \fBmib file\fR command returns the file name which contains the
definition of the MIB node or the MIB type. The \fInodeOrType\fR
argument may be a node name, a type name or an object identifier in
one of the formats discussed above. 

.TP
.B mib format \fInodeOrType\fR \fIvalue\fR
The \fBmib format\fR command applies formatting rules associated with
a MIB type to a \fIvalue\fR. The \fIvalue\fR is expected to be in a
format which complies to the rules defined for the underlying base
type.  The type is selected by the \fInodeOrType\fR argument. If
\fInodeOrType\fR refers to a MIB node, the type associated with that
MIB node will be used. The \fInodeOrType\fR argument may be a node
name, a type name or an object identifier in one of the formats
discussed above.

The \fBmib format\fR command can be used to render integer values into
enumerations, to apply display hints, to render integer values into
time tick strings or to convert object identifier into fully qualified
names.

.TP
.B mib index \fInode\fR
The \fBmib index\fR command returns the list of MIB labels which are
used as a key in a conceptual table or an empty result if the MIB node
does not identify a conceptual table. The \fInode\fR argument may be a
node name in one of the formats discussed above.

.TP
.B mib instance \fInode\fR
The \fBmib instance\fR command returns the instance part of an object
identifier or MIB node name. The \fInode\fR argument may be a node
name in one of the formats discussed above. No checks to made to
ensure that the instance identifier is valid.

.TP
.B mib label \fInode\fR
The \fBmib label\fR command returns the label of a MIB node. The
\fInode\fR argument may be a node name or an object identifier in one
of the formats discussed above. The returned label is not necessarily
unique and should not be used to refer to the MIB node.

.TP
.B mib length \fIoid\fR
The \fBmib length\fR command returns the length of the object
identifier \fIoid\fR. The length is defined as the number of
subidentifiers. The \fIoid\fR argument can be an object identifier
or a node name in one of the formats discussed above.

.TP
.B mib load \fIfile\fR
The \fBmib load\fR command loads the MIB definitions contained in
\fIfile\fR. The built-in parser reads the \fIfile\fR and creates
internal data structures in main memory. Parsing errors are written to
stderr. Not all MIB information is actually kept in memory due to the
size of some MIB definitions. Instead, some pointers into the
\fIfile\fR are maintained in main memory. Some commands described in
this man page will not work as expected if the \fIfile\fR is removed
after the MIB definitions have been loaded.

The \fBmib load\fR command first tries to locate the \fIfile\fR in the
current directory. The \fBmib load\fR command automatically tries to
locate the file in the $tnm(library)/site and the $tnm(library)/mibs
directory if the \fIfile\fR does not exist in the current directory.
A condensed format of the MIB definition is saved in the platform
specific directory $tnm(library)/$tnm(arch) to speed up future load
commands. Note, this requires write permissions for the platform
specific sub-directory. Missing write permissions will be silently
ignored, which might result is increased MIB loading times.

The Tnm extension uses two global Tcl variables to control which set
of MIB files is loaded automatically. The Tcl variable $tnm(mibs:core)
contains the names of the MIB files that make up the SNMPv1 and SNMPv2
core definitions. The $tnm(mibs) contains the list of MIB file names
that are useful on your site. The default value of $tnm(mibs) is the
set of all IETF MIBs published as RFCs. You can customize this set of
MIBs in the $tnm(library)/site/init.tcl script. It is possible to
bypass the auto-loading mechanism if the first \fBmib\fR command is a
\fBmib load\fR command. Note that the \fBsnmp\fR command also invokes
\fBmib\fR commands internally. It is therefore a good idea to load MIB
definitions at the beginning of a script.

.TP
.B mib macro \fInodeOrType\fR
The \fBmib macro\fR command returns the name of the ASN.1 macro used
to define the MIB node or MIB type. The \fInodeOrType\fR argument may
be a node name, a type name or an object identifier in one of the
formats discussed above. An empty string is returned if the node or
type is not defined by an ASN.1 macro. The legal return values are
therefore "", "OBJECT-TYPE", "OBJECT-IDENTITY", "MODULE-IDENTITY",
"NOTIFICATION-TYPE", "TRAP-TYPE", "OBJECT-GROUP",
"NOTIFICATION-GROUP", "MODULE-COMPLIANCE", "AGENT-CAPABILITIES", or
"TEXTUAL-CONVENTION".

.TP
.B mib module \fInodeOrType\fR 
The \fBmib module\fR command returns the name of the module which
contains the definition of the MIB node or type. The \fInodeOrType\fR
argument may be a node name, a type name or an object identifier in
one of the formats discussed above.

.TP
.B mib name \fInode\fR
The \fBmib name\fR command returns the fully qualified name associated
with a node in the MIB tree. The \fInode\fR argument may be a node
name or an object identifier in one of the formats discussed
above.

.TP
.B mib oid \fInode\fR
The \fBmib oid\fR command is the counterpart to the \fBmib name\fR
command and returns the object identifier of the MIB node identified
by \fInode\fR. The \fInode\fR argument may be a node name in one of
the formats discussed above. The object identifier of the first
matching MIB node will be returned if \fInode\fR is not unique within
the set of currently loaded MIB definitions.

.TP
.B mib parent \fInode\fR 
The \fBmib parent\fR command returns the parent node of a MIB node.
The \fInode\fR argument may be a node name in one of the formats
discussed above. The format of the result depends on the format of
\fInode\fR: The result is an object identifier value if \fInode\fR is
an object identifier value. The result is a fully qualified MIB node
names if \fInode\fR is a MIB node name.

.TP
.B mib scan \fInodeOrType\fR \fIvalue\fR
The \fBmib scan\fR command implements the inverse operation of the
\fBmib format\fR command described above. It converts a rendered
\fIvalue\fR into the underlying base type representation. The \fBmib
scan\fR command returns the \fIvalue\fR unaltered if no conversions
apply. The conversion rules depend on the \fInodeOrType\fR argument.
If \fInodeOrType\fR refers to a MIB node, the type associated with
that MIB node will be used. The \fInodeOrType\fR argument may be a
node name, a type name or an object identifier in one of the formats
discussed above.

The \fBmib scan\fR is useful in situations where you want to operate
on the primitive format rather than the rendered format. This allows
in some cases to implement calculations based on the base type in a
straight forward way, which would be difficult to do on the rendered
value.

.TP
.B mib syntax \fInodeOrType\fR
The \fBmib syntax\fR command returns the syntax associated with a MIB
node or a MIB type. An empty string is returned if the node identified
by \fInodeOrType\fR has no associated ASN.1 syntax. The \fInodeOrType\fR 
argument may be a node name, a type name or an object identifier in
one of the formats discussed above. The syntax name returned is the
syntax name used in the ASN.1 macro. 

.TP
.B mib walk \fIvarName node body\fR
The \fBmib walk\fR command evaluates the Tcl script \fIbody\fR for
each MIB node in the MIB subtree rooted at \fInode\fR. The \fInode\fR
argument may be a node name or an object identifier in one of the
formats discussed above.  The variable varName will hold the name or
the object identifier of the current MIB node whenever the \fIbody\fR
is evaluated. The format of the values assigned to \fIvarName\fR
depends on the format of the \fInode\fR argument: The value of
\fIvarName\fR is an object identifier value if \fInode\fR is an object
identifier value. The value of \fIvarName\fR is a fully qualified MIB
node names if \fInode\fR is a MIB node name.

.SH SEE ALSO
scotty(1), Tnm(n), Tcl(n)

.SH AUTHORS
Juergen Schoenwaelder <schoenw@cs.utwente.nl>
.br
Sven Schmidt
.br
Erik Schoenfelder <schoenfr@gaertner.de>
.br
