Provided by: erlang-manpages_16.b.3-dfsg-1ubuntu2_all bug

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 corresponding Erlang
       module which can encode and decode the data-types specified.  Alternatively  the  compiler
       takes  a  specification  module  (se below) specifying all input modules and generates one
       module with encode/decode functions. There are also some generic functions  which  can  be
       used  in  during  development  of applications which handles ASN.1 data (encoded as BER or
       PER).

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

       Another change in R16 is that the generated encode/2 function (and asn1rt:encode/3) always
       returns a binary. The encode/2 function 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 | der | compact_bit_string | legacy_bit_string | noobj
                 | {n2n, EnumTypeName} |{outdir, Dir} | {i, IncludeDir} | asn1config | undec_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 which returns the value in
              Erlang representation 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). Of course
              Asn1module can be a full pathname (relative or absolute)  including  filename  with
              (or without) extension.

              If  one  wishes  to  compile  a  set  of  Asn1  modules  into  one Erlang file with
              encode/decode functions one has 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"). The input files' names must be  listed,  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 shall look like:

              File1.asn
              File2.asn
              File3.asn

              The output files will in this case get their names from the configuration file.  If
              the configuration file has the name SetOfFiles.set.asn the name of the output files
              will be SetOfFiles.hrl, SetOfFiles.erl and SetOfFiles.asn1db.

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

              Another  unwanted  effect  that  may  occur  in  multi  file  compilation  is  name
              collisions.  The  compiler  solves this problem in two ways: If the definitions are
              identical then the output module keeps only one definition with the original  name.
              But  if  definitions  only  have same name and differs in the definition, then they
              will be renamed. The new names will be the definition name and the original  module
              name concatenated.

              If  any  name  collision have occurred 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 asn1 compiler and options that are
              applied to the Erlang compiler. The latter are those that not is recognized as asn1
              specific. Available options are:

                ber | per | uper:
                  The  encoding  rule  to  be  used.  The supported encoding rules are BER (Basic
                  Encoding Rules), PER aligned (Packed Encoding Rules) and PER unaligned. 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 and
                  as a consequence of this only one encoding rule per ASN.1 module can be used at
                  runtime.

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

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

                  For details see  BIT STRING type section in the Users Guide .

                legacy_bit_string:
                  The BIT STRING type will be decoded to the legacy format, i.e. a list of zeroes
                  and ones. This option is not recommended for new code.

                  For details see  BIT STRING type section in the Users Guide .

                {n2n, EnumTypeName}:
                  Tells  the  compiler  to  generate  functions  for conversion between names (as
                  atoms) and numbers and vice versa for the EnumTypeName specified. There can  be
                  multiple occurrences of this option in order to specify several type names. The
                  type names must  be  declared  as  ENUMERATIONS  in  the  ASN.1  spec.  If  the
                  EnumTypeName does not exist in the ASN.1 spec the compilation will stop with an
                  error    code.    The    generated    conversion    functions     are     named
                  name2num_EnumTypeName/1 and num2name_EnumTypeName/1.

                noobj:
                  Do  not  compile  (i.e  do not produce object code) the generated .erl file. If
                  this option is omitted the generated Erlang module will be compiled.

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

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

                asn1config:
                  When one of the specialized decodes, exclusive or selective decode,  is  wanted
                  one  has  to  give  instructions in a configuration file. The option asn1config
                  enables specialized decodes and takes the configuration  file,  which  has  the
                  same name as the ASN.1 spec but with extension .asn1config, in concern.

                  The  instructions  for exclusive decode must follow the instruction and grammar
                  in the User's Guide.

                  You can also find the instructions for selective decode in the User's Guide.

                undec_rest:
                  A buffer that holds a message, being  decoded  may  also  have  some  following
                  bytes.  Now  it is possible to get those following bytes returned together with
                  the decoded value. If an asn1 spec is compiled with this option  a  tuple  {ok,
                  Value,  Rest}  is returned. Rest may be a list or a binary. Earlier versions of
                  the compiler ignored those following bytes.

                no_ok_wrapper:
                  If this option is given, the generated encode/2 and decode/2 functions will not
                  wrap a successful return value in an {ok,...} tuple. If any error occurs, there
                  will be an exception.

                {macro_name_prefix, Prefix}:
                  All macro names generated by the compiler are prefixed  with  Prefix.  This  is
                  useful  when  multiple  protocols that contains 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 contains records with identical names are
                  included in a single module.

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

                warnings_as_errors:
                  Causes warnings to be treated as errors.

              Any additional option that is applied will be 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 the Erlang module with encode, decode and value functions.

                * Asn1module.asn1db intermediate format used by the compiler when modules IMPORTS
                  definitions from each other.

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

              Types:

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

              Encodes Value of Type defined in the ASN.1 module Module. To get as fast  execution
              as  possible  the  encode  function  only performs rudimentary tests that the input
              Value is a correct instance of Type. The length  of  strings  is  for  example  not
              always  checked.  Returns  {ok, Bytes} if successful or {error, Reason} if an error
              occurred.

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

              Types:

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

              Decodes Type from Module from the binary Bytes. Returns {ok, Value} if successful.

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

              Types:

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

              Returns an Erlang term which is an example of a valid Erlang  representation  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.

       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 and  the  general  runtime  support  work  as
              expected.

                * 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 happens for each type in the module:

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

              The  test  functions  utilizes the *.asn1db files for all included modules. If they
              are located in a different directory than the current 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.