The R13B03 release.OTP_R13B03

1 files changed, 608 insertions, 0 deletions

diff --git a/lib/snmp/doc/src/snmp.xml b/lib/snmp/doc/src/snmp.xml
new file mode 100644
index 0000000000..af0833f005
--- /dev/null
+++ b/lib/snmp/doc/src/snmp.xml
@@ -0,0 +1,608 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+  <header>
+    <copyright>
+      <year>1996</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>snmp</title>
+    <prepared></prepared>
+    <responsible></responsible>
+    <docno></docno>
+    <approved></approved>
+    <checked></checked>
+    <date></date>
+    <rev></rev>
+    <file>snmp.xml</file>
+  </header>
+  <module>snmp</module>
+  <modulesummary>Interface functions to the SNMP toolkit</modulesummary>
+  <description>
+    <p>The module <c>snmp</c> contains interface functions to the 
+      SNMP toolkit.</p>
+  </description>
+
+  <section>
+    <title>Common Data Types</title>
+    <p>The following data-types are used in the functions below: </p>
+    <list type="bulleted">
+      <item>
+        <p><c>datetime() = {date(), time()}</c></p>
+        <p>See <seealso marker="stdlib:calendar">calendar</seealso> 
+          for more info.</p>
+      </item>
+
+    </list>
+    
+    <marker id="config"></marker>
+  </section>
+
+  <funcs>
+    <func>
+      <name>config() -> ok | {error, Reason}</name>
+      <fsummary>Configure with a simple interactive tool</fsummary>
+      <desc>
+        <p>A simple interactive configuration tool. Simple
+          configuration files can be generated, but more complex
+          configurations still have to be edited manually.
+          </p>
+        <p>The tool is a textual based tool that asks some questions
+          and generates <c>sys.config</c> and <c>*.conf</c> files.
+          </p>
+        <p><em>Note</em> that if the application shall support version 3, 
+          then the crypto app must be started before running this function 
+          (password generation).</p>
+        <p><em>Note</em> also that some of the configuration files for the 
+          agent and manager share the same names. This means that 
+          they have to be stored in <em>different</em> directories!</p>
+
+        <marker id="start"></marker>
+      </desc>
+    </func>
+
+    <func>
+      <name>start() -> ok | {error, Reason}</name>
+      <name>start(Type) -> ok | {error, Reason}</name>
+      <fsummary>Start the SNMP application</fsummary>
+      <type>
+        <v>Type = start_type()</v>
+      </type>
+      <desc>
+        <p>Starts the SNMP application.</p>
+        <p>See <seealso marker="kernel:application">application</seealso> for more info.</p>
+
+        <marker id="start_agent"></marker>
+      </desc>
+    </func>
+
+    <func>
+      <name>start_agent() -> ok | {error, Reason}</name>
+      <name>start_agent(Type) -> ok | {error, Reason}</name>
+      <fsummary>Start the agent part of the SNMP application</fsummary>
+      <type>
+        <v>Type = start_type()</v>
+      </type>
+      <desc>
+        <p>The SNMP application consists of several entities, of which the
+          agent is one. This function starts the agent entity of the 
+          application. 
+          </p>
+        <p>Note that the only way to actually start the agent in this way is
+          to add the agent related config after starting the application (e.g
+          it cannot be part of the normal application config; sys.config).
+          This is done by calling: 
+          <c>application:set_env(snmp, agent, Conf)</c>.
+          </p>
+        <p>The default value for <c>Type</c> is <c>normal</c>.</p>
+	
+	<marker id="start_manager"></marker>
+      </desc>
+    </func>
+
+    <func>
+      <name>start_manager() -> ok | {error, Reason}</name>
+      <name>start_manager(Type) -> ok | {error, Reason}</name>
+      <fsummary>Start the manager part of the SNMP application</fsummary>
+      <type>
+        <v>Type = start_type()</v>
+      </type>
+      <desc>
+        <p>The SNMP application consists of several entities, of which the
+          manager is one. This function starts the manager entity of the 
+          application. 
+          </p>
+        <p>Note that the only way to actually start the manager in this way is
+          to add the manager related config after starting the application (e.g
+          it cannot be part of the normal application config; sys.config).
+          This is done by calling: 
+          <c>application:set_env(snmp, manager, Conf)</c>.
+          </p>
+        <p>The default value for <c>Type</c> is <c>normal</c>.</p>
+
+        <marker id="dat"></marker>
+      </desc>
+    </func>
+
+    <func>
+      <name>date_and_time() -> DateAndTime</name>
+      <fsummary>Return the current date and time as an OCTET STRING</fsummary>
+      <type>
+        <v>DateAndTime = [int()]</v>
+      </type>
+      <desc>
+        <p>Returns current date and time as the data type DateAndTime,
+          as specified in RFC1903. This is an OCTET STRING.</p>
+	  
+	<marker id="dat2ut_dst"></marker>
+      </desc>
+    </func>
+
+    <func>
+      <name>date_and_time_to_universal_time_dst(DateAndTime) -> [utc()]</name>
+      <fsummary>Convert a DateAndTime value to a list of possible utc()</fsummary>
+      <type>
+        <v>DateAndTime = [int()]</v>
+        <v>utc() = {{Y,Mo,D},{H,M,S}}</v>
+      </type>
+      <desc>
+        <p>Converts a DateAndTime list to a list of possible universal 
+          time(s). The universal time value on the same format as defined in
+          calendar(3). </p>
+
+	<marker id="dat2s"></marker>
+      </desc>
+    </func>
+
+    <func>
+      <name>date_and_time_to_string(DateAndTime) -> string()</name>
+      <name>date_and_time_to_string(DateAndTime, Validate) -> string()</name>
+      <fsummary>Convert a DateAndTime value to a string</fsummary>
+      <type>
+        <v>DateAndTime = [int()]</v>
+	<v>Validate = fun(Kind, Data) -> boolean()</v>
+      </type>
+      <desc>
+        <p>Converts a DateAndTime list to a printable string, according
+          to the DISPLAY-HINT definition in RFC2579.</p>
+
+        <p>The validation fun,  <c>Validate</c>, allows for a more "flexible" 
+          validation of the <c>DateAndTime</c> argument. Whenever the data 
+          is found to not follow RFC2579, the fun is called to allow a more
+          "lax" validation. 
+          See the <seealso marker="#vdat">validate_date_and_time/2</seealso> 
+          function for more info on the <c>Validate</c> fun. </p>
+
+	<marker id="dat2s2"></marker>
+      </desc>
+    </func>
+
+    <func>
+      <name>date_and_time_to_string2(DateAndTime) -> string()</name>
+      <fsummary>Convert a DateAndTime value to a string</fsummary>
+      <type>
+        <v>DateAndTime = [int()]</v>
+      </type>
+      <desc>
+	<p>Converts a DateAndTime list to a printable string, according
+	  to the DISPLAY-HINT definition in RFC2579, with the extension 
+          that it also allows the values "hours from UTC" = 14 together with 
+          "minutes from UTC" = 0. </p>
+
+	<marker id="lt2dat_dst"></marker>
+      </desc>
+    </func>
+
+    <func>
+      <name>local_time_to_date_and_time_dst(Local) -> [DateAndTime]</name>
+      <fsummary>Convert a Local time value to a list of possible DateAndTime(s)</fsummary>
+      <type>
+        <v>Local = {{Y,Mo,D},{H,M,S}}</v>
+        <v>DateAndTime = [int()]</v>
+      </type>
+      <desc>
+        <p>Converts a local time value to a list of possible DateAndTime 
+          list(s). The local time value on the same format as defined in 
+          calendar(3).</p>
+
+	<marker id="ut2dat"></marker>
+      </desc>
+    </func>
+
+    <func>
+      <name>universal_time_to_date_and_time(UTC) -> DateAndTime</name>
+      <fsummary>Convert a UTC value to DateAndTime</fsummary>
+      <type>
+        <v>UTC = {{Y,Mo,D},{H,M,S}}</v>
+        <v>DateAndTime = [int()]</v>
+      </type>
+      <desc>
+        <p>Converts a universal time value to a DateAndTime list.  The
+          universal time value on the same format as defined in calendar(3).</p>
+
+        <marker id="vdat"></marker>
+      </desc>
+    </func>
+
+    <func>
+      <name>validate_date_and_time(DateAndTime) -> bool()</name>
+      <name>validate_date_and_time(DateAndTime, Validate) -> bool()</name>
+      <fsummary>Check if a DateAndTime value is correct</fsummary>
+      <type>
+        <v>DateAndTime = term()</v>
+	<v>Validate = fun(Kind, Data) -> boolean()</v>
+      </type>
+      <desc>
+        <p>Checks if <c>DateAndTime</c> is a correct DateAndTime
+          value, as specified in RFC2579.  This function can be used in
+          instrumentation functions to validate a DateAndTime value.</p>
+
+
+        <p>The validation fun,  <c>Validate</c>, allows for a more "flexible" 
+          validation of the <c>DateAndTime</c> argument. Whenever the data 
+          is found to not follow RFC2579, the fun is called to allow a more
+          "lax" validation. 
+          The input to the validation fun looks like this: </p>
+
+        <pre>
+          Kind             Data
+          --------------   ----------------------
+          year             {Year1, Year2}
+          month            Month
+          day              Day
+          hour             Hour
+          minute           Minute
+          seconds          Seconds
+          deci_seconds     DeciSeconds
+          diff             [Sign, Hour, Minute]
+          valid_date       {Year, Month, Day}
+	</pre>
+
+        <marker id="passwd2localized_key"></marker>
+      </desc>
+    </func>
+
+    <func>
+      <name>passwd2localized_key(Alg, Passwd, EngineID) -> Key</name>
+      <fsummary>Generates an localized key</fsummary>
+      <type>
+        <v>Alg = algorithm()</v>
+        <v>algorithm() = md5 | sha</v>
+        <v>Passwd = string()</v>
+        <v>EngineID = string()</v>
+        <v>Key = list()</v>
+      </type>
+      <desc>
+        <p>Generates a key that can be used as an authentication
+          or privacy key using MD5 och SHA.  The key is
+          localized for EngineID.</p>
+
+        <marker id="octet_string_to_bits"></marker>
+      </desc>
+    </func>
+
+    <func>
+      <name>octet_string_to_bits(S) -> Val</name>
+      <fsummary>Convert an OCTET-STRING to BITS</fsummary>
+      <type>
+        <v>Val = bits()</v>
+      </type>
+      <desc>
+        <p>Utility function for converting a value of type 
+          <c>OCTET-STRING</c> to <c>BITS</c>. </p>
+
+        <marker id="bits_to_octet_string"></marker>
+      </desc>
+    </func>
+
+    <func>
+      <name>bits_to_octet_string(B) -> Val</name>
+      <fsummary>Convert an OCTET-STRING to BITS</fsummary>
+      <type>
+        <v>Val = octet_string()</v>
+      </type>
+      <desc>
+        <p>Utility function for converting a value of type <c>BITS</c> 
+          to <c>OCTET-STRING</c>. </p>
+
+        <marker id="read_mib"></marker>
+      </desc>
+    </func>
+
+    <func>
+      <name>read_mib(FileName) -> {ok, mib()} | {error, Reason}</name>
+      <fsummary></fsummary>
+      <type>
+        <v>FileName = string()</v>
+        <v>mib() = #mib{}</v>
+        <v>Reason = term()</v>
+      </type>
+      <desc>
+        <p>Read a compiled mib.</p>
+
+        <marker id="log_to_txt"></marker>
+      </desc>
+    </func>
+
+    <func>
+      <name>log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile) ->  ok | {error, Reason}</name>
+      <name>log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Start) ->  ok | {error, Reason}</name>
+      <name>log_to_txt(LogDir, Mibs, OutFile, LogName, LogFile, Start, Stop) -> ok | {error, Reason}</name>
+      <fsummary>Convert an Audit Trail Log to text format</fsummary>
+      <type>
+        <v>LogDir = string()</v>
+        <v>Mibs = [MibName]</v>
+        <v>OutFile = string()</v>
+        <v>MibName = string()</v>
+        <v>LogName = string()</v>
+        <v>LogFile = string()</v>
+        <v>Start = Stop = null | datetime() | {local_time,datetime()} |  {universal_time,datetime()} </v>
+        <v>Reason = term()</v>
+      </type>
+      <desc>
+        <p>Converts an Audit Trail Log to a readable text file, where
+          each item has a trailing TAB character, and any TAB
+          character in the body of an item has been replaced by ESC
+          TAB.
+          </p>
+        <p>The function can be used on a running system, or by copying
+          the entire log directory and calling this function. SNMP
+          must be running in order to provide MIB information.
+          </p>
+        <p><c>LogDir</c> is the name of the directory where the audit
+          trail log is stored. 
+          <c>Mibs</c> is a list of Mibs to be used. The function uses 
+          the information in the Mibs to convert for example object 
+          identifiers to their symbolic name. 
+          <c>OutFile</c> is the name of the generated text-file.
+          <c>LogName</c> is the name of the log, 
+          <c>LogFile</c> is the name of the log file. 
+          <c>Start</c> is the start (first) date and time from which 
+          log events will be converted and 
+          <c>Stop</c> is the stop (last) date and time to which log 
+          events will be converted.
+          </p>
+        <p>The format of an audit trail log text item is as follows:
+          </p>
+        <p><c>Tag Addr - Community [TimeStamp] Vsn</c><br></br>
+          <c>PDU</c></p>
+        <p>where <c>Tag</c> is <c>request</c>, <c>response</c>, 
+          <c>report</c>, <c>trap</c> or <c>inform</c>; Addr is 
+          <c>IP:Port</c> (or comma space separated list of such);
+          <c>Community</c> is the community parameter (SNMP version
+          v1 and v2), or <c>SecLevel:"AuthEngineID":"UserName"</c>
+          (SNMP v3); <c>TimeStamp</c> is a date and time stamp,
+          and <c>Vsn</c> is the SNMP version. <c>PDU</c> is a textual
+          version of the protocol data unit. There is a new line
+          between <c>Vsn</c> and <c>PDU</c>.</p>
+
+        <marker id="change_log_size"></marker>
+      </desc>
+    </func>
+
+    <func>
+      <name>change_log_size(LogName, NewSize) -> ok | {error, Reason}</name>
+      <fsummary>Change the size of the Audit Trail Log</fsummary>
+      <type>
+        <v>LogName = string()</v>
+        <v>NewSize = {MaxBytes, MaxFiles}</v>
+        <v>MaxBytes = integer()</v>
+        <v>MaxFiles = integer()</v>
+        <v>Reason = term()</v>
+      </type>
+      <desc>
+        <p>Changes the log size of the Audit Trail Log.  The
+          application must be configured to use the audit trail log
+          function. Please refer to disk_log(3) in Kernel Reference 
+          Manual for a description of how to change the log size.
+          </p>
+        <p>The change is permanent, as long as the log is not deleted. 
+          That means, the log size is remembered across reboots.</p>
+
+	<marker id="print_version_info"></marker>
+      </desc>
+    </func>
+
+    <func>
+      <name>print_version_info() -> void()</name>
+      <name>print_version_info(Prefix) -> void()</name>
+      <fsummary>Formatted print of result of the versions functions</fsummary>
+      <type>
+        <v>Prefix = string() | integer()</v>
+      </type>
+      <desc>
+        <p>Utility function(s) to produce a formatted printout of the versions
+          info generated by the <c>versions1</c> function</p>
+        <p>This is the same as doing, e.g.: </p>
+        <pre>
+           {ok, V} = snmp:versions1(), 
+           snmp:print_versions(V).
+        </pre>
+
+	<marker id="versions1"></marker>
+	<marker id="versions2"></marker>
+      </desc>
+    </func>
+
+    <func>
+      <name>versions1() -> {ok, Info} | {error, Reason}</name>
+      <name>versions2() -> {ok, Info} | {error, Reason}</name>
+      <fsummary>Retrieve various system and application info</fsummary>
+      <type>
+        <v>Info = [info()]</v>
+        <v>info() = term()</v>
+        <v>Reason = term()</v>
+      </type>
+      <desc>
+        <p>Utility functions used to retrieve some system and
+          application info.</p>
+        <p>The difference between the two functions is in how they get
+          the modules to check. <c>versions1</c> uses the app-file and
+          <c>versions2</c> uses the function <c>application:get_key</c>.</p>
+
+        <marker id="print_versions"></marker>
+      </desc>
+    </func>
+
+    <func>
+      <name>print_versions(VersionInfo) -> void()</name>
+      <name>print_versions(Prefix, VersionInfo) -> void()</name>
+      <fsummary>Formatted print of result of the versions functions</fsummary>
+      <type>
+        <v>VersionInfo = [version_info()]</v>
+        <v>version_info() = term()</v>
+        <v>Prefix = string() | integer()</v>
+      </type>
+      <desc>
+        <p>Utility function to produce a formatted printout of the versions
+          info generated by the <c>versions1</c> and <c>versions2</c>
+          functions</p>
+        <p>Example: </p>
+        <pre>
+           {ok, V} = snmp:versions1(), 
+           snmp:print_versions(V).
+        </pre>
+
+        <marker id="enable_trace"></marker>
+      </desc>
+    </func>
+
+    <func>
+      <name>enable_trace() -> void()</name>
+      <fsummary>Starts a tracer</fsummary>
+      <!--
+      <type>
+        <v>Prefix = string() | integer()</v>
+      </type>
+      -->
+      <desc>
+        <p>Starts a dbg tracer that prints trace events to stdout (using
+          plain io:format after a minor formatting). </p>
+
+        <marker id="disable_trace"></marker>
+      </desc>
+    </func>
+
+    <func>
+      <name>disable_trace() -> void()</name>
+      <fsummary>Stop the tracer</fsummary>
+      <!--
+      <type>
+        <v>Prefix = string() | integer()</v>
+      </type>
+      -->
+      <desc>
+        <p>Stop the tracer. </p>
+
+        <marker id="set_trace1"></marker>
+      </desc>
+    </func>
+
+    <func>
+      <name>set_trace(Targets) -> void()</name>
+      <fsummary>Set trace target</fsummary>
+      <type>
+        <v>Targets = target() | targets()</v>
+        <v>target() = module()</v>
+        <v>module() = atom()</v>
+        <v>targets() = [target() | {target(), target_options()}]</v>
+        <v>target_options() = [target_option()]</v>
+        <v>target_option() = {return_trace, boolean()} | {scope, scope()}</v>
+        <v>scope() = all_functions | exported_functions | function_name() | {function_name(), function_arity()}</v>
+        <v>function_name() = atom()</v>
+        <v>function_arity() = integer() >= 0</v>
+      </type>
+      <desc>
+        <p>This function is used to set up default trace on function(s) 
+          for the given module or modules. The scope of the trace will be 
+          all <em>exported</em> functions (both the call info and the return 
+	  value). Timestamp info will also be included. </p>
+
+        <marker id="reset_trace"></marker>
+      </desc>
+    </func>
+
+    <func>
+      <name>reset_trace(Targets) -> void()</name>
+      <fsummary>Reset trace target</fsummary>
+      <type>
+        <v>Targets = module() | modules()</v>
+        <v>modules() = [module()]</v>
+        <v>module() = atom()</v>
+      </type>
+      <desc>
+        <p>This function is used to reset (disable) trace for the 
+	  given module(s). </p>
+      
+	<marker id="set_trace2"></marker>
+      </desc>
+    </func>
+
+    <func>
+      <name>set_trace(Targets, Opts) -> void()</name>
+      <fsummary>Set trace target</fsummary>
+      <type>
+        <v>Targets = target() | targets()</v>
+        <v>target() = module()</v>
+        <v>module() = atom()</v>
+        <v>targets() = [target() | {target(), target_options()}]</v>
+        <v>target_options() = [target_option()]</v>
+        <v>target_option() = {return_trace, boolean()} | {scope, scope()}</v>
+        <v>scope() = all_functions | exported_functions | function_name() | {function_name(), function_arity()}</v>
+        <v>function_name() = atom()</v>
+        <v>function_arity() = integer() >= 0</v>
+        <v>Opts = disable | trace_options()</v>
+        <v>trace_options() = [trace_option()]</v>
+        <v>trace_option() = {timestamp, boolean()} | target_option()</v>
+      </type>
+      <desc>
+        <p>This function is used to set up trace on function(s) for the given
+	  module or modules. </p>
+
+	<p>The example below sets up trace on the exported functions (default) 
+	  of module <c>snmp_generic</c> and all functions of module 
+	  <c>snmp_generic_mnesia</c>. With return values (which is default)
+          and timestamps in both cases (which is also default): </p>
+
+	<pre>
+	  snmp:enable_trace(),
+	  snmp:set_trace([snmp_generic, 
+                          {snmp_generic_mnesia, [{scope, all_functions}]}]),
+	  .
+	  .
+	  .
+          snmp:set_trace(snmp_generic, disable),
+	  .
+	  .
+	  .
+	  snmp:disable_trace(),
+	</pre>
+
+      </desc>
+    </func>
+
+  </funcs>
+
+  <section>
+    <title>See Also</title>
+    <p>calendar(3)
+      </p>
+  </section>
+  
+</erlref>
+