asn1ct(3)



asn1ct(3erl)               Erlang Module Definition               asn1ct(3erl)

NAME
       asn1ct - ASN.1 compiler and compile-time support functions

DESCRIPTION
       The  ASN.1 compiler takes an ASN.1 module as input and generates a cor-
       responding Erlang module, which can encode  and  decode  the  specified
       data  types.  Alternatively,  the compiler takes a specification module
       specifying all input modules, and generates a module with encode/decode
       functions.  In  addition, some generic functions can be used during de-
       velopment of applications that handles ASN.1 data (encoded  as  BER  or
       PER).

   Note:
       By  default  in  OTP 17, the representation of the BIT STRING and OCTET
       STRING types as Erlang terms were changed. BIT STRING  values  are  now
       Erlang bit strings and OCTET STRING values are binaries. Also, an unde-
       coded open type is now wrapped in an asn1_OPENTYPE tuple. For  details,
       see  BIT  STRING,  OCTET  STRING,  and ASN.1 Information Objects in the
       User's Guide.

       To revert to the old representation of the types, use option legacy_er-
       lang_types.

   Note:
       In  OTP  R16, the options were simplified. The back end is chosen using
       one of the options ber, per, uper or jer. Options  optimize,  nif,  and
       driver  options  are no longer necessary (and the ASN.1 compiler gener-
       ates a warning  if  they  are  used).  Options  ber_bin,  per_bin,  and
       uper_bin options still work, but generates a warning.

       Another  change  in OTP R16 is that the generated function encode/2 al-
       ways returns a binary. Function encode/2 for the BER back end  used  to
       return an iolist.

EXPORTS
       compile(Asn1module) -> ok | {error, Reason}
       compile(Asn1module, Options) -> ok | {error, Reason}

              Types:

                 Asn1module = atom() | string()
                 Options = [Option| OldOption]
                 Option  = ber | per | uper | jer | der | compact_bit_string |
                 legacy_bit_string | legacy_erlang_types | noobj | {n2n, Enum-
                 TypeName} |{outdir, Dir} | {i, IncludeDir} | asn1config | un-
                 dec_rest |  no_ok_wrapper  |  {macro_name_prefix,  Prefix}  |
                 {record_name_prefix, Prefix} | verbose | warnings_as_errors
                 OldOption = ber | per
                 Reason = term()
                 Prefix = string()

              Compiles  the  ASN.1  module  Asn1module and generates an Erlang
              module Asn1module.erl with encode and decode functions  for  the
              types defined in Asn1module. For each ASN.1 value defined in the
              module, an Erlang function that returns the value in Erlang rep-
              resentation is generated.

              If  Asn1module is a filename without extension, first ".asn1" is
              assumed, then ".asn", and finally ".py" (to be  compatible  with
              the old ASN.1 compiler). Asn1module can be a full pathname (rel-
              ative or absolute) including filename with (or  without)  exten-
              sion.

              If it is needed to compile a set of ASN.1 modules into an Erlang
              file with encode/decode functions, ensure to list  all  involved
              files in a configuration file. This configuration file must have
              a double  extension  ".set.asn"  (".asn"  can  alternatively  be
              ".asn1"  or  ".py").  List the input file names within quotation
              marks (""), one at each row in the file. If the input files  are
              File1.asn, File2.asn, and File3.asn, the configuration file must
              look as follows:

              File1.asn
              File2.asn
              File3.asn

              The output files in this case get their names from the  configu-
              ration   file.   If  the  configuration  file  is  named  SetOf-
              Files.set.asn, the names of the output files are SetOfFiles.hrl,
              SetOfFiles.erl, and SetOfFiles.asn1db.

              Sometimes  in  a  system of ASN.1 modules, different default tag
              modes, for example, AUTOMATIC, IMPLICIT, or EXPLICIT. The multi-
              file  compilation resolves the default tagging as if the modules
              were compiled separately.

              Name collisions is another unwanted effect  that  can  occur  in
              multi  file-compilation. The compiler solves this problem in one
              of two ways:

                * If the definitions are identical, the  output  module  keeps
                  only one definition with the original name.

                * If  the  definitions  have  the same name and differs in the
                  definition, they are renamed. The new names are the  defini-
                  tion name and the original module name concatenated.

              If a name collision occurs, the compiler reports a "NOTICE: ..."
              message that tells if a definition was renamed, and the new name
              that must be used to encode/decode data.

              Options  is  a list with options specific for the ASN.1 compiler
              and options that are applied to the Erlang compiler. The  latter
              are  not recognized as ASN.1 specific. The available options are
              as follows:

                ber | per | uper | jer:
                  The encoding rule to be used. The supported  encoding  rules
                  are  Basic Encoding Rules (ber), Packed Encoding Rules (per)
                  aligned, PER unaligned (uper) and JSON Encoding Rules (jer).
                  The  jer  option  can be used by itself to generate a module
                  that only supports encoding/decoding to JER  or  it  can  be
                  used  as a supplementary option to ber, per and uper. In the
                  latter case a module with for both the main  encoding  rules
                  and  JER  will  be generated. The exported functions for JER
                  will then be jer_encode(Type,  Value)  and  jer_decode(Type,
                  Bytes).

                  The jer encoding rules (ITU-T X.697) are experimental in OTP
                  22. There is support for a subset of the X.697 standard, for
                  example there is no support for:

                  * JER encoding instructions

                  * the REAL type

                  Also  note that when using the jer encoding rules the gener-
                  ated module will get a dependency to an external json compo-
                  nent. The generated code is currently tested together with:

                  * jsx which currently is the default.

                  * jsone can be chosen instead of jsx by providing the option
                    {d,jsone}.

                  If the encoding rule option is omitted, ber is the default.

                  The generated Erlang module always gets the same name as the
                  ASN.1  module.  Therefore,  only one encoding rule per ASN.1
                  module can be used at runtime.

                der:
                  With this option the Distinguished Encoding Rules  (der)  is
                  chosen.  DER is regarded as a specialized variant of the BER
                  encoding rule. Therefore, this option only makes  sense  to-
                  gether  with  option ber. This option sometimes adds sorting
                  and value checks when encoding, which implies a  slower  en-
                  coding. The decoding routines are the same as for ber.

                maps:
                  This option changes the representation of the types SEQUENCE
                  and SET to use maps (instead of records). This  option  also
                  suppresses the generation of .hrl files.

                  For  details,  see  Section  Map representation for SEQUENCE
                  and SET in the User's Guide.

                compact_bit_string:
                  The BIT STRING type is decoded to "compact  notation".  This
                  option  is  not recommended for new code. This option cannot
                  be combined with the option maps.

                  For details, see Section  BIT STRING in the User's Guide.

                  This option implies option legacy_erlang_types.

                legacy_bit_string:
                  The BIT STRING type is decoded to the  legacy  format,  that
                  is,  a  list  of  zeroes and ones. This option is not recom-
                  mended for new code. This option cannot be combined with the
                  option maps.

                  For details, see Section BIT STRING in the User's Guide

                  This option implies option legacy_erlang_types.

                legacy_erlang_types:
                  Use  the same Erlang types to represent BIT STRING and OCTET
                  STRING as in OTP R16.

                  For details, see Section BIT STRING and Section OCTET STRING
                  in the User's Guide.

                  This  option  is  not  recommended for new code. This option
                  cannot be combined with the option maps.

                {n2n, EnumTypeName}:
                  Tells the compiler to generate functions for conversion  be-
                  tween  names  (as  atoms) and numbers and conversely for the
                  specified EnumTypeName. There can be multiple occurrences of
                  this  option  to  specify several type names. The type names
                  must be declared as ENUMERATIONS in the ASN.1 specification.

                  If EnumTypeName does not exist in the  ASN.1  specification,
                  the compilation stops with an error code.

                  The  generated conversion functions are named name2num_Enum-
                  TypeName/1 and num2name_EnumTypeName/1.

                noobj:
                  Do not compile (that is, do not  produce  object  code)  the
                  generated  .erl  file. If this option is omitted, the gener-
                  ated Erlang module is compiled.

                {i, IncludeDir}:
                  Adds IncludeDir to the search-path  for  .asn1db  and  ASN.1
                  source  files.  The  compiler  tries to open an .asn1db file
                  when a module imports definitions from another ASN.1 module.
                  If  no  .asn1db  file  is  found,  the  ASN.1 source file is
                  parsed. Several {i, IncludeDir} can be given.

                {outdir, Dir}:
                  Specifies directory Dir where all generated files are to  be
                  placed.  If  this option is omitted, the files are placed in
                  the current directory.

                asn1config:
                  When using one of the specialized decodes, exclusive or  se-
                  lective  decode,  instructions must be given in a configura-
                  tion file. Option asn1config enables specialized decodes and
                  takes  the  configuration file in concern. The configuration
                  file has the same name as the ASN.1 specification, but  with
                  extension .asn1config.

                  For instructions for exclusive decode, see Section Exclusive
                  Decode in the User's Guide.

                  For instructions for selective decode, see Section Selective
                  Decode in the User's Guide.

                undec_rest:
                  A  buffer  that  holds  a message, being decoded it can also
                  have some following bytes. Those following bytes can now  be
                  returned together with the decoded value. If an ASN.1 speci-
                  fication is compiled with this option, a tuple  {ok,  Value,
                  Rest}  is  returned. Rest can be a list or a binary. Earlier
                  versions of the compiler ignored those following bytes.

                no_ok_wrapper:
                  With this option, the generated encode/2 and decode/2  func-
                  tions  do  not wrap a successful return value in an {ok,...}
                  tuple. If any error occurs, an exception will be raised.

                {macro_name_prefix, Prefix}:
                  All macro names generated by the compiler are prefixed  with
                  Prefix.  This is useful when multiple protocols that contain
                  macros with identical names are included in a single module.

                {record_name_prefix, Prefix}:
                  All record names generated by the compiler are prefixed with
                  Prefix.  This is useful when multiple protocols that contain
                  records with identical names are included in a  single  mod-
                  ule.

                verbose:
                  Causes more verbose information from the compiler describing
                  what it is doing.

                warnings_as_errors:
                  Causes warnings to be treated as errors.

              Any more option that is applied is passed to the final step when
              the generated .erl file is compiled.

              The compiler generates the following files:

                * Asn1module.hrl (if any SET or SEQUENCE is defined)

                * Asn1module.erl  -  Erlang  module  with  encode, decode, and
                  value functions

                * Asn1module.asn1db - Intermediate format used by the compiler
                  when modules IMPORT definitions from each other.

       value(Module, Type) -> {ok, Value} | {error, Reason}

              Types:

                 Module = Type = atom()
                 Value = term()
                 Reason = term()

              Returns an Erlang term that is an example of a valid Erlang rep-
              resentation of a value of the ASN.1 type Type. The  value  is  a
              random value and subsequent calls to this function will for most
              types return different values.

          Note:
              Currently, the value function has many limitations. Essentially,
              it  will  mostly  work  for old specifications based on the 1997
              standard for ASN.1, but not for most modern-style  applications.
              Another  limitation  is  that the value function may not work if
              options that change code generations strategies such as the  op-
              tions macro_name_prefix and record_name_prefix have been used.

       test(Module) -> ok | {error, Reason}
       test(Module, Type | Options) -> ok | {error, Reason}
       test(Module, Type, Value | Options) -> ok | {error, Reason}

              Types:

                 Module = Type = atom()
                 Value = term()
                 Options = [{i, IncludeDir}]
                 Reason = term()

              Performs  a  test  of  encode and decode of types in Module. The
              generated functions are called by this function.  This  function
              is  useful  during  test to secure that the generated encode and
              decode functions as well as the general runtime support work  as
              expected.

          Note:
              Currently,  the  test  functions  have  many limitations. Essen-
              tially, they will mostly work for old  specifications  based  on
              the  1997  standard for ASN.1, but not for most modern-style ap-
              plications. Another limitation is that the  test  functions  may
              not work if options that change code generations strategies such
              as the options  macro_name_prefix  and  record_name_prefix  have
              been used.

                * test/1 iterates over all types in Module.

                * test/2 tests type Type with a random value.

                * test/3 tests type Type with Value.

              Schematically, the following occurs for each type in the module:

              {ok, Value} = asn1ct:value(Module, Type),
              {ok, Bytes} = Module:encode(Type, Value),
              {ok, Value} = Module:decode(Type, Bytes).

              The  test functions use the *.asn1db files for all included mod-
              ules. If they are located in a different directory than the cur-
              rent  working  directory,  use  the include option to add paths.
              This is only needed when automatically  generating  values.  For
              static values using Value no options are needed.

Ericsson AB                       asn1 5.0.13                     asn1ct(3erl)

Man(1) output converted with man2html
list of all man pages