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
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
103emit definitions for C-functions includeable in a C-file that do some basic
104stuff on enums like value checking and conversion between value and strings.
105.It Fl f
106emit definitions for inline C-functions that do some basic
107stuff on enums like value checking and conversion between value and strings.
108.It Fl h
109Print a short help page.
110.It Fl I Ar directory
111Add the named directory to the include path just before the standard include
112directories.
113.It Fl i Ar infile
114Read from the named file instead of standard input.
115.It Fl l
116Generate local preprocessor includes.
117This is used for bootstrapping
118.Xr bsnmpd 1 .
119.It Fl t
120Instead of normal output print the resulting tree.
121.It Fl p Ar prefix
122Prefix the file names and the table name with
123.Ar prefix .
124.El
125.Sh MIBS
126The 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
166specifies a SNMP data type and may be one of
167.Bl -bullet -offset indent -compact
168.It
169NULL
170.It
171INTEGER
172.It
173INTEGER32 (same as INTEGER)
174.It
175UNSIGNED32 (same as GAUGE)
176.It
177OCTETSTRING
178.It
179IPADDRESS
180.It
181OID
182.It
183TIMETICKS
184.It
185COUNTER
186.It
187GAUGE
188.It
189COUNTER64
190.El
191.Pp
192.Ar ACCESS
193specifies the accessibility of the MIB variable (which operation can be
194performed) and is one of
195.Bl -bullet -offset indent -compact
196.It
197GET
198.It
199SET
200.El
201.Pp
202.Ar INT
203is a decimal integer and
204.Ar STRING
205is any string starting with a letter or underscore and consisting of
206letters, digits, underscores and minuses, that is not one of the keywords.
207.Pp
208The
209.Ar typedef
210directive associates a type with a single name.
211.Pp
212The
213.Ar include
214directive is replaced by the contents of the named file.
215.Sh EXAMPLES
216The following MIB description describes the system group:
217.Bd -literal -offset indent
218include "tc.def"
219
220typedef 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
253