1asn1ct(3)                  Erlang Module Definition                  asn1ct(3)
2
3
4

NAME

6       asn1ct - ASN.1 compiler and compile-time support functions
7

DESCRIPTION

9       The  ASN.1 compiler takes an ASN.1 module as input and generates a cor‐
10       responding Erlang module, which can encode  and  decode  the  specified
11       data  types.  Alternatively,  the compiler takes a specification module
12       specifying all input modules, and generates a module with encode/decode
13       functions.  In  addition, some generic functions can be used during de‐
14       velopment of applications that handles ASN.1 data (encoded  as  BER  or
15       PER).
16
17   Note:
18       By  default  in  OTP 17, the representation of the BIT STRING and OCTET
19       STRING types as Erlang terms were changed. BIT STRING  values  are  now
20       Erlang bit strings and OCTET STRING values are binaries. Also, an unde‐
21       coded open type is now wrapped in an asn1_OPENTYPE tuple. For  details,
22       see  BIT  STRING,  OCTET  STRING,  and ASN.1 Information Objects in the
23       User's Guide.
24
25       To revert to the old representation of the types, use option legacy_er‐
26       lang_types.
27
28
29   Note:
30       In  OTP  R16, the options were simplified. The back end is chosen using
31       one of the options ber, per, uper or jer. Options  optimize,  nif,  and
32       driver  options  are no longer necessary (and the ASN.1 compiler gener‐
33       ates a warning  if  they  are  used).  Options  ber_bin,  per_bin,  and
34       uper_bin options still work, but generates a warning.
35
36       Another  change  in OTP R16 is that the generated function encode/2 al‐
37       ways returns a binary. Function encode/2 for the BER back end  used  to
38       return an iolist.
39
40

EXPORTS

42       compile(Asn1module) -> ok | {error, Reason}
43       compile(Asn1module, Options) -> ok | {error, Reason}
44
45              Types:
46
47                 Asn1module = atom() | string()
48                 Options = [Option| OldOption]
49                 Option  = ber | per | uper | jer | der | compact_bit_string |
50                 legacy_bit_string | legacy_erlang_types | noobj | {n2n, Enum‐
51                 TypeName} |{outdir, Dir} | {i, IncludeDir} | asn1config | un‐
52                 dec_rest |  no_ok_wrapper  |  {macro_name_prefix,  Prefix}  |
53                 {record_name_prefix, Prefix} | verbose | warnings_as_errors
54                 OldOption = ber | per
55                 Reason = term()
56                 Prefix = string()
57
58              Compiles  the  ASN.1  module  Asn1module and generates an Erlang
59              module Asn1module.erl with encode and decode functions  for  the
60              types defined in Asn1module. For each ASN.1 value defined in the
61              module, an Erlang function that returns the value in Erlang rep‐
62              resentation is generated.
63
64              If  Asn1module is a filename without extension, first ".asn1" is
65              assumed, then ".asn", and finally ".py" (to be  compatible  with
66              the old ASN.1 compiler). Asn1module can be a full pathname (rel‐
67              ative or absolute) including filename with (or  without)  exten‐
68              sion.
69
70              If it is needed to compile a set of ASN.1 modules into an Erlang
71              file with encode/decode functions, ensure to list  all  involved
72              files in a configuration file. This configuration file must have
73              a double  extension  ".set.asn"  (".asn"  can  alternatively  be
74              ".asn1"  or  ".py").  List the input file names within quotation
75              marks (""), one at each row in the file. If the input files  are
76              File1.asn, File2.asn, and File3.asn, the configuration file must
77              look as follows:
78
79              File1.asn
80              File2.asn
81              File3.asn
82
83              The output files in this case get their names from the  configu‐
84              ration   file.   If  the  configuration  file  is  named  SetOf‐
85              Files.set.asn, the names of the output files are SetOfFiles.hrl,
86              SetOfFiles.erl, and SetOfFiles.asn1db.
87
88              Sometimes  in  a  system of ASN.1 modules, different default tag
89              modes, for example, AUTOMATIC, IMPLICIT, or EXPLICIT. The multi-
90              file  compilation resolves the default tagging as if the modules
91              were compiled separately.
92
93              Name collisions is another unwanted effect  that  can  occur  in
94              multi  file-compilation. The compiler solves this problem in one
95              of two ways:
96
97                * If the definitions are identical, the  output  module  keeps
98                  only one definition with the original name.
99
100                * If  the  definitions  have  the same name and differs in the
101                  definition, they are renamed. The new names are the  defini‐
102                  tion name and the original module name concatenated.
103
104              If a name collision occurs, the compiler reports a "NOTICE: ..."
105              message that tells if a definition was renamed, and the new name
106              that must be used to encode/decode data.
107
108              Options  is  a list with options specific for the ASN.1 compiler
109              and options that are applied to the Erlang compiler. The  latter
110              are  not recognized as ASN.1 specific. The available options are
111              as follows:
112
113                ber | per | uper | jer:
114                  The encoding rule to be used. The supported  encoding  rules
115                  are  Basic Encoding Rules (ber), Packed Encoding Rules (per)
116                  aligned, PER unaligned (uper) and JSON Encoding Rules (jer).
117                  The  jer  option  can be used by itself to generate a module
118                  that only supports encoding/decoding to JER  or  it  can  be
119                  used  as a supplementary option to ber, per and uper. In the
120                  latter case a module with for both the main  encoding  rules
121                  and  JER  will  be generated. The exported functions for JER
122                  will then be jer_encode(Type,  Value)  and  jer_decode(Type,
123                  Bytes).
124
125                  The jer encoding rules (ITU-T X.697) are experimental in OTP
126                  22. There is support for a subset of the X.697 standard, for
127                  example there is no support for:
128
129                  * JER encoding instructions
130
131                  * the REAL type
132
133                  Also  note that when using the jer encoding rules the gener‐
134                  ated module will get a dependency to an external json compo‐
135                  nent. The generated code is currently tested together with:
136
137                  * jsx which currently is the default.
138
139                  * jsone can be chosen instead of jsx by providing the option
140                    {d,jsone}.
141
142                  If the encoding rule option is omitted, ber is the default.
143
144                  The generated Erlang module always gets the same name as the
145                  ASN.1  module.  Therefore,  only one encoding rule per ASN.1
146                  module can be used at runtime.
147
148                der:
149                  With this option the Distinguished Encoding Rules  (der)  is
150                  chosen.  DER is regarded as a specialized variant of the BER
151                  encoding rule. Therefore, this option only makes  sense  to‐
152                  gether  with  option ber. This option sometimes adds sorting
153                  and value checks when encoding, which implies a  slower  en‐
154                  coding. The decoding routines are the same as for ber.
155
156                maps:
157                  This option changes the representation of the types SEQUENCE
158                  and SET to use maps (instead of records). This  option  also
159                  suppresses the generation of .hrl files.
160
161                  For  details,  see  Section  Map representation for SEQUENCE
162                  and SET in the User's Guide.
163
164                compact_bit_string:
165                  The BIT STRING type is decoded to "compact  notation".  This
166                  option  is  not recommended for new code. This option cannot
167                  be combined with the option maps.
168
169                  For details, see Section  BIT STRING in the User's Guide.
170
171                  This option implies option legacy_erlang_types.
172
173                legacy_bit_string:
174                  The BIT STRING type is decoded to the  legacy  format,  that
175                  is,  a  list  of  zeroes and ones. This option is not recom‐
176                  mended for new code. This option cannot be combined with the
177                  option maps.
178
179                  For details, see Section BIT STRING in the User's Guide
180
181                  This option implies option legacy_erlang_types.
182
183                legacy_erlang_types:
184                  Use  the same Erlang types to represent BIT STRING and OCTET
185                  STRING as in OTP R16.
186
187                  For details, see Section BIT STRING and Section OCTET STRING
188                  in the User's Guide.
189
190                  This  option  is  not  recommended for new code. This option
191                  cannot be combined with the option maps.
192
193                {n2n, EnumTypeName}:
194                  Tells the compiler to generate functions for conversion  be‐
195                  tween  names  (as  atoms) and numbers and conversely for the
196                  specified EnumTypeName. There can be multiple occurrences of
197                  this  option  to  specify several type names. The type names
198                  must be declared as ENUMERATIONS in the ASN.1 specification.
199
200                  If EnumTypeName does not exist in the  ASN.1  specification,
201                  the compilation stops with an error code.
202
203                  The  generated conversion functions are named name2num_Enum‐
204                  TypeName/1 and num2name_EnumTypeName/1.
205
206                noobj:
207                  Do not compile (that is, do not  produce  object  code)  the
208                  generated  .erl  file. If this option is omitted, the gener‐
209                  ated Erlang module is compiled.
210
211                {i, IncludeDir}:
212                  Adds IncludeDir to the search-path  for  .asn1db  and  ASN.1
213                  source  files.  The  compiler  tries to open an .asn1db file
214                  when a module imports definitions from another ASN.1 module.
215                  If  no  .asn1db  file  is  found,  the  ASN.1 source file is
216                  parsed. Several {i, IncludeDir} can be given.
217
218                {outdir, Dir}:
219                  Specifies directory Dir where all generated files are to  be
220                  placed.  If  this option is omitted, the files are placed in
221                  the current directory.
222
223                asn1config:
224                  When using one of the specialized decodes, exclusive or  se‐
225                  lective  decode,  instructions must be given in a configura‐
226                  tion file. Option asn1config enables specialized decodes and
227                  takes  the  configuration file in concern. The configuration
228                  file has the same name as the ASN.1 specification, but  with
229                  extension .asn1config.
230
231                  For instructions for exclusive decode, see Section Exclusive
232                  Decode in the User's Guide.
233
234                  For instructions for selective decode, see Section Selective
235                  Decode in the User's Guide.
236
237                undec_rest:
238                  A  buffer  that  holds  a message, being decoded it can also
239                  have some following bytes. Those following bytes can now  be
240                  returned together with the decoded value. If an ASN.1 speci‐
241                  fication is compiled with this option, a tuple  {ok,  Value,
242                  Rest}  is  returned. Rest can be a list or a binary. Earlier
243                  versions of the compiler ignored those following bytes.
244
245                no_ok_wrapper:
246                  With this option, the generated encode/2 and decode/2  func‐
247                  tions  do  not wrap a successful return value in an {ok,...}
248                  tuple. If any error occurs, an exception will be raised.
249
250                {macro_name_prefix, Prefix}:
251                  All macro names generated by the compiler are prefixed  with
252                  Prefix.  This is useful when multiple protocols that contain
253                  macros with identical names are included in a single module.
254
255                {record_name_prefix, Prefix}:
256                  All record names generated by the compiler are prefixed with
257                  Prefix.  This is useful when multiple protocols that contain
258                  records with identical names are included in a  single  mod‐
259                  ule.
260
261                verbose:
262                  Causes more verbose information from the compiler describing
263                  what it is doing.
264
265                warnings_as_errors:
266                  Causes warnings to be treated as errors.
267
268              Any more option that is applied is passed to the final step when
269              the generated .erl file is compiled.
270
271              The compiler generates the following files:
272
273                * Asn1module.hrl (if any SET or SEQUENCE is defined)
274
275                * Asn1module.erl  -  Erlang  module  with  encode, decode, and
276                  value functions
277
278                * Asn1module.asn1db - Intermediate format used by the compiler
279                  when modules IMPORT definitions from each other.
280
281       value(Module, Type) -> {ok, Value} | {error, Reason}
282
283              Types:
284
285                 Module = Type = atom()
286                 Value = term()
287                 Reason = term()
288
289              Returns an Erlang term that is an example of a valid Erlang rep‐
290              resentation of a value of the ASN.1 type Type. The  value  is  a
291              random value and subsequent calls to this function will for most
292              types return different values.
293
294          Note:
295              Currently, the value function has many limitations. Essentially,
296              it  will  mostly  work  for old specifications based on the 1997
297              standard for ASN.1, but not for most modern-style  applications.
298              Another  limitation  is  that the value function may not work if
299              options that change code generations strategies such as the  op‐
300              tions macro_name_prefix and record_name_prefix have been used.
301
302
303       test(Module) -> ok | {error, Reason}
304       test(Module, Type | Options) -> ok | {error, Reason}
305       test(Module, Type, Value | Options) -> ok | {error, Reason}
306
307              Types:
308
309                 Module = Type = atom()
310                 Value = term()
311                 Options = [{i, IncludeDir}]
312                 Reason = term()
313
314              Performs  a  test  of  encode and decode of types in Module. The
315              generated functions are called by this function.  This  function
316              is  useful  during  test to secure that the generated encode and
317              decode functions as well as the general runtime support work  as
318              expected.
319
320          Note:
321              Currently,  the  test  functions  have  many limitations. Essen‐
322              tially, they will mostly work for old  specifications  based  on
323              the  1997  standard for ASN.1, but not for most modern-style ap‐
324              plications. Another limitation is that the  test  functions  may
325              not work if options that change code generations strategies such
326              as the options  macro_name_prefix  and  record_name_prefix  have
327              been used.
328
329
330                * test/1 iterates over all types in Module.
331
332                * test/2 tests type Type with a random value.
333
334                * test/3 tests type Type with Value.
335
336              Schematically, the following occurs for each type in the module:
337
338              {ok, Value} = asn1ct:value(Module, Type),
339              {ok, Bytes} = Module:encode(Type, Value),
340              {ok, Value} = Module:decode(Type, Bytes).
341
342              The  test functions use the *.asn1db files for all included mod‐
343              ules. If they are located in a different directory than the cur‐
344              rent  working  directory,  use  the include option to add paths.
345              This is only needed when automatically  generating  values.  For
346              static values using Value no options are needed.
347
348
349
350Ericsson AB                       asn1 5.0.17                        asn1ct(3)
Impressum