doc/man/asn1c.man.md

   1 % asn1c(1) ASN.1 Compiler
   2 % Lev Walkin <vlm@lionet.info>
   3 % 2017-09-01
   4
   5 # NAME
   6
   7 asn1c -- the ASN.1 Compiler
   8
   9 # SYNOPSIS
  10
  11 asn1c [**-E** [**-F**] | **-P** | **-R**] \
  12       [**-S***dir*] [**-X**] \
  13       [**-W***debug-*...] [**-f***option*] [**-gen-***option*]
  14       [**-pdu**={**all**|**auto**|*Type*}] \
  15       [**-print-***option*] \
  16       *input-filenames*...
  17
  18 # DESCRIPTION
  19
  20 asn1c compiles ASN.1 specifications into a set of
  21 target language (C/C++) encoders and decoders for BER, DER, PER, XER, OER
  22 and other encoding rules.
  23
  24 # OPTIONS
  25
  26 ## Stage Selection Options
  27
  28 -E
  29 :   Run the parsing stage only. Print the reconstructed ASN.1 text.
  30
  31 -F
  32 :   Used together with **-E**,
  33     instructs the compiler to stop after the ASN.1 syntax
  34     tree fixing stage and dump the reconstructed ASN.1 specification
  35     to the standard output.
  36
  37 -P
  38 :   Dump the compiled output to the standard output instead of creating the
  39     target language files on disk.
  40
  41 -R
  42 :   Restrict the compiler to generate only the ASN.1 tables,
  43     omitting the usual support code.
  44
  45 -S *directory*
  46 :   Use the specified directory with ASN.1 skeleton files.
  47
  48 -X
  49 :   Generate an XML DTD schema for the specified ASN.1 files.
  50
  51 ## Warning Options
  52
  53 -Werror
  54 :   Treat warnings as errors; abort if any warning is produced.
  55
  56 -Wdebug-lexer
  57 :   Enable lexer debugging during the ASN.1 lexing stage.
  58
  59 -Wdebug-parser
  60 :   Enable lexer debugging during the ASN.1 parsing stage.
  61
  62 -Wdebug-fixer
  63 :   Enable ASN.1 syntax tree fixer debugging during the fixing stage.
  64
  65 -Wdebug-compiler
  66 :   Enable debugging during the actual compile time.
  67
  68 ## Language Options
  69
  70 -fbless-SIZE
  71 :   Allow `SIZE()` constraint for `INTEGER`, `ENUMERATED`,
  72     and other types for which this constraint is normally prohibited
  73     by the standard.
  74     This is a violation of ASN.1 standard, and the compiler may
  75     fail to produce a meaningful code.
  76
  77 -fcompound-names
  78 :   Using this option prevents name collisions in the target source code
  79     by using complex names for target language structures.
  80     (Name collisions may occur if the ASN.1 module reuses the same identifiers
  81     in multiple contexts).
  82
  83 -findirect-choice
  84 :   When generating code for a `CHOICE` type, compile the `CHOICE` members
  85     as indirect pointers instead of declaring them inline.
  86     Consider using this option together with **-fno-include-deps**
  87     to prevent circular references.
  88
  89 -fincludes-quoted
  90 :   Refer to header files in `#include`s using **"**double**"** instead of **\<**angle**>** quotes.
  91
  92 -fknown-extern-type=*name*
  93 :   Pretend the specified type is known.
  94     The compiler will assume the target language source files
  95     for the given type have been provided manually.
  96
  97 -fline-refs
  98 :   Include ASN.1 module's line numbers in generated code comments.
  99
 100 -fno-constraints
 101 :   Do not generate ASN.1 subtype constraint checking code.
 102     This may make a shorter executable.
 103
 104 -fno-include-deps
 105 :   Do not generate courtesy #include lines for non-critical type dependencies.
 106     Helps prevent namespace collisions.
 107
 108 -funnamed-unions
 109 :   Enable unnamed unions in the definitions of target language's structures.
 110
 111 -fwide-types
 112 :   Use the unbounded size data types (`INTEGER_t`, `ENUMERATED_t`, `REAL_t`)
 113     by default, instead of using the native machine's data types (long, double).
 114
 115 ## Codecs Generation Options
 116
 117 -gen-OER
 118 :   Generate the Octet Encoding Rules (OER) support code.
 119
 120 -gen-PER
 121 :   Generate the Packed Encoding Rules (PER) support code.
 122
 123 -pdu={all|auto|*Type*}
 124 :   Create a PDU table for specified types, or discover Protocol Data Units
 125     automatically. In case of **-pdu=all**,
 126     all ASN.1 types defined in all modules will form a PDU table.
 127     In case of **-pdu=auto**, all types not referenced by any other type will
 128     form a PDU table.
 129     If *Type* is an ASN.1 type identifier, the identifier is added to
 130     the generated PDU table.
 131     The last form may be specified multiple times to add any number of PDUs.
 132
 133 ## Output Options
 134
 135 -print-constraints
 136 :   When **-EF** options are also specified,
 137     this option forces the compiler to explain its internal understanding
 138     of subtype constraints.
 139
 140 -print-lines
 141 :   Generate "`-- #line`" comments in **-E** output.
 142
 143 # TRANSFER SYNTAXES
 144
 145 The ASN.1 family of standards define a number of ways to encode data,
 146 including byte-oriented (e.g., BER), bit-oriented (e.g., PER),
 147 and textual (e.g., XER). Some encoding variants (e.g., DER) are just stricter
 148 variants of the more general encodings (e.g., BER).
 149
 150 The interoperability table below specifies which API functions can be used
 151 to exchange data in a compatible manner. If you need to _produce_ data
 152 conforming to the standard specified in the column 1,
 153 use the API function in the column 2.
 154 If you need to _process_ data conforming to the standard(s) specified in the
 155 column 3, use the API function specified in column 4.
 156 See the `asn1c-usage.pdf` for details.
 157
 158 -------------------------------------------------------------
 159 Encoding       API function       Understood by API function
 160 -------------- ------------------ ------------- -------------
 161 BER            der_encode()       BER           ber_decode()
 162
 163 DER            der_encode()       DER, BER      ber_decode()
 164
 165 CER            _not supported_    CER, BER      ber_decode()
 166
 167 BASIC-OER      oer_encode()       *-OER         oer_decode()
 168
 169 CANONICAL-OER  oer_encode()       *-OER         oer_decode()
 170
 171 BASIC-UPER     uper_encode()      *-UPER        uper_decode()
 172
 173 CANONICAL-UPER uper_encode()      *-UPER        uper_decode()
 174
 175 *-APER         _not supported_    *-APER        _not supported_
 176
 177 BASIC-XER      xer_encode(...)    *-XER         xer_decode()
 178
 179 CANONICAL-XER  xer_encode         *-XER         xer_decode()
 180                (XER_F_CANONICAL)
 181 -------------------------------------------------------------
 182
 183 *) Asterisk means both BASIC and CANONICAL variants.
 184
 185
 186 # SEE ALSO
 187
 188 `unber`(1), `enber`(1).
 189