Unix/Linux Go Back    


Linux 2.6 - man page for asn1ct (linux section 3erl)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


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 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).

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

	      Types  Asn1module = atom() | string()
		     Options = [Option| OldOption]
		     Option = ber_bin | per_bin | uper_bin | der | compact_bit_string |  noobj	|
		     {n2n,EnumTypeName}  |{outdir,Dir}	|  {i,IncludeDir}  |  optimize | driver |
		     asn1config | undec_rest | {inline,OutputName} | inline | {macro_name_prefix,
		     Prefix} | {record_name_prefix, Prefix} | verbose
		     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 alter-
	      natively be ".asn1" or ".py"). The input files' names must be listed, within quota-
	      tion  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  colli-
	      sions. The compiler solves this problem in two ways: If the definitions are identi-
	      cal 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.  For preferred option use see Preferred Option Use section in users guide
	      . Available options are:

		ber | ber_bin | per | per_bin | uper_bin :
		  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  per_bin  option  means
		  the aligned variant. To use the unaligned variant the uper_bin option has to be
		  used.

		  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.

		  The ber_bin and per_bin options are equivalent with the OldOptions ber and  per
		  with	the difference that the generated encoding/decoding functions take advan-
		  tage of the bit syntax, which in most cases increases the performance consider-
		  ably. The result from encoding is a binary or an iolist.

		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 or ber_bin 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 :
		  Makes  it  possible to use a compact notation for values of the BIT STRING type
		  in Erlang. The notation:

		BitString = {Unused,Binary},
		Unused = integer(),
		Binary = binary()

		  Unused must be a number in the range 0 to 7. It tells  how  many  bits  in  the
		  least  significant  byte  in	Binary that is unused. For details see BIT STRING
		  type section in 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 EnumType-
		  Name 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 com-
		  piler 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 omit-
		  ted the files are placed in the current directory.

		optimize :
		  This	option	is only valid together with one of the per_bin or ber_bin option.
		  It gives time optimized code generated and it uses another runtime  module  and
		  in  the per_bin case a linked-in driver. The result in the per_bin case from an
		  encode when compiled with this option will be a binary.

		driver :
		  Option valid together with ber_bin and optimize options. It enables the use  of
		  a linked-in driver that gives considerable faster decode. In ber_bin the driver
		  is enabled only by explicit use of the option driver .

		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.

		{inline,OutputName} :
		  Compiling with this option gives one output module containing all asn1 run-time
		  functionality. The asn1 specs are provided in a target module Module.set.asn as
		  described above .  The  name	of  the  resulting  module  containing	generated
		  encode/decode  functions and in-lined run-time functions will be OutputName.erl
		  . The merging/in-lining of code is done by the igor module of syntax_tools . By
		  default  the	functions  generated from the first asn1 spec in the .set.asn are
		  exported, unless a {export,[atom()]} or {export_all,true} option are	provided.
		  The list of atoms are names of chosen asn1 specs from the .set.asn file.

		inline :
		  It  is also possible to use the sole argument inline . It is as {inline,Output-
		  Name} , but the output file gets the default name of the source .set.asn file.

		{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.

	      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 = [Int] when integer(Int), Int >= 0, Int =< 255
		     Reason = term()

	      Encodes Value of Type defined in the ASN.1 module Module . Returns a list of  bytes
	      if  successful.  To get as fast execution as possible the encode function only per-
	      forms 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 success-
	      ful or {error,Reason} if an error occurred.

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

	      Types  Module = Type = atom()
		     Value = Reason = term()
		     Bytes = [Int] when integer(Int), Int >= 0, Int =< 255

	      Decodes Type from Module from the list of bytes Bytes . Returns {ok,Value} if  suc-
	      cessful.

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

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

	      Validates that Value conforms to Type from Module . Not implemented in this version
	      of the ASN.1 application.

       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) -> ok | {error,Reason}
       test(Module,Type,Value) -> ok | {error,Reason}

	      Performs a test of encode and decode of all types in Module . The  generated  func-
	      tions  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 <c>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).

Ericsson AB				   asn1 1.6.16				     asn1ct(3erl)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 11:59 PM.