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 June 29, 2018 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 48The 49.Nm 50utility is used to either generate C language tables and header files from 51a MIB description or to numeric OIDs from MIB descriptions. 52The first form is used only for maintaining the 53.Xr bsnmpd 1 54daemon or for module writers. 55The second form may be used by SNMP client program writers. 56.Pp 57If none of the options 58.Fl e , 59.Fl E 60or 61.Fl t 62are used 63.Nm 64reads a MIB description from its standard input and creates two files: a 65C-file 66.Ar prefix Ns tree.c 67containing a table used by 68.Xr bsnmpd 1 69during PDU processing 70and a header file 71.Ar prefix Ns tree.h 72containing appropriate declarations of the callback functions used in this 73table, the table itself and definitions for all enums. 74.Pp 75The following options are available: 76.Bl -tag -width ".Fl E" 77.It Fl d 78Switch on debugging. 79.It Fl E 80Extract enumerations and bit constructs. 81In this mode the tool emits 82a header file that contains for each type given on the command line a 83C-enum definition and a preprocessor define that may be used to map 84values to strings. 85.It Fl e 86.Nm 87expects MIB variable names (only the last component) on its command line. 88It reads a MIB specification from standard input and for each MIB variable 89name 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 92This define can be used to initialize a 93.Va struct asn_oid 94in the following way: 95.Pp 96.Dl const struct asn_oid oid_sysDescr = OIDX_sysDescr; 97.It Va OIDLEN_ Ns Ar name 98is the length of the OID. 99.It Va OID_ Ns Ar name 100is the last component of the OID. 101.El 102.It Fl F 103Together with 104.Fl E 105causes 106.Nm 107instead of the generation of enum definitions the generation of 108functions for checking a value to be one of the enumeration variants and 109for conversion between strings and the enum. The file is sent to standard 110output and is meant to be included into a C-file for compilation. 111.It Fl f 112This flag can be used together with 113.Fl E 114or when generating the tree files. It causes 115.Nm 116to emit static inline functions for checking a value to be one of the 117enumeration values and for conversion between strings and the enum. 118If used when generating the tree files, the preprocessor symbol 119.Ar SNMPTREE_TYPES 120must be defined when including the tree header file for these definitions 121to become visible. 122.It Fl h 123Print a short help page. 124.It Fl I Ar directory 125Add the named directory to the include path just before the standard include 126directories. 127.It Fl i Ar infile 128Read from the named file instead of standard input. 129.It Fl l 130Generate local preprocessor includes. 131This is used for bootstrapping 132.Xr bsnmpd 1 . 133.It Fl t 134Instead of normal output print the resulting tree. 135.It Fl p Ar prefix 136Prefix the file names and the table name with 137.Ar prefix . 138.El 139.Pp 140The following functions are generated by 141.Fl f 142or 143.Fl F : 144.Pp 145.Ft static inline int 146.Fn isok_EnumName "enum EnumName" ; 147.Pp 148.Ft static inline const char * 149.Fn tostr_EnumName "enum EnumName" ; 150.Pp 151.Ft static inline int 152.Fn fromstr_EnumName "const char *" "enum EnumName *" ; 153.Pp 154The 155.Fa EnumName 156is replaced with the enumeration name. 157.Fn isok_EnumName 158returns 1 if the argument is one of the valid enum values and 0 otherwise. 159.Fn tostr_EnumName 160returns a string representation of the enumeration value. 161If the values is not one of the legal values 162.Ar EnumName??? 163is returned. 164.Fn fromstr_EnumName 165returns 1 if the string represents one of the legal enumeration values and 1660 otherwise. 167If 1 is return the variable pointed to by the second argument is set to 168the enumeration value. 169.Sh MIBS 170The syntax of the MIB description file can formally be specified as follows: 171.Bd -unfilled -offset indent 172 file := top | top file 173 174 top := tree | typedef | include 175 176 tree := head elements ')' 177 178 entry := head ':' index STRING elements ')' 179 180 leaf := head type STRING ACCESS ')' 181 182 column := head type ACCESS ')' 183 184 type := BASETYPE | BASETYPE '|' subtype | enum | bits 185 186 subtype := STRING 187 188 enum := ENUM '(' value ')' 189 190 bits := BITS '(' value ')' 191 192 value := INT STRING | INT STRING value 193 194 head := '(' INT STRING 195 196 elements := EMPTY | elements element 197 198 element := tree | leaf | column 199 200 index := type | index type 201 202 typedef := 'typedef' STRING type 203 204 include := 'include' filespec 205 206 filespec := '"' STRING '"' | '<' STRING '>' 207.Ed 208.Pp 209.Ar BASETYPE 210specifies a SNMP data type and may be one of 211.Bl -bullet -offset indent -compact 212.It 213NULL 214.It 215INTEGER 216.It 217INTEGER32 (same as INTEGER) 218.It 219UNSIGNED32 (same as GAUGE) 220.It 221OCTETSTRING 222.It 223IPADDRESS 224.It 225OID 226.It 227TIMETICKS 228.It 229COUNTER 230.It 231GAUGE 232.It 233COUNTER64 234.El 235.Pp 236.Ar ACCESS 237specifies the accessibility of the MIB variable (which operation can be 238performed) and is one of 239.Bl -bullet -offset indent -compact 240.It 241GET 242.It 243SET 244.El 245.Pp 246.Ar INT 247is a decimal integer and 248.Ar STRING 249is any string starting with a letter or underscore and consisting of 250letters, digits, underscores and minuses, that is not one of the keywords. 251.Pp 252The 253.Ar typedef 254directive associates a type with a single name. 255.Pp 256The 257.Ar include 258directive is replaced by the contents of the named file. 259.Sh EXAMPLES 260The following MIB description describes the system group: 261.Bd -literal -offset indent 262include "tc.def" 263 264typedef AdminStatus ENUM ( 265 1 up 266 2 down 267) 268 269(1 internet 270 (2 mgmt 271 (1 mibII 272 (1 system 273 (1 sysDescr OCTETSTRING op_system_group GET) 274 (2 sysObjectId OID op_system_group GET) 275 (3 sysUpTime TIMETICKS op_system_group GET) 276 (4 sysContact OCTETSTRING op_system_group GET SET) 277 (5 sysName OCTETSTRING op_system_group GET SET) 278 (6 sysLocation OCTETSTRING op_system_group GET SET) 279 (7 sysServices INTEGER op_system_group GET) 280 (8 sysORLastChange TIMETICKS op_system_group GET) 281 (9 sysORTable 282 (1 sysOREntry : INTEGER op_or_table 283 (1 sysORIndex INTEGER) 284 (2 sysORID OID GET) 285 (3 sysORDescr OCTETSTRING GET) 286 (4 sysORUpTime TIMETICKS GET) 287 )) 288 ) 289 ) 290 ) 291) 292.Ed 293.Sh SEE ALSO 294.Xr bsnmpd 1 295.Sh AUTHORS 296.An Hartmut Brandt Aq harti@FreeBSD.org 297