SecuritySNACCRuntime/doc/snacc.1

   1 .\" Copyright (c) 1993 by Mike Sample and UBC
   2 .\" See section COPYING for conditions for redistribution
   3 .\" $Header: /cvs/Darwin/Security/SecuritySNACCRuntime/doc/snacc.1,v 1.1.1.1 2001/05/18 23:14:10 mb Exp $
   4 .\" $Log: snacc.1,v $
   5 .\" Revision 1.1.1.1  2001/05/18 23:14:10  mb
   6 .\" Move from private repository to open source repository
   7 .\"
   8 .\" Revision 1.1.1.1  1999/03/16 18:05:54  aram
   9 .\" Originals from SMIME Free Library.
  10 .\"
  11 .\" Revision 1.3  1997/02/16 15:26:26  rj
  12 .\" made return *this after calling abort()'' a compile time option.
  13 .\"
  14 .\" Revision 1.2  1997/01/01 22:47:16  rj
  15 .\" first check-in
  16 .\"
  17 .TH SNACC 1 "11 July 1993"
  18 .SH NAME
  19 snacc \- ASN.1 to C, C++ or type table Compiler
  20 .SH SYNOPSIS
  21 .nf
  22 snacc [\-h] [\-P] [\-t] [\-e] [\-d] [\-p] [\-f]\p
  23       [\-c | \-C | \-idl | \-T <table output file>]\p
  24       [\-u <useful types ASN.1 file>]\p
  25       [\-mf <max file name len>]\p
  26       [\-l <neg number>]\p
  27       [\-meta] [\-tcl <module.type>]\p
  28       [\-novolat]\p
  29       <ASN.1 file list>
  30 .SH
  31 For complete and current documentation, refer to the snacc manual.
  32 .I
  33 .SH DESCRIPTION
  34 Snacc (Sample Neufeld Asn.1 to C/C++ Compiler) generates C or C++
  35 source code for BER encode and decode routines as well as print and
  36 free routines for each type in the given ASN.1 modules.
  37 Alternatively, snacc can produce type tables that can be used for
  38 table based/interpreted encoding and decoding.  The type table based
  39 methods tend to be slower than their C or C++ counterparts but they
  40 usually use less memory (table size vs. C/C++ object code).
  41
  42 Most of the 1990 ASN.1 features are parsed although some do not affect
  43 the generated code.  Fairly rigourous error checking is performed on
  44 the ASN.1 source; any errors detected will be reported (printed to
  45 stderr).
  46
  47 Each file in the ASN.1 file list should contain a complete ASN.1
  48 module.  ASN.1 modules that use the IMPORTS feature must be compiled
  49 together (specify all necessary modules in the ASN.1 file list).  The
  50 generated source files will include each module's header file in the
  51 command line order.  This makes it important to order the modules from
  52 least dependent to most dependent on the command line to avoid type
  53 ordering problems. Currently, snacc assumes that each ASN.1 file
  54 given on the command line depends on all of the others on the command
  55 line.  No attempt is made to only include the header files from
  56 modules referenced in the import list for that module.
  57
  58 If the target language is C, snacc will generate a \c
  59 .B .h
  60 and
  61 .B .c
  62 file for each specified ASN.1 module.  If the target language is C++,
  63 snacc will generate a
  64 .B .h
  65 and
  66 .B .C
  67 file for each module.  The generated file names will be derived from the
  68 module names.
  69
  70 .SH OPTIONS
  71
  72 .TP
  73 .B \-h
  74 Help. Prints a synopsis of snacc and exits.
  75 .TP
  76 .B \-c
  77 Generate C source code.  This is the default behaviour of snacc.
  78 Only one of \c
  79 .B \-c
  80 ,
  81 .B \-C
  82 or
  83 .B \-T
  84 should be specified.
  85 .TP
  86 .B \-C
  87 Generate C++ source code.
  88 .TP
  89 .B \-novolat
  90 Generate ``return *this'' after calling ``abort()''.
  91 (Some broken compilers don't know about volatile functions, or their abort() isn't correctly typed.)
  92 .TP
  93 .B -meta
  94 Generate meta code that describes the generated types.
  95 Implies -C.
  96 .TP
  97 .B -tcl
  98 .IR module.type [, module.type ]
  99 Generate code for a Tcl interpreter where \fImodule.type\fP are the top level PDUs.
 100 Implies -meta.
 101 .TP
 102 .BI "\-T " file\c
 103 This causes snacc to generate type tables and write them to the given
 104 file.
 105 .TP
 106 .B \-P
 107 This causes snacc to print the parsed ASN.1 modules to stdout after
 108 the types have been linked, sorted, and processed.  This option is
 109 useful for debugging snacc and observing the modifications snacc
 110 performs on the types to make code generation simpler.
 111 .TP
 112 .B \-t
 113 Generate type definitions in the target language for each ASN.1 type.
 114 .TP
 115 .B \-v
 116 Generate value definitions in the target language for each ASN.1 value.
 117 Currently value definitions are limited to INTEGERs, BOOLEANs and
 118 OBJECT IDENTIFIERs.
 119 .TP
 120 .B \-e
 121 Generate encode routines in the target language for each ASN.1 type.
 122 .TP
 123 .B \-d
 124 Generate decode routines in the target language for each ASN.1 type.
 125 .TP
 126 .B \-p
 127 Generate print routines in the target language for each ASN.1 type.
 128 .TP
 129 .B \-f
 130 Generate free routines in the target language for each ASN.1 type.
 131 This option only works when the target language is C.
 132
 133 If none of the
 134 .B \-t, \-v, \-e, \-d, \-p, or \-f
 135 options are given on
 136 the command line, snacc assumes that all of them are in effect.
 137 They do not affect type table generation.
 138 .TP
 139 .BI "\-u " file\c
 140 \&Read the useful types definitions from the ASN.1 module in file \c
 141 .I file\c
 142 \& for linking purposes.  For some ASN.1 specifications, such as SNMP,
 143 the useful types are not needed. The types in the given useful types
 144 file are globally available to all modules; a useful type definition
 145 is overridden by a local or explicitly imported type with the same
 146 name.  The current list of useful types is:
 147 .RS 9
 148 ObjectDecscriptor
 149 .br
 150 NumericString
 151 .br
 152 PrintableString
 153 .br
 154 TeletexString
 155 .br
 156 T61String
 157 .br
 158 VideoTexString
 159 .br
 160 IA5String
 161 .br
 162 GraphicString
 163 .br
 164 ISO646String
 165 .br
 166 GeneralString
 167 .br
 168 UTCTime
 169 .br
 170 GeneralizedTime
 171 .br
 172 EXTERNAL
 173 .RE
 174 .TP
 175 .BI "\-mf " number\c
 176 \&This causes the generated source files to have a
 177 maximum length of \c
 178 .I number\c
 179  characters, including their suffix.  The \c
 180 .I number\c
 181  must be at least 3.  This option is useful for supporting operating
 182 systems that only support short file names.  A better solution is to
 183 shorten the module name of each ASN.1 module.
 184
 185 .TP
 186 .BI "\-l " number\c
 187 \&This is fairly obscure but may be useful.  Each error that the
 188 decoders can report is given an id number.  The number \c
 189 .I number\c
 190  is where the error ids start decreasing from as they are assigned to
 191 errors .  The default is -100 if this option is not given.  Avoid
 192 using a number in the range -100 to 0 since they may conflict with the
 193 library routines' error ids.  If you are re-compiling the useful types
 194 for the library use -50.  Another use of this option is to integrate
 195 newly generated code with older code; if done correctly, the error ids
 196 will not conflict.
 197
 198 .PP
 199 .\" there is a tab between the file name and the description
 200 .SH FILES
 201 .PD 0
 202 .TP 28
 203 .B snacc/asn1specs/asn-useful.asn1
 204 ASN.1 useful types module (use with \-u option)
 205 .TP
 206 .B snacc/c-lib/inc/
 207 C runtime library include files
 208 .TP
 209 .B snacc/c-lib/libasn1csbuf.a
 210 C SBuf runtime library
 211 .TP
 212 .B snacc/c-lib/libasn1cmbuf.a
 213 C MinBuf runtime library
 214 .TP
 215 .B snacc/c-lib/libasn1cebuf.a
 216 C ExpBuf runtime library
 217 .TP
 218 .B snacc/c++-lib/inc/
 219 C++ runtime library include files
 220 .TP
 221 .B snacc/c++-lib/libasn1c++.a
 222 C++ runtime library
 223 .TP
 224 .B snacc/c-lib/inc/tbl*/
 225 Type table runtime library include files
 226 .TP
 227 .B snacc/c-lib/libasn1ctbl.a
 228 Type table runtime library
 229 .TP
 230 .B snacc/tbl-tools/
 231 Source code for table based tools (mkchdr, ptbl, pval)
 232 .TP
 233 .B snacc/c-examples/
 234 directory with ASN.1 to C examples
 235 .TP
 236 .B snacc/c++-examples/
 237 directory with ASN.1 to C++ examples
 238 .TP
 239 .B snacc/tbl-example
 240 directory with an ASN.1 to type table example
 241 .TP
 242 .B snacc/doc
 243 directory with snacc documentation and this man page
 244 .PD
 245 .SH BUGS
 246 Snacc has problems with the following case:
 247 .RS
 248 .nf
 249
 250 Foo ::= SEQUENCE
 251 {
 252     id IdType,
 253     val ANY DEFINED BY id
 254 }
 255
 256 IdType ::= CHOICE
 257 {
 258     a INTEGER,
 259     b OBJECT IDENTIFIER
 260 }
 261
 262 .fi
 263 .RE
 264 The error checking pass will print an error to the effect that the id
 265 type must be INTEGER or OBJECT IDENTIFER.  To fix this you must modify
 266 the error checking pass as well as the code generation pass.  To be
 267 cheap about it, disable/fix the error checking and hand modify the
 268 generated code.
 269
 270 The hashing code used for handling ANY DEFINED BY id to type mappings
 271 will encounter problems if the hash table goes more than four levels
 272 deep (I think this is unlikely).  To fix this just add linear chaining
 273 at fourth level.
 274
 275 Please send bug reports or comments to
 276 .\".BR snacc-bugs@cs.ubc.ca .
 277 .BR "Robert Joop <rj@rainbow.in-berlin.de>" .
 278 See the documentation about reporting bugs and (lack of) support.
 279 .SH COPYING
 280 Copyright (c) 1993 Mike Sample and the University of British Columbia
 281 .br
 282 Copyright (c) 1994 1995 Robert Joop and GMD Fokus.
 283 .PP
 284 Permission is granted to make and distribute verbatim copies of
 285 this manual provided the copyright notice and this permission notice
 286 are preserved on all copies.
 287 .PP
 288 Permission is granted to copy and distribute modified versions of this
 289 manual under the conditions for verbatim copying, provided that the
 290 entire resulting derived work is distributed under the terms of a
 291 permission notice identical to this one.
 292 .PP
 293 The snacc compiler is released under the GNU General Public License.
 294 The runtime libraries are no longer under the GNU Library General
 295 Public License.  The generated code is yours.
 296 .SH AUTHOR
 297 Snacc was written by Mike Sample at the University of British Columbia
 298 (UBC).  He used it as a tool to do encoding/decoding performance
 299 research.
 300 .PP
 301 It was augmented by Robert Joop at GMD Fokus with the help of some of its project partners.
 302 .SH ACKNOWLEDGEMENTS
 303 This work was made possible by grants from the Canadian Institute for
 304 Telecommunications Research (CITR) and Natural Sciences and
 305 Engineering Research Council of Canada (NSERC).