contrib/bsnmp/gensnmptree/gensnmptree.1

   1 .\"
   2 .\" Copyright (c) 2001-2005
   3 .\"     Fraunhofer Institute for Open Communication Systems (FhG Fokus).
   4 .\"     All rights reserved.
   5 .\" Copyright (c) 2006,2018
   6 .\"     Hartmut Brandt
   7 .\"     All rights reserved.
   8 .\"
   9 .\" Author: Harti Brandt <harti@FreeBSD.org>
  10 .\"
  11 .\" Redistribution and use in source and binary forms, with or without
  12 .\" modification, are permitted provided that the following conditions
  13 .\" are met:
  14 .\" 1. Redistributions of source code must retain the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer.
  16 .\" 2. Redistributions in binary form must reproduce the above copyright
  17 .\"    notice, this list of conditions and the following disclaimer in the
  18 .\"    documentation and/or other materials provided with the distribution.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\" $Begemot: gensnmptree.1 383 2006-05-30 07:40:49Z brandt_h $
  33 .\"
  34 .Dd April 2, 2019
  35 .Dt GENSNMPTREE 1
  36 .Os
  37 .Sh NAME
  38 .Nm gensnmptree
  39 .Nd "generate C and header files from a MIB description file"
  40 .Sh SYNOPSIS
  41 .Nm
  42 .Op Fl dEeFfhlt
  43 .Op Fl I Ar directory
  44 .Op Fl i Ar infile
  45 .Op Fl p Ar prefix
  46 .Op Ar name Ar ...
  47 .Sh DESCRIPTION
  48 The
  49 .Nm
  50 utility is used to either generate C language tables and header files from
  51 a MIB description or to numeric OIDs from MIB descriptions.
  52 The first form is used only for maintaining the
  53 .Xr bsnmpd 1
  54 daemon or for module writers.
  55 The second form may be used by SNMP client program writers.
  56 .Pp
  57 If none of the options
  58 .Fl e ,
  59 .Fl E
  60 or
  61 .Fl t
  62 are used
  63 .Nm
  64 reads a MIB description from its standard input and creates two files: a
  65 C-file
  66 .Ar prefix Ns tree.c
  67 containing a table used by
  68 .Xr bsnmpd 1
  69 during PDU processing
  70 and a header file
  71 .Ar prefix Ns tree.h
  72 containing appropriate declarations of the callback functions used in this
  73 table, the table itself and definitions for all enums.
  74 .Pp
  75 The following options are available:
  76 .Bl -tag -width ".Fl E"
  77 .It Fl d
  78 Switch on debugging.
  79 .It Fl E
  80 Extract enumerations and bit constructs.
  81 In this mode the tool emits
  82 a header file that contains for each type given on the command line a
  83 C-enum definition and a preprocessor define that may be used to map
  84 values to strings.
  85 .It Fl e
  86 .Nm
  87 expects MIB variable names (only the last component) on its command line.
  88 It reads a MIB specification from standard input and for each MIB variable
  89 name emits three C preprocessor defines on its standard output:
  90 .Bl -tag -width ".Va OIDLEN_ Ns Ar Name"
  91 .It Va OIDX_ Ns Ar name
  92 This define can be used to initialize a
  93 .Va struct asn_oid
  94 in the following way:
  95 .Pp
  96 .Dl const struct asn_oid oid_sysDescr = OIDX_sysDescr;
  97 .It Va OIDLEN_ Ns Ar name
  98 is the length of the OID.
  99 .It Va OID_ Ns Ar name
 100 is the last component of the OID.
 101 .El
 102 .It Fl F
 103 emit definitions for C-functions includeable in a C-file that do some basic
 104 stuff on enums like value checking and conversion between value and strings.
 105 .It Fl f
 106 emit definitions for inline C-functions that do some basic
 107 stuff on enums like value checking and conversion between value and strings.
 108 .It Fl h
 109 Print a short help page.
 110 .It Fl I Ar directory
 111 Add the named directory to the include path just before the standard include
 112 directories.
 113 .It Fl i Ar infile
 114 Read from the named file instead of standard input.
 115 .It Fl l
 116 Generate local preprocessor includes.
 117 This is used for bootstrapping
 118 .Xr bsnmpd 1 .
 119 .It Fl t
 120 Instead of normal output print the resulting tree.
 121 .It Fl p Ar prefix
 122 Prefix the file names and the table name with
 123 .Ar prefix .
 124 .El
 125 .Sh MIBS
 126 The syntax of the MIB description file can formally be specified as follows:
 127 .Bd -unfilled -offset indent
 128  file := top | top file
 129
 130  top := tree | typedef | include
 131
 132  tree := head elements ')'
 133
 134  entry := head ':' index STRING elements ')'
 135
 136  leaf := head type STRING ACCESS ')'
 137
 138  column := head type ACCESS ')'
 139
 140  type := BASETYPE | BASETYPE '|' subtype | enum | bits
 141
 142  subtype := STRING
 143
 144  enum := ENUM '(' value ')'
 145
 146  bits := BITS '(' value ')'
 147
 148  value := INT STRING | INT STRING value
 149
 150  head := '(' INT STRING
 151
 152  elements := EMPTY | elements element
 153
 154  element := tree | leaf | column
 155
 156  index := type | index type
 157
 158  typedef := 'typedef' STRING type
 159
 160  include := 'include' filespec
 161
 162  filespec := '"' STRING '"' | '<' STRING '>'
 163 .Ed
 164 .Pp
 165 .Ar BASETYPE
 166 specifies a SNMP data type and may be one of
 167 .Bl -bullet -offset indent -compact
 168 .It
 169 NULL
 170 .It
 171 INTEGER
 172 .It
 173 INTEGER32 (same as INTEGER)
 174 .It
 175 UNSIGNED32 (same as GAUGE)
 176 .It
 177 OCTETSTRING
 178 .It
 179 IPADDRESS
 180 .It
 181 OID
 182 .It
 183 TIMETICKS
 184 .It
 185 COUNTER
 186 .It
 187 GAUGE
 188 .It
 189 COUNTER64
 190 .El
 191 .Pp
 192 .Ar ACCESS
 193 specifies the accessibility of the MIB variable (which operation can be
 194 performed) and is one of
 195 .Bl -bullet -offset indent -compact
 196 .It
 197 GET
 198 .It
 199 SET
 200 .El
 201 .Pp
 202 .Ar INT
 203 is a decimal integer and
 204 .Ar STRING
 205 is any string starting with a letter or underscore and consisting of
 206 letters, digits, underscores and minuses, that is not one of the keywords.
 207 .Pp
 208 The
 209 .Ar typedef
 210 directive associates a type with a single name.
 211 .Pp
 212 The
 213 .Ar include
 214 directive is replaced by the contents of the named file.
 215 .Sh EXAMPLES
 216 The following MIB description describes the system group:
 217 .Bd -literal -offset indent
 218 include "tc.def"
 219
 220 typedef AdminStatus ENUM (
 221         1 up
 222         2 down
 223 )
 224
 225 (1 internet
 226   (2 mgmt
 227     (1 mibII
 228       (1 system
 229         (1 sysDescr OCTETSTRING op_system_group GET)
 230         (2 sysObjectId OID op_system_group GET)
 231         (3 sysUpTime TIMETICKS op_system_group GET)
 232         (4 sysContact OCTETSTRING op_system_group GET SET)
 233         (5 sysName OCTETSTRING op_system_group GET SET)
 234         (6 sysLocation OCTETSTRING op_system_group GET SET)
 235         (7 sysServices INTEGER op_system_group GET)
 236         (8 sysORLastChange TIMETICKS op_system_group GET)
 237         (9 sysORTable
 238           (1 sysOREntry : INTEGER op_or_table
 239             (1 sysORIndex INTEGER)
 240             (2 sysORID OID GET)
 241             (3 sysORDescr OCTETSTRING GET)
 242             (4 sysORUpTime TIMETICKS GET)
 243         ))
 244       )
 245     )
 246   )
 247 )
 248 .Ed
 249 .Sh SEE ALSO
 250 .Xr bsnmpd 1
 251 .Sh AUTHORS
 252 .An Hartmut Brandt Aq harti@FreeBSD.org