The R13B03 release.OTP_R13B03

1 files changed, 379 insertions, 0 deletions

diff --git a/lib/asn1/doc/src/asn1ct.xml b/lib/asn1/doc/src/asn1ct.xml
new file mode 100644
index 0000000000..9c04956e86
--- /dev/null
+++ b/lib/asn1/doc/src/asn1ct.xml
@@ -0,0 +1,379 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+  <header>
+    <copyright>
+      <year>1997</year><year>2009</year>
+      <holder>Ericsson AB. All Rights Reserved.</holder>
+    </copyright>
+    <legalnotice>
+      The contents of this file are subject to the Erlang Public License,
+      Version 1.1, (the "License"); you may not use this file except in
+      compliance with the License. You should have received a copy of the
+      Erlang Public License along with this software. If not, it can be
+      retrieved online at http://www.erlang.org/.
+    
+      Software distributed under the License is distributed on an "AS IS"
+      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+      the License for the specific language governing rights and limitations
+      under the License.
+    
+    </legalnotice>
+
+    <title>asn1ct</title>
+    <prepared>Kenneth Lundin</prepared>
+    <responsible>Kenneth Lundin</responsible>
+    <docno>1</docno>
+    <approved>Kenneth Lundin</approved>
+    <checked></checked>
+    <date>97-10-14</date>
+    <rev>A</rev>
+    <file>asn1.sgml</file>
+  </header>
+  <module>asn1ct</module>
+  <modulesummary>ASN.1 compiler and compile-time support functions</modulesummary>
+  <description>
+    <p>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).</p>
+  </description>
+  <funcs>
+    <func>
+      <name>compile(Asn1module) -> ok | {error,Reason}</name>
+      <name>compile(Asn1module , Options) -> ok | {error,Reason}</name>
+      <fsummary>Compile an ASN.1 module and generate encode/decode functions according to the encoding rules BER or PER.</fsummary>
+      <type>
+        <v>Asn1module = atom() | string()</v>
+        <v>Options = [Option| OldOption]</v>
+        <v>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</v>
+        <v>OldOption = ber | per</v> 
+        <v>Reason = term()</v>
+      </type>
+      <desc>
+        <p>Compiles the ASN.1 module <c>Asn1module</c> and generates an 
+          Erlang module <c>Asn1module.erl</c> with encode and decode 
+          functions for the types defined in <c>Asn1module</c>. For each 
+          ASN.1 value defined in the module an Erlang function which 
+          returns the value in Erlang representation is generated.</p>
+        <p>If <c>Asn1module</c> is a filename without extension first
+          <c>".asn1"</c> is assumed, then <c>".asn"</c> and finally
+          <c>".py"</c> (to be compatible with the old ASN.1 compiler).
+          Of course <c>Asn1module</c> can be a full pathname (relative or
+          absolute) including filename with (or without) extension.
+                    <marker id="asn1set"></marker>
+</p>
+        <p>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 <c>File1.asn</c>,
+          <c>File2.asn</c> and <c>File3.asn</c> the configuration file
+          shall look like:</p>
+        <pre>
+File1.asn
+File2.asn
+File3.asn        </pre>
+        <p>The output files will in this case get their names from the
+          configuration file. If the configuration file has the name
+          <c>SetOfFiles.set.asn</c> the name of the output files will be
+          <c>SetOfFiles.hrl, SetOfFiles.erl and SetOfFiles.asn1db</c>.</p>
+        <p>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.</p>
+        <p>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.</p>
+        <p>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.</p>
+
+        <p>
+	  <c>Options</c> 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 <em>preferred option use</em> see <seealso
+	  marker="asn1_ug#preferred option use">Preferred Option Use
+	  section in users guide</seealso>. Available options are:
+	</p>
+	<taglist>
+          <tag><c>ber | ber_bin | per | per_bin | uper_bin</c></tag>
+          <item>
+            <p>
+	      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 <c>ber</c> 
+	      is the default.
+	      The <c>per_bin</c> option means the aligned
+	      variant. To use the unaligned variant the <c>uper_bin</c>
+	      option has to be used.
+	    </p>
+	    <p>
+	      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.
+	    </p>
+	    <p>
+	      The <c>ber_bin</c> and <c>per_bin</c> options are
+	      equivalent with the <c>OldOptions</c> <c>ber</c> and <c>per</c>
+	      with the difference that the generated encoding/decoding
+	      functions take advantage of the bit syntax, which in most
+	      cases increases the performance considerably. The result
+	      from encoding is a binary or an iolist.
+	    </p>
+          </item>
+          <tag><c>der</c></tag>
+          <item>
+            <p>
+	      By this option the Distinguished Encoding Rules (DER) is chosen.
+	      DER is regarded as a specialized variant of the BER encoding 
+              rule, therefore the <c>der</c> option only makes sense together
+	      with the <c>ber</c> or <c>ber_bin</c> option. 
+	      This option
+              sometimes adds sorting and value checks when encoding, which
+              implies a slower encoding. The decoding routines are the same
+              as for <c>ber</c>.
+	    </p>
+          </item>
+          <tag><c>compact_bit_string</c></tag>
+          <item>
+            <p>
+	      Makes it possible to use a compact notation for values
+              of the BIT STRING type in Erlang. The notation: 
+	    </p>
+            <pre>
+BitString = {Unused,Binary},
+Unused = integer(),
+Binary = binary()            
+	    </pre>
+            <p>
+	      <c>Unused</c> must be a number in the range 0 to 7. It
+	      tells how many bits in the least significant byte in
+	      <c>Binary</c> that is unused. 
+	      For details see 
+	      <seealso marker="asn1_ug#BIT STRING">
+		BIT STRING type section in users guide
+		</seealso>.
+	    </p>
+	  </item>
+          <tag><c>{n2n,EnumTypeName}</c></tag>
+          <item>
+            <p>
+	      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 
+	      <c>name2num_EnumTypeName/1</c> and 
+	      <c>num2name_EnumTypeName/1</c>.
+	    </p>
+          </item>
+          <tag><c>noobj</c></tag>
+          <item>
+            <p>Do not compile (i.e do not produce object code) the generated 
+              <c>.erl</c> file. If this option is omitted the generated Erlang module
+              will be compiled.</p>
+          </item>
+          <tag><c>{i,IncludeDir}</c></tag>
+          <item>
+            <p>Adds <c>IncludeDir</c> to the search-path for
+              <c>.asn1db</c> and asn1 source files. The compiler tries
+              to open a <c>.asn1db</c> file when a module imports
+              definitions from another ASN.1 module. If no
+              <c>.asn1db</c> file is found the asn1 source file is
+              parsed.  Several <c>{i,IncludeDir}</c> can be given.
+              </p>
+          </item>
+          <tag><c>{outdir,Dir}</c></tag>
+          <item>
+            <p>Specifies the directory <c>Dir</c> where all generated files 
+              shall be placed. If omitted the files are placed in the 
+              current directory.</p>
+          </item>
+          <tag><c>optimize</c></tag>
+          <item>
+            <p>This option is only valid together with one of the
+              <c>per_bin</c> 
+              or <c>ber_bin</c> option. It gives time optimized code 
+              generated and it uses another runtime module and 
+              in the <c>per_bin</c> case a linked-in driver. The result 
+              in the <c>per_bin</c> case from an encode when compiled
+              with this option will be a binary.</p>
+          </item>
+          <tag><c>driver</c></tag>
+          <item>
+            <p>Option valid together with <c>ber_bin</c> and <c>optimize</c>
+              options. It enables the use of a linked-in driver that gives
+              considerable faster decode. In <c>ber_bin</c> the driver is
+              enabled only by explicit use of the option <c>driver</c>.</p>
+          </item>
+          <tag><c>asn1config</c></tag>
+          <item>
+            <p>When one of the specialized decodes, exclusive or
+              selective decode, is wanted one has to give instructions in
+              a configuration file. The option <c>asn1config</c> enables
+              specialized decodes and takes the configuration file, which
+              has the same name as the ASN.1 spec but with extension
+              <c>.asn1config</c>, in concern.
+              </p>
+            <p>The instructions for exclusive decode must follow the
+              <seealso marker="asn1_spec#Exclusive Instruction">instruction and grammar in the User's Guide</seealso>.
+              </p>
+            <p>You can also find the instructions for selective decode
+              in the
+              <seealso marker="asn1_spec#Selective Instruction">User's Guide</seealso>.
+              </p>
+          </item>
+          <tag><c>undec_rest</c></tag>
+          <item>
+            <p>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
+              <c>{ok,Value,Rest}</c> is returned. <c>Rest</c> may be a
+              list or a binary. Earlier versions of the compiler ignored
+              those following bytes.</p>
+          </item>
+          <tag><c>{inline,OutputName}</c></tag>
+          <item>
+            <p>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
+              <seealso marker="#asn1set">above</seealso>. The name of the
+              resulting module containing generated encode/decode functions
+              and in-lined run-time functions will be
+              <c>OutputName.erl</c>. The merging/in-lining of code is done
+              by the <c>igor</c> module of <c>syntax_tools</c>. By default
+              the functions generated from the first asn1 spec in the
+              <c>.set.asn</c> are exported, unless a
+              <c>{export,[atom()]}</c> or <c>{export_all,true}</c> option
+              are provided. The list of atoms are names of chosen asn1
+              specs from the <c>.set.asn</c> file.</p>
+          </item>
+          <tag><c>inline</c></tag>
+          <item>
+            <p>It is also possible to use the sole argument <c>inline</c>.
+              It is as <c>{inline,OutputName}</c>, but the output file gets the
+              default name of the source <c>.set.asn</c> file.</p>
+          </item>
+        </taglist>
+        <p>Any additional option that is applied will be passed to
+          the final step when the generated .erl file is compiled.
+          </p>
+        <p>The compiler generates the following files:</p>
+        <list type="bulleted">
+          <item>
+            <p><c>Asn1module.hrl</c> (if any SET or SEQUENCE is defined)</p>
+          </item>
+          <item>
+            <p><c>Asn1module.erl</c> the Erlang module with encode, decode and value functions.</p>
+          </item>
+          <item>
+            <p><c>Asn1module.asn1db</c> intermediate format used by the compiler when modules IMPORTS
+              definitions from each other.</p>
+          </item>
+        </list>
+      </desc>
+    </func>
+    <func>
+      <name>encode(Module,Type,Value)-> {ok,Bytes} | {error,Reason}</name>
+      <fsummary>Encode an ASN.1 value.</fsummary>
+      <type>
+        <v>Module = Type = atom()</v>
+        <v>Value = term()</v>
+        <v>Bytes = [Int] when integer(Int), Int >= 0, Int =&lt; 255</v>
+        <v>Reason = term()</v>
+      </type>
+      <desc>
+        <p>Encodes <c>Value</c> of <c>Type</c> defined in the ASN.1 module 
+          <c>Module</c>. Returns a list of bytes if successful. To get as fast execution as 
+          possible the 
+          encode function only performs rudimentary tests that the input 
+          <c>Value</c>
+          is a correct instance of <c>Type</c>. The length of strings is for example
+          not always checked. Returns <c>{ok,Bytes}</c> if successful or 
+          <c>{error,Reason}</c> if an error occurred.
+          </p>
+      </desc>
+    </func>
+    <func>
+      <name>decode(Module,Type,Bytes) -> {ok,Value}|{error,Reason}</name>
+      <fsummary>Decode from Bytes into an ASN.1 value.</fsummary>
+      <type>
+        <v>Module = Type = atom()</v>
+        <v>Value = Reason = term()</v>
+        <v>Bytes = [Int] when integer(Int), Int >= 0, Int =&lt; 255</v>
+      </type>
+      <desc>
+        <p>Decodes <c>Type</c> from <c>Module</c> from the list of bytes 
+          <c>Bytes</c>. Returns <c>{ok,Value}</c> if successful.</p>
+      </desc>
+    </func>
+    <func>
+      <name>validate(Module,Type,Value) ->  ok | {error,Reason}</name>
+      <fsummary>Validate an ASN.1 value.</fsummary>
+      <type>
+        <v>Module = Type = atom()</v>
+        <v>Value = term()</v>
+      </type>
+      <desc>
+        <p>Validates that <c>Value</c> conforms  to <c>Type</c> 
+          from <c>Module</c>. <em>Not implemented in this version of the ASN.1 application.</em></p>
+      </desc>
+    </func>
+    <func>
+      <name>value(Module ,Type) -> {ok,Value} | {error,Reason}</name>
+      <fsummary>Create an ASN.1 value for test purposes.</fsummary>
+      <type>
+        <v>Module = Type = atom()</v>
+        <v>Value = term()</v>
+        <v>Reason = term()</v>
+      </type>
+      <desc>
+        <p>Returns an Erlang term which is an example of a valid Erlang 
+          representation of a value of the ASN.1 type <c>Type</c>. The value
+          is a random value and subsequent calls to this function will for most
+          types return different values.</p>
+      </desc>
+    </func>
+    <func>
+      <name>test(Module) -> ok | {error,Reason}</name>
+      <name>test(Module,Type) -> ok | {error,Reason}</name>
+      <name>test(Module,Type,Value) -> ok | {error,Reason}</name>
+      <fsummary>Perform a test of encode and decode for types in an  ASN.1 module.</fsummary>
+      <desc>
+        <p>Performs a test of encode and decode of all types in <c>Module</c>. 
+          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.          <br></br>
+<c>test/1</c> iterates over all types in <c>Module</c>.          <br></br>
+<c>test/2</c> tests type <c>Type</c> with a random value.          <br></br>
+<c><![CDATA[test/3 tests type <c>Type]]></c> with <c>Value</c>.          <br></br>
+
+          Schematically the following happens for each type in the module.</p>
+        <p></p>
+        <code type="none">
+{ok,Value} = asn1ct:value(Module,Type),
+{ok,Bytes} = asn1ct:encode(Module,Type,Value),
+{ok,Value} = asn1ct:decode(Module,Type,Bytes).         </code>
+      </desc>
+    </func>
+  </funcs>
+  
+</erlref>
+