doc/man/asn1c.1

   1 .\"t
   2 .\" Automatically generated by Pandoc 1.19.2.1
   3 .\"
   4 .ad l
   5 .TH "asn1c" "1" "2017\-09\-01" "ASN.1 Compiler" "Version 0.9.29"
   6 .nh \" Turn off hyphenation by default.
   7 .SH NAME
   8 .PP
   9 asn1c \-\- the ASN.1 Compiler
  10 .SH SYNOPSIS
  11 .PP
  12 asn1c [\f[B]\-E\f[] [\f[B]\-F\f[]] | \f[B]\-P\f[] | \f[B]\-R\f[]]
  13 .PD 0
  14 .P
  15 .PD
  16 [\f[B]\-S\f[]\f[I]dir\f[]] [\f[B]\-X\f[]]
  17 .PD 0
  18 .P
  19 .PD
  20 [\f[B]\-W\f[]\f[I]debug\-\f[]...] [\f[B]\-f\f[]\f[I]option\f[]]
  21 [\f[B]\-gen\-\f[]\f[I]option\f[]]
  22 [\f[B]\-pdu\f[]={\f[B]all\f[]|\f[B]auto\f[]|\f[I]Type\f[]}]
  23 .PD 0
  24 .P
  25 .PD
  26 [\f[B]\-print\-\f[]\f[I]option\f[]]
  27 .PD 0
  28 .P
  29 .PD
  30 \f[I]input\-filenames\f[]...
  31 .SH DESCRIPTION
  32 .PP
  33 asn1c compiles ASN.1 specifications into a set of target language
  34 (C/C++) encoders and decoders for BER, DER, PER, XER, OER and other
  35 encoding rules.
  36 .SH OPTIONS
  37 .SS Stage Selection Options
  38 .TP
  39 .B \-E
  40 Run the parsing stage only.
  41 Print the reconstructed ASN.1 text.
  42 .RS
  43 .RE
  44 .TP
  45 .B \-F
  46 Used together with \f[B]\-E\f[], instructs the compiler to stop after
  47 the ASN.1 syntax tree fixing stage and dump the reconstructed ASN.1
  48 specification to the standard output.
  49 .RS
  50 .RE
  51 .TP
  52 .B \-P
  53 Dump the compiled output to the standard output instead of creating the
  54 target language files on disk.
  55 .RS
  56 .RE
  57 .TP
  58 .B \-R
  59 Restrict the compiler to generate only the ASN.1 tables, omitting the
  60 usual support code.
  61 .RS
  62 .RE
  63 .TP
  64 .B \-S \f[I]directory\f[]
  65 Use the specified directory with ASN.1 skeleton files.
  66 .RS
  67 .RE
  68 .TP
  69 .B \-X
  70 Generate an XML DTD schema for the specified ASN.1 files.
  71 .RS
  72 .RE
  73 .SS Warning Options
  74 .TP
  75 .B \-Werror
  76 Treat warnings as errors; abort if any warning is produced.
  77 .RS
  78 .RE
  79 .TP
  80 .B \-Wdebug\-lexer
  81 Enable lexer debugging during the ASN.1 lexing stage.
  82 .RS
  83 .RE
  84 .TP
  85 .B \-Wdebug\-parser
  86 Enable lexer debugging during the ASN.1 parsing stage.
  87 .RS
  88 .RE
  89 .TP
  90 .B \-Wdebug\-fixer
  91 Enable ASN.1 syntax tree fixer debugging during the fixing stage.
  92 .RS
  93 .RE
  94 .TP
  95 .B \-Wdebug\-compiler
  96 Enable debugging during the actual compile time.
  97 .RS
  98 .RE
  99 .SS Language Options
 100 .TP
 101 .B \-fbless\-SIZE
 102 Allow \f[C]SIZE()\f[] constraint for \f[C]INTEGER\f[],
 103 \f[C]ENUMERATED\f[], and other types for which this constraint is
 104 normally prohibited by the standard.
 105 This is a violation of ASN.1 standard, and the compiler may fail to
 106 produce a meaningful code.
 107 .RS
 108 .RE
 109 .TP
 110 .B \-fcompound\-names
 111 Using this option prevents name collisions in the target source code by
 112 using complex names for target language structures.
 113 (Name collisions may occur if the ASN.1 module reuses the same
 114 identifiers in multiple contexts).
 115 .RS
 116 .RE
 117 .TP
 118 .B \-findirect\-choice
 119 When generating code for a \f[C]CHOICE\f[] type, compile the
 120 \f[C]CHOICE\f[] members as indirect pointers instead of declaring them
 121 inline.
 122 Consider using this option together with \f[B]\-fno\-include\-deps\f[]
 123 to prevent circular references.
 124 .RS
 125 .RE
 126 .TP
 127 .B \-fincludes\-quoted
 128 Refer to header files in \f[C]#include\f[]s using
 129 \f[B]"\f[]double\f[B]"\f[] instead of \f[B]<\f[]angle\f[B]>\f[] quotes.
 130 .RS
 131 .RE
 132 .TP
 133 .B \-fknown\-extern\-type=\f[I]name\f[]
 134 Pretend the specified type is known.
 135 The compiler will assume the target language source files for the given
 136 type have been provided manually.
 137 .RS
 138 .RE
 139 .TP
 140 .B \-fline\-refs
 141 Include ASN.1 module\[aq]s line numbers in generated code comments.
 142 .RS
 143 .RE
 144 .TP
 145 .B \-fno\-constraints
 146 Do not generate ASN.1 subtype constraint checking code.
 147 This may make a shorter executable.
 148 .RS
 149 .RE
 150 .TP
 151 .B \-fno\-include\-deps
 152 Do not generate courtesy #include lines for non\-critical type
 153 dependencies.
 154 Helps prevent namespace collisions.
 155 .RS
 156 .RE
 157 .TP
 158 .B \-funnamed\-unions
 159 Enable unnamed unions in the definitions of target language\[aq]s
 160 structures.
 161 .RS
 162 .RE
 163 .TP
 164 .B \-fwide\-types
 165 Use the unbounded size data types (\f[C]INTEGER_t\f[],
 166 \f[C]ENUMERATED_t\f[], \f[C]REAL_t\f[]) by default, instead of using the
 167 native machine\[aq]s data types (long, double).
 168 .RS
 169 .RE
 170 .SS Codecs Generation Options
 171 .TP
 172 .B \-gen\-OER
 173 Generate the Octet Encoding Rules (OER) support code.
 174 .RS
 175 .RE
 176 .TP
 177 .B \-gen\-PER
 178 Generate the Packed Encoding Rules (PER) support code.
 179 .RS
 180 .RE
 181 .TP
 182 .B \-pdu={all|auto|\f[I]Type\f[]}
 183 Create a PDU table for specified types, or discover Protocol Data Units
 184 automatically.
 185 In case of \f[B]\-pdu=all\f[], all ASN.1 types defined in all modules
 186 will form a PDU table.
 187 In case of \f[B]\-pdu=auto\f[], all types not referenced by any other
 188 type will form a PDU table.
 189 If \f[I]Type\f[] is an ASN.1 type identifier, the identifier is added to
 190 the generated PDU table.
 191 The last form may be specified multiple times to add any number of PDUs.
 192 .RS
 193 .RE
 194 .SS Output Options
 195 .TP
 196 .B \-print\-constraints
 197 When \f[B]\-EF\f[] options are also specified, this option forces the
 198 compiler to explain its internal understanding of subtype constraints.
 199 .RS
 200 .RE
 201 .TP
 202 .B \-print\-lines
 203 Generate "\f[C]\-\-\ #line\f[]" comments in \f[B]\-E\f[] output.
 204 .RS
 205 .RE
 206 .SH TRANSFER SYNTAXES
 207 .PP
 208 The ASN.1 family of standards define a number of ways to encode data,
 209 including byte\-oriented (e.g., BER), bit\-oriented (e.g., PER), and
 210 textual (e.g., XER).
 211 Some encoding variants (e.g., DER) are just stricter variants of the
 212 more general encodings (e.g., BER).
 213 .PP
 214 The interoperability table below specifies which API functions can be
 215 used to exchange data in a compatible manner.
 216 If you need to \f[I]produce\f[] data conforming to the standard
 217 specified in the column 1, use the API function in the column 2.
 218 If you need to \f[I]process\f[] data conforming to the standard(s)
 219 specified in the column 3, use the API function specified in column 4.
 220 See the \f[C]asn1c\-usage.pdf\f[] for details.
 221 .PP
 222 .TS
 223 tab(@);
 224 lw(14.6n) lw(18.5n) lw(13.6n) lw(13.6n).
 225 T{
 226 Encoding
 227 T}@T{
 228 API function
 229 T}@T{
 230 Understood by
 231 T}@T{
 232 API function
 233 T}
 234 _
 235 T{
 236 BER
 237 T}@T{
 238 der_encode()
 239 T}@T{
 240 BER
 241 T}@T{
 242 ber_decode()
 243 T}
 244 T{
 245 DER
 246 T}@T{
 247 der_encode()
 248 T}@T{
 249 DER, BER
 250 T}@T{
 251 ber_decode()
 252 T}
 253 T{
 254 CER
 255 T}@T{
 256 \f[I]not supported\f[]
 257 T}@T{
 258 CER, BER
 259 T}@T{
 260 ber_decode()
 261 T}
 262 T{
 263 BASIC\-OER
 264 T}@T{
 265 oer_encode()
 266 T}@T{
 267 *\-OER
 268 T}@T{
 269 oer_decode()
 270 T}
 271 T{
 272 CANONICAL\-OER
 273 T}@T{
 274 oer_encode()
 275 T}@T{
 276 *\-OER
 277 T}@T{
 278 oer_decode()
 279 T}
 280 T{
 281 BASIC\-UPER
 282 T}@T{
 283 uper_encode()
 284 T}@T{
 285 *\-UPER
 286 T}@T{
 287 uper_decode()
 288 T}
 289 T{
 290 CANONICAL\-UPER
 291 T}@T{
 292 uper_encode()
 293 T}@T{
 294 *\-UPER
 295 T}@T{
 296 uper_decode()
 297 T}
 298 T{
 299 *\-APER
 300 T}@T{
 301 \f[I]not supported\f[]
 302 T}@T{
 303 *\-APER
 304 T}@T{
 305 \f[I]not supported\f[]
 306 T}
 307 T{
 308 BASIC\-XER
 309 T}@T{
 310 xer_encode(...)
 311 T}@T{
 312 *\-XER
 313 T}@T{
 314 xer_decode()
 315 T}
 316 T{
 317 CANONICAL\-XER
 318 T}@T{
 319 xer_encode (XER_F_CANONICAL)
 320 T}@T{
 321 *\-XER
 322 T}@T{
 323 xer_decode()
 324 T}
 325 .TE
 326 .PP
 327 *) Asterisk means both BASIC and CANONICAL variants.
 328 .SH SEE ALSO
 329 .PP
 330 \f[C]unber\f[](1), \f[C]enber\f[](1).
 331 .SH AUTHORS
 332 Lev Walkin <vlm@lionet.info>.