.TH asn1ct 3erl "asn1 4.0.4" "Ericsson AB" "Erlang Module Definition"
.SH NAME
asn1ct \- ASN.1 compiler and compile-time support functions
.SH DESCRIPTION
.LP
The ASN\&.1 compiler takes an ASN\&.1 module as input and generates a corresponding 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 development of applications that handles ASN\&.1 data (encoded as \fIBER\fR\& or \fIPER\fR\&)\&.
.LP

.RS -4
.B
Note:
.RE
By default in OTP 17, the representation of the \fIBIT STRING\fR\& and \fIOCTET STRING\fR\& types as Erlang terms were changed\&. \fIBIT STRING\fR\& values are now Erlang bit strings and \fIOCTET STRING\fR\& values are binaries\&. Also, an undecoded open type is now wrapped in an \fIasn1_OPENTYPE\fR\& tuple\&. For details, see \fBBIT STRING\fR\&, \fBOCTET STRING\fR\&, and \fBASN\&.1 Information Objects\fR\& in the User\&'s Guide\&.
.LP
To revert to the old representation of the types, use option \fIlegacy_erlang_types\fR\&\&.

.LP

.RS -4
.B
Note:
.RE
In OTP R16, the options were simplified\&. The back end is chosen using one of the options \fIber\fR\&, \fIper\fR\&, or \fIuper\fR\&\&. Options \fIoptimize\fR\&, \fInif\fR\&, and \fIdriver\fR\& options are no longer necessary (and the ASN\&.1 compiler generates a warning if they are used)\&. Options \fIber_bin\fR\&, \fIper_bin\fR\&, and \fIuper_bin\fR\& options still work, but generates a warning\&.
.LP
Another change in OTP R16 is that the generated function \fIencode/2\fR\& always returns a binary\&. Function \fIencode/2\fR\& for the \fIBER\fR\& back end used to return an iolist\&.

.SH EXPORTS
.LP
.B
compile(Asn1module) -> ok | {error, Reason}
.br
.B
compile(Asn1module, Options) -> ok | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
Asn1module = atom() | string()
.br
Options = [Option| OldOption]
.br
Option = ber | per | uper | der | compact_bit_string | legacy_bit_string | legacy_erlang_types | 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
.br
OldOption = ber | per
.br
Reason = term()
.br
Prefix = string()
.br
.RE
.RE
.RS
.LP
Compiles the \fIASN\&.1\fR\& module \fIAsn1module\fR\& and generates an Erlang module \fIAsn1module\&.erl\fR\& with encode and decode functions for the types defined in \fIAsn1module\fR\&\&. For each ASN\&.1 value defined in the module, an Erlang function that returns the value in Erlang representation is generated\&.
.LP
If \fIAsn1module\fR\& is a filename without extension, first \fI"\&.asn1"\fR\& is assumed, then \fI"\&.asn"\fR\&, and finally \fI"\&.py"\fR\& (to be compatible with the old ASN\&.1 compiler)\&. \fIAsn1module\fR\& can be a full pathname (relative or absolute) including filename with (or without) extension\&. 
.LP
If it is needed to compile a set of \fIASN\&.1\fR\& 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 \fI"\&.set\&.asn"\fR\& (\fI"\&.asn"\fR\& can alternatively be \fI"\&.asn1"\fR\& or \fI"\&.py"\fR\&)\&. List the input file names within quotation marks (""), one at each row in the file\&. If the input files are \fIFile1\&.asn\fR\&, \fIFile2\&.asn\fR\&, and \fIFile3\&.asn\fR\&, the configuration file must look as follows:
.LP
.nf

File1.asn
File2.asn
File3.asn
.fi
.LP
The output files in this case get their names from the configuration file\&. If the configuration file is named \fISetOfFiles\&.set\&.asn\fR\&, the names of the output files are \fISetOfFiles\&.hrl, SetOfFiles\&.erl, and SetOfFiles\&.asn1db\fR\&\&.
.LP
Sometimes in a system of \fIASN\&.1\fR\& modules, different default tag modes, for example, \fIAUTOMATIC\fR\&, \fIIMPLICIT\fR\&, or \fIEXPLICIT\fR\&\&. The multi-file compilation resolves the default tagging as if the modules were compiled separately\&.
.LP
Name collisions is another unwanted effect that can occur in multi file-compilation\&. The compiler solves this problem in one of two ways:
.RS 2
.TP 2
*
If the definitions are identical, the output module keeps only one definition with the original name\&.
.LP
.TP 2
*
If the definitions have the same name and differs in the definition, they are renamed\&. The new names are the definition name and the original module name concatenated\&.
.LP
.RE

.LP
If a name collision occurs, the compiler reports a \fI"NOTICE: \&.\&.\&."\fR\& message that tells if a definition was renamed, and the new name that must be used to encode/decode data\&.
.LP
\fIOptions\fR\& is a list with options specific for the \fIASN\&.1\fR\& compiler and options that are applied to the Erlang compiler\&. The latter are not recognized as \fIASN\&.1\fR\& specific\&. The available options are as follows:
.RS 2
.TP 2
.B
\fIber | per | uper\fR\&:
The encoding rule to be used\&. The supported encoding rules are Basic Encoding Rules (BER), Packed Encoding Rules (PER) aligned, and PER unaligned\&. If the encoding rule option is omitted, \fIber\fR\& is the default\&.
.RS 2
.LP
The generated Erlang module always gets the same name as the \fIASN\&.1\fR\& module\&. Therefore, only one encoding rule per \fIASN\&.1\fR\& module can be used at runtime\&.
.RE

.TP 2
.B
\fIder\fR\&:
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 together with option \fIber\fR\&\&. This option sometimes adds sorting and value checks when encoding, which implies a slower encoding\&. The decoding routines are the same as for \fIber\fR\&\&.
.TP 2
.B
\fIcompact_bit_string\fR\&:
The \fIBIT STRING\fR\& type is decoded to "compact notation"\&. \fIThis option is not recommended for new code\&.\fR\& 
.RS 2
.LP
For details, see Section \fB BIT STRING\fR\& in the User\&'s Guide\&.
.RE

.RS 2
.LP
This option implies option \fIlegacy_erlang_types\fR\&\&.
.RE

.TP 2
.B
\fIlegacy_bit_string\fR\&:
The \fIBIT STRING\fR\& type is decoded to the legacy format, that is, a list of zeroes and ones\&. \fIThis option is not recommended for new code\&.\fR\& 
.RS 2
.LP
For details, see Section \fBBIT STRING\fR\& in the User\&'s Guide
.RE

.RS 2
.LP
This option implies option \fIlegacy_erlang_types\fR\&\&.
.RE

.TP 2
.B
\fIlegacy_erlang_types\fR\&:
Use the same Erlang types to represent \fIBIT STRING\fR\& and \fIOCTET STRING\fR\& as in OTP R16\&.
.RS 2
.LP
For details, see Section \fBBIT STRING\fR\& and Section \fBOCTET STRING\fR\& in the User\&'s Guide\&.
.RE

.RS 2
.LP
\fIThis option is not recommended for new code\&.\fR\&
.RE

.TP 2
.B
\fI{n2n, EnumTypeName}\fR\&:
Tells the compiler to generate functions for conversion between names (as atoms) and numbers and conversely for the specified \fIEnumTypeName\fR\&\&. There can be multiple occurrences of this option to specify several type names\&. The type names must be declared as \fIENUMERATIONS\fR\& in the ASN\&.1 specification\&.
.RS 2
.LP
If \fIEnumTypeName\fR\& does not exist in the ASN\&.1 specification, the compilation stops with an error code\&.
.RE

.RS 2
.LP
The generated conversion functions are named \fIname2num_EnumTypeName/1\fR\& and \fInum2name_EnumTypeName/1\fR\&\&.
.RE

.TP 2
.B
\fInoobj\fR\&:
Do not compile (that is, do not produce object code) the generated \fI\&.erl\fR\& file\&. If this option is omitted, the generated Erlang module is compiled\&.
.TP 2
.B
\fI{i, IncludeDir}\fR\&:
Adds \fIIncludeDir\fR\& to the search-path for \fI\&.asn1db\fR\& and \fIASN\&.1\fR\& source files\&. The compiler tries to open an \fI\&.asn1db\fR\& file when a module imports definitions from another \fIASN\&.1\fR\& module\&. If no \fI\&.asn1db\fR\& file is found, the \fIASN\&.1\fR\& source file is parsed\&. Several \fI{i, IncludeDir}\fR\& can be given\&.
.TP 2
.B
\fI{outdir, Dir}\fR\&:
Specifies directory \fIDir\fR\& where all generated files are to be placed\&. If this option is omitted, the files are placed in the current directory\&.
.TP 2
.B
\fIasn1config\fR\&:
When using one of the specialized decodes, exclusive or selective decode, instructions must be given in a configuration file\&. Option \fIasn1config\fR\& 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 \fI\&.asn1config\fR\&\&.
.RS 2
.LP
For instructions for exclusive decode, see Section \fBExclusive Decode\fR\& in the User\&'s Guide\&.
.RE

.RS 2
.LP
For instructions for selective decode, see Section \fBSelective Decode\fR\& in the User\&'s Guide\&.
.RE

.TP 2
.B
\fIundec_rest\fR\&:
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 specification is compiled with this option, a tuple \fI{ok, Value, Rest}\fR\& is returned\&. \fIRest\fR\& can be a list or a binary\&. Earlier versions of the compiler ignored those following bytes\&.
.TP 2
.B
\fIno_ok_wrapper\fR\&:
With this option, the generated \fIencode/2\fR\& and \fIdecode/2\fR\& functions do not wrap a successful return value in an \fI{ok,\&.\&.\&.}\fR\& tuple\&. If any error occurs, an exception will be raised\&.
.TP 2
.B
\fI{macro_name_prefix, Prefix}\fR\&:
All macro names generated by the compiler are prefixed with \fIPrefix\fR\&\&. This is useful when multiple protocols that contain macros with identical names are included in a single module\&.
.TP 2
.B
\fI{record_name_prefix, Prefix}\fR\&:
All record names generated by the compiler are prefixed with \fIPrefix\fR\&\&. This is useful when multiple protocols that contain records with identical names are included in a single module\&.
.TP 2
.B
\fIverbose\fR\&:
Causes more verbose information from the compiler describing what it is doing\&.
.TP 2
.B
\fIwarnings_as_errors\fR\&:
Causes warnings to be treated as errors\&.
.RE
.LP
Any more option that is applied is passed to the final step when the generated \fI\&.erl\fR\& file is compiled\&.
.LP
The compiler generates the following files:
.RS 2
.TP 2
*
\fIAsn1module\&.hrl\fR\& (if any \fISET\fR\& or \fISEQUENCE\fR\& is defined) 
.LP
.TP 2
*
\fIAsn1module\&.erl\fR\& - Erlang module with encode, decode, and value functions 
.LP
.TP 2
*
\fIAsn1module\&.asn1db\fR\& - Intermediate format used by the compiler when modules \fIIMPORT\fR\& definitions from each other\&. 
.LP
.RE

.RE

.LP
.B
encode(Module, Type, Value)-> {ok, Bytes} | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
Module = Type = atom()
.br
Value = term()
.br
Bytes = binary()
.br
Reason = term()
.br
.RE
.RE
.RS
.LP
Encodes \fIValue\fR\& of \fIType\fR\& defined in the \fIASN\&.1\fR\& module \fIModule\fR\&\&. To get as fast execution as possible, the encode function performs only the rudimentary tests that input \fIValue\fR\& is a correct instance of \fIType\fR\&\&. So, for example, the length of strings is not always checked\&. Returns \fI{ok, Bytes}\fR\& if successful or \fI{error, Reason}\fR\& if an error occurred\&.
.LP
This function is deprecated\&. Use \fIModule:encode(Type, Value)\fR\& instead\&.
.RE

.LP
.B
decode(Module, Type, Bytes) -> {ok, Value} | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
Module = Type = atom()
.br
Value = Reason = term()
.br
Bytes = binary()
.br
.RE
.RE
.RS
.LP
Decodes \fIType\fR\& from \fIModule\fR\& from the binary \fIBytes\fR\&\&. Returns \fI{ok, Value}\fR\& if successful\&.
.LP
This function is deprecated\&. Use \fIModule:decode(Type, Bytes)\fR\& instead\&.
.RE

.LP
.B
value(Module, Type) -> {ok, Value} | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
Module = Type = atom()
.br
Value = term()
.br
Reason = term()
.br
.RE
.RE
.RS
.LP
Returns an Erlang term that is an example of a valid Erlang representation of a value of the \fIASN\&.1\fR\& type \fIType\fR\&\&. The value is a random value and subsequent calls to this function will for most types return different values\&.
.LP

.RS -4
.B
Note:
.RE
Currently, the \fIvalue\fR\& 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 \fIvalue\fR\& function may not work if options that change code generations strategies such as the options \fImacro_name_prefix\fR\& and \fIrecord_name_prefix\fR\& have been used\&.

.RE

.LP
.B
test(Module) -> ok | {error, Reason}
.br
.B
test(Module, Type | Options) -> ok | {error, Reason}
.br
.B
test(Module, Type, Value | Options) -> ok | {error, Reason}
.br
.RS
.LP
Types:

.RS 3
Module = Type = atom()
.br
Value = term()
.br
Options = [{i, IncludeDir}]
.br
Reason = term()
.br
.RE
.RE
.RS
.LP
Performs a test of encode and decode of types in \fIModule\fR\&\&. 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\&.
.LP

.RS -4
.B
Note:
.RE
Currently, the \fItest\fR\& functions have many limitations\&. Essentially, they 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 \fItest\fR\& functions may not work if options that change code generations strategies such as the options \fImacro_name_prefix\fR\& and \fIrecord_name_prefix\fR\& have been used\&.

.RS 2
.TP 2
*
\fItest/1\fR\& iterates over all types in \fIModule\fR\&\&.
.LP
.TP 2
*
\fItest/2\fR\& tests type \fIType\fR\& with a random value\&.
.LP
.TP 2
*
\fItest/3\fR\& tests type \fIType\fR\& with \fIValue\fR\&\&.
.LP
.RE

.LP
Schematically, the following occurs for each type in the module:
.LP
.nf

{ok, Value} = asn1ct:value(Module, Type),
{ok, Bytes} = asn1ct:encode(Module, Type, Value),
{ok, Value} = asn1ct:decode(Module, Type, Bytes).
.fi
.LP
The \fItest\fR\& functions use the \fI*\&.asn1db\fR\& 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 \fIValue\fR\& no options are needed\&.
.RE