.\" Copyright (c) 1993 by Mike Sample and UBC
.\" See section COPYING for conditions for redistribution
.\" $Header: /cvs/Darwin/Security/SecuritySNACCRuntime/doc/snacc.1,v 1.1.1.1 2001/05/18 23:14:10 mb Exp $
.\" $Log: snacc.1,v $
.\" Revision 1.1.1.1 2001/05/18 23:14:10 mb
.\" Move from private repository to open source repository
.\"
.\" Revision 1.1.1.1 1999/03/16 18:05:54 aram
.\" Originals from SMIME Free Library.
.\"
.\" Revision 1.3 1997/02/16 15:26:26 rj
.\" made return *this after calling abort()'' a compile time option.
.\"
.\" Revision 1.2 1997/01/01 22:47:16 rj
.\" first check-in
.\"
.TH SNACC 1 "11 July 1993"
.SH NAME
snacc \- ASN.1 to C, C++ or type table Compiler
.SH SYNOPSIS
.nf
snacc [\-h] [\-P] [\-t] [\-e] [\-d] [\-p] [\-f]\p
[\-c | \-C | \-idl | \-T <table output file>]\p
[\-u <useful types ASN.1 file>]\p
[\-mf <max file name len>]\p
[\-l <neg number>]\p
[\-meta] [\-tcl <module.type>]\p
[\-novolat]\p
<ASN.1 file list>
.SH
For complete and current documentation, refer to the snacc manual.
.I
.SH DESCRIPTION
Snacc (Sample Neufeld Asn.1 to C/C++ Compiler) generates C or C++
source code for BER encode and decode routines as well as print and
free routines for each type in the given ASN.1 modules.
Alternatively, snacc can produce type tables that can be used for
table based/interpreted encoding and decoding. The type table based
methods tend to be slower than their C or C++ counterparts but they
usually use less memory (table size vs. C/C++ object code).
Most of the 1990 ASN.1 features are parsed although some do not affect
the generated code. Fairly rigourous error checking is performed on
the ASN.1 source; any errors detected will be reported (printed to
stderr).
Each file in the ASN.1 file list should contain a complete ASN.1
module. ASN.1 modules that use the IMPORTS feature must be compiled
together (specify all necessary modules in the ASN.1 file list). The
generated source files will include each module's header file in the
command line order. This makes it important to order the modules from
least dependent to most dependent on the command line to avoid type
ordering problems. Currently, snacc assumes that each ASN.1 file
given on the command line depends on all of the others on the command
line. No attempt is made to only include the header files from
modules referenced in the import list for that module.
If the target language is C, snacc will generate a \c
.B .h
and
.B .c
file for each specified ASN.1 module. If the target language is C++,
snacc will generate a
.B .h
and
.B .C
file for each module. The generated file names will be derived from the
module names.
.SH OPTIONS
.TP
.B \-h
Help. Prints a synopsis of snacc and exits.
.TP
.B \-c
Generate C source code. This is the default behaviour of snacc.
Only one of \c
.B \-c
,
.B \-C
or
.B \-T
should be specified.
.TP
.B \-C
Generate C++ source code.
.TP
.B \-novolat
Generate ``return *this'' after calling ``abort()''.
(Some broken compilers don't know about volatile functions, or their abort() isn't correctly typed.)
.TP
.B -meta
Generate meta code that describes the generated types.
Implies -C.
.TP
.B -tcl
.IR module.type [, module.type ]
Generate code for a Tcl interpreter where \fImodule.type\fP are the top level PDUs.
Implies -meta.
.TP
.BI "\-T " file\c
This causes snacc to generate type tables and write them to the given
file.
.TP
.B \-P
This causes snacc to print the parsed ASN.1 modules to stdout after
the types have been linked, sorted, and processed. This option is
useful for debugging snacc and observing the modifications snacc
performs on the types to make code generation simpler.
.TP
.B \-t
Generate type definitions in the target language for each ASN.1 type.
.TP
.B \-v
Generate value definitions in the target language for each ASN.1 value.
Currently value definitions are limited to INTEGERs, BOOLEANs and
OBJECT IDENTIFIERs.
.TP
.B \-e
Generate encode routines in the target language for each ASN.1 type.
.TP
.B \-d
Generate decode routines in the target language for each ASN.1 type.
.TP
.B \-p
Generate print routines in the target language for each ASN.1 type.
.TP
.B \-f
Generate free routines in the target language for each ASN.1 type.
This option only works when the target language is C.
If none of the
.B \-t, \-v, \-e, \-d, \-p, or \-f
options are given on
the command line, snacc assumes that all of them are in effect.
They do not affect type table generation.
.TP
.BI "\-u " file\c
\&Read the useful types definitions from the ASN.1 module in file \c
.I file\c
\& for linking purposes. For some ASN.1 specifications, such as SNMP,
the useful types are not needed. The types in the given useful types
file are globally available to all modules; a useful type definition
is overridden by a local or explicitly imported type with the same
name. The current list of useful types is:
.RS 9
ObjectDecscriptor
.br
NumericString
.br
PrintableString
.br
TeletexString
.br
T61String
.br
VideoTexString
.br
IA5String
.br
GraphicString
.br
ISO646String
.br
GeneralString
.br
UTCTime
.br
GeneralizedTime
.br
EXTERNAL
.RE
.TP
.BI "\-mf " number\c
\&This causes the generated source files to have a
maximum length of \c
.I number\c
characters, including their suffix. The \c
.I number\c
must be at least 3. This option is useful for supporting operating
systems that only support short file names. A better solution is to
shorten the module name of each ASN.1 module.
.TP
.BI "\-l " number\c
\&This is fairly obscure but may be useful. Each error that the
decoders can report is given an id number. The number \c
.I number\c
is where the error ids start decreasing from as they are assigned to
errors . The default is -100 if this option is not given. Avoid
using a number in the range -100 to 0 since they may conflict with the
library routines' error ids. If you are re-compiling the useful types
for the library use -50. Another use of this option is to integrate
newly generated code with older code; if done correctly, the error ids
will not conflict.
.PP
.\" there is a tab between the file name and the description
.SH FILES
.PD 0
.TP 28
.B snacc/asn1specs/asn-useful.asn1
ASN.1 useful types module (use with \-u option)
.TP
.B snacc/c-lib/inc/
C runtime library include files
.TP
.B snacc/c-lib/libasn1csbuf.a
C SBuf runtime library
.TP
.B snacc/c-lib/libasn1cmbuf.a
C MinBuf runtime library
.TP
.B snacc/c-lib/libasn1cebuf.a
C ExpBuf runtime library
.TP
.B snacc/c++-lib/inc/
C++ runtime library include files
.TP
.B snacc/c++-lib/libasn1c++.a
C++ runtime library
.TP
.B snacc/c-lib/inc/tbl*/
Type table runtime library include files
.TP
.B snacc/c-lib/libasn1ctbl.a
Type table runtime library
.TP
.B snacc/tbl-tools/
Source code for table based tools (mkchdr, ptbl, pval)
.TP
.B snacc/c-examples/
directory with ASN.1 to C examples
.TP
.B snacc/c++-examples/
directory with ASN.1 to C++ examples
.TP
.B snacc/tbl-example
directory with an ASN.1 to type table example
.TP
.B snacc/doc
directory with snacc documentation and this man page
.PD
.SH BUGS
Snacc has problems with the following case:
.RS
.nf
Foo ::= SEQUENCE
{
id IdType,
val ANY DEFINED BY id
}
IdType ::= CHOICE
{
a INTEGER,
b OBJECT IDENTIFIER
}
.fi
.RE
The error checking pass will print an error to the effect that the id
type must be INTEGER or OBJECT IDENTIFER. To fix this you must modify
the error checking pass as well as the code generation pass. To be
cheap about it, disable/fix the error checking and hand modify the
generated code.
The hashing code used for handling ANY DEFINED BY id to type mappings
will encounter problems if the hash table goes more than four levels
deep (I think this is unlikely). To fix this just add linear chaining
at fourth level.
Please send bug reports or comments to
.\".BR snacc-bugs@cs.ubc.ca .
.BR "Robert Joop <rj@rainbow.in-berlin.de>" .
See the documentation about reporting bugs and (lack of) support.
.SH COPYING
Copyright (c) 1993 Mike Sample and the University of British Columbia
.br
Copyright (c) 1994 1995 Robert Joop and GMD Fokus.
.PP
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.
.PP
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.
.PP
The snacc compiler is released under the GNU General Public License.
The runtime libraries are no longer under the GNU Library General
Public License. The generated code is yours.
.SH AUTHOR
Snacc was written by Mike Sample at the University of British Columbia
(UBC). He used it as a tool to do encoding/decoding performance
research.
.PP
It was augmented by Robert Joop at GMD Fokus with the help of some of its project partners.
.SH ACKNOWLEDGEMENTS
This work was made possible by grants from the Canadian Institute for
Telecommunications Research (CITR) and Natural Sciences and
Engineering Research Council of Canada (NSERC).