The R13B03 release.OTP_R13B03

1 files changed, 450 insertions, 0 deletions

diff --git a/lib/kernel/doc/src/error_logger.xml b/lib/kernel/doc/src/error_logger.xml
new file mode 100644
index 0000000000..e107d9b746
--- /dev/null
+++ b/lib/kernel/doc/src/error_logger.xml
@@ -0,0 +1,450 @@
+<?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>error_logger</title>
+    <prepared></prepared>
+    <docno></docno>
+    <date></date>
+    <rev></rev>
+  </header>
+  <module>error_logger</module>
+  <modulesummary>Erlang Error Logger</modulesummary>
+  <description>
+    <p>The Erlang <em>error logger</em> is an event manager (see
+      <seealso marker="doc/design_principles:des_princ">OTP Design Principles</seealso> and
+      <seealso marker="stdlib:gen_event">gen_event(3)</seealso>),
+      registered as <c>error_logger</c>. Error, warning and info events
+      are sent to the error logger from the Erlang runtime system and
+      the different Erlang/OTP applications. The events are, by default,
+      logged to tty. Note that an event from a process <c>P</c> is
+      logged at the node of the group leader of <c>P</c>. This means
+      that log output is directed to the node from which a process was
+      created, which not necessarily is the same node as where it is
+      executing.</p>
+    <p>Initially, <c>error_logger</c> only has a primitive event
+      handler, which buffers and prints the raw event messages. During
+      system startup, the application Kernel replaces this with a
+      <em>standard event handler</em>, by default one which writes
+      nicely formatted output to tty. Kernel can also be configured so
+      that events are logged to file instead, or not logged at all, see
+      <seealso marker="kernel_app">kernel(6)</seealso>.</p>
+    <p>Also the SASL application, if started, adds its own event
+      handler, which by default writes supervisor-, crash- and progress
+      reports to tty. See
+      <seealso marker="sasl:sasl_app">sasl(6)</seealso>.</p>
+    <p>It is recommended that user defined applications should report
+      errors through the error logger, in order to get uniform reports.
+      User defined event handlers can be added to handle application
+      specific events. (<c>add_report_handler/1,2</c>). Also, there is
+      a useful event handler in STDLIB for multi-file logging of events,
+      see <c>log_mf_h(3)</c>.</p>
+    <p>Warning events was introduced in Erlang/OTP R9C. To retain
+      backwards compatibility, these are by default tagged as errors,
+      thus showing up as error reports in the logs. By using
+      the command line flag <c><![CDATA[+W <w | i>]]></c>, they can instead
+      be tagged as warnings or info. Tagging them as warnings may
+      require rewriting existing user defined event handlers.</p>
+  </description>
+  <funcs>
+    <func>
+      <name>error_msg(Format) -> ok</name>
+      <name>error_msg(Format, Data) -> ok</name>
+      <name>format(Format, Data) -> ok</name>
+      <fsummary>Send an standard error event to the error logger</fsummary>
+      <type>
+        <v>Format = string()</v>
+        <v>Data = [term()]</v>
+      </type>
+      <desc>
+        <p>Sends a standard error event to the error logger.
+          The <c>Format</c> and <c>Data</c> arguments are the same as
+          the arguments of <c>io:format/2</c>. The event is handled by
+          the standard event handler.</p>
+        <pre>
+1> <input>error_logger:error_msg("An error occurred in ~p~n", [a_module]).</input>
+
+=ERROR REPORT==== 11-Aug-2005::14:03:19 ===
+An error occurred in a_module
+ok</pre>
+        <warning>
+          <p>If called with bad arguments, this function can crash
+            the standard event handler, meaning no further events are
+            logged. When in doubt, use <c>error_report/1</c> instead.</p>
+        </warning>
+      </desc>
+    </func>
+    <func>
+      <name>error_report(Report) -> ok</name>
+      <fsummary>Send a standard error report event to the error logger</fsummary>
+      <type>
+        <v>Report = [{Tag, Data} | term()] | string() | term()</v>
+        <v>&nbsp;Tag = Data = term()</v>
+      </type>
+      <desc>
+        <p>Sends a standard error report event to the error logger.
+          The event is handled by the standard event handler.</p>
+        <pre>
+2> <input>error_logger:error_report([{tag1,data1},a_term,{tag2,data}]).</input>
+
+=ERROR REPORT==== 11-Aug-2005::13:45:41 ===
+    tag1: data1
+    a_term
+    tag2: data
+ok
+3> <input>error_logger:error_report("Serious error in my module").</input>
+
+=ERROR REPORT==== 11-Aug-2005::13:45:49 ===
+Serious error in my module
+ok</pre>
+      </desc>
+    </func>
+    <func>
+      <name>error_report(Type, Report) -> ok</name>
+      <fsummary>Send a user defined error report event to the error logger</fsummary>
+      <type>
+        <v>Type = term()</v>
+        <v>Report = [{Tag, Data} | term()] | string() | term()</v>
+        <v>&nbsp;Tag = Data = term()</v>
+      </type>
+      <desc>
+        <p>Sends a user defined error report event to the error logger.
+          An event handler to handle the event is supposed to have been
+          added. The event is ignored by the standard event handler.</p>
+        <p>It is recommended that <c>Report</c> follows the same
+          structure as for <c>error_report/1</c>.</p>
+      </desc>
+    </func>
+    <func>
+      <name>warning_map() -> Tag</name>
+      <fsummary>Return the current mapping for warning events</fsummary>
+      <type>
+        <v>Tag = error | warning | info</v>
+      </type>
+      <desc>
+        <p>Returns the current mapping for warning events. Events sent
+          using <c>warning_msg/1,2</c> or <c>warning_report/1,2</c>
+          are tagged as errors (default), warnings or info, depending
+          on the value of the command line flag <c>+W</c>.</p>
+        <pre>
+os$ <input>erl</input>
+Erlang (BEAM) emulator version 5.4.8 [hipe] [threads:0] [kernel-poll]
+
+Eshell V5.4.8  (abort with ^G)
+1> <input>error_logger:warning_map().</input>
+error
+2> <input>error_logger:warning_msg("Warnings tagged as: ~p~n", [error]).</input>
+
+=ERROR REPORT==== 11-Aug-2005::15:31:23 ===
+Warnings tagged as: error
+ok
+3> 
+User switch command
+ --> q
+os$ <input>erl +W w</input>
+Erlang (BEAM) emulator version 5.4.8 [hipe] [threads:0] [kernel-poll]
+
+Eshell V5.4.8  (abort with ^G)
+1> <input>error_logger:warning_map().</input>
+warning
+2> <input>error_logger:warning_msg("Warnings tagged as: ~p~n", [warning]).</input>
+
+=WARNING REPORT==== 11-Aug-2005::15:31:55 ===
+Warnings tagged as: warning
+ok</pre>
+      </desc>
+    </func>
+    <func>
+      <name>warning_msg(Format) -> ok</name>
+      <name>warning_msg(Format, Data) -> ok</name>
+      <fsummary>Send a standard warning event to the error logger</fsummary>
+      <type>
+        <v>Format = string()</v>
+        <v>Data = [term()]</v>
+      </type>
+      <desc>
+        <p>Sends a standard warning event to the error logger.
+          The <c>Format</c> and <c>Data</c> arguments are the same as
+          the arguments of <c>io:format/2</c>. The event is handled by
+          the standard event handler. It is tagged either as an error,
+          warning or info, see
+          <seealso marker="#warning_map/0">warning_map/0</seealso>.</p>
+        <warning>
+          <p>If called with bad arguments, this function can crash
+            the standard event handler, meaning no further events are
+            logged. When in doubt, use <c>warning_report/1</c> instead.</p>
+        </warning>
+      </desc>
+    </func>
+    <func>
+      <name>warning_report(Report) -> ok</name>
+      <fsummary>Send a standard warning report event to the error logger</fsummary>
+      <type>
+        <v>Report = [{Tag, Data} | term()] | string() | term()</v>
+        <v>&nbsp;Tag = Data = term()</v>
+      </type>
+      <desc>
+        <p>Sends a standard warning report event to the error logger.
+          The event is handled by the standard event handler. It is
+          tagged either as an error, warning or info, see
+          <seealso marker="#warning_map/0">warning_map/0</seealso>.</p>
+      </desc>
+    </func>
+    <func>
+      <name>warning_report(Type, Report) -> ok</name>
+      <fsummary>Send a user defined warning report event to the error logger</fsummary>
+      <type>
+        <v>Type = term()</v>
+        <v>Report = [{Tag, Data} | term()] | string() | term()</v>
+        <v>&nbsp;Tag = Data = term()</v>
+      </type>
+      <desc>
+        <p>Sends a user defined warning report event to the error
+          logger. An event handler to handle the event is supposed to
+          have been added. The event is ignored by the standard event
+          handler. It is tagged either as an error, warning or info,
+          depending on the value of
+          <seealso marker="#warning_map/0">warning_map/0</seealso>.</p>
+      </desc>
+    </func>
+    <func>
+      <name>info_msg(Format) -> ok</name>
+      <name>info_msg(Format, Data) -> ok</name>
+      <fsummary>Send a standard information event to the error logger</fsummary>
+      <type>
+        <v>Format = string()</v>
+        <v>Data = [term()]</v>
+      </type>
+      <desc>
+        <p>Sends a standard information event to the error logger.
+          The <c>Format</c> and <c>Data</c> arguments are the same as
+          the arguments of <c>io:format/2</c>. The event is handled by
+          the standard event handler.</p>
+        <pre>
+1> <input>error_logger:info_msg("Something happened in ~p~n", [a_module]).</input>
+
+=INFO REPORT==== 11-Aug-2005::14:06:15 ===
+Something happened in a_module
+ok</pre>
+        <warning>
+          <p>If called with bad arguments, this function can crash
+            the standard event handler, meaning no further events are
+            logged. When in doubt, use <c>info_report/1</c> instead.</p>
+        </warning>
+      </desc>
+    </func>
+    <func>
+      <name>info_report(Report) -> ok</name>
+      <fsummary>Send a standard information report event to the error logger</fsummary>
+      <type>
+        <v>Report = [{Tag, Data} | term()] | string() | term()</v>
+        <v>&nbsp;Tag = Data = term()</v>
+      </type>
+      <desc>
+        <p>Sends a standard information report event to the error
+          logger. The event is handled by the standard event handler.</p>
+        <pre>
+2> <input>error_logger:info_report([{tag1,data1},a_term,{tag2,data}]).</input>
+
+=INFO REPORT==== 11-Aug-2005::13:55:09 ===
+    tag1: data1
+    a_term
+    tag2: data
+ok
+3> <input>error_logger:info_report("Something strange happened").</input>
+
+=INFO REPORT==== 11-Aug-2005::13:55:36 ===
+Something strange happened
+ok</pre>
+      </desc>
+    </func>
+    <func>
+      <name>info_report(Type, Report) -> ok</name>
+      <fsummary>Send a user defined information report event to the error logger</fsummary>
+      <type>
+        <v>Type = term()</v>
+        <v>Report = [{Tag, Data} | term()] | string() | term()</v>
+        <v>&nbsp;Tag = Data = term()</v>
+      </type>
+      <desc>
+        <p>Sends a user defined information report event to the error
+          logger. An event handler to handle the event is supposed to
+          have been added. The event is ignored by the standard event
+          handler.</p>
+        <p>It is recommended that <c>Report</c> follows the same
+          structure as for <c>info_report/1</c>.</p>
+      </desc>
+    </func>
+    <func>
+      <name>add_report_handler(Handler) -> Result</name>
+      <name>add_report_handler(Handler, Args) -> Result</name>
+      <fsummary>Add an event handler to the error logger</fsummary>
+      <type>
+        <v>Handler, Args, Result -- see gen_event:add_handler/3</v>
+      </type>
+      <desc>
+        <p>Adds a new event handler to the error logger. The event
+          handler must be implemented as a <c>gen_event</c> callback
+          module, see
+          <seealso marker="stdlib:gen_event">gen_event(3)</seealso>.</p>
+        <p><c>Handler</c> is typically the name of the callback module
+          and <c>Args</c> is an optional term (defaults to []) passed
+          to the initialization callback function <c>Module:init/1</c>.
+          The function returns <c>ok</c> if successful.</p>
+        <p>The event handler must be able to handle the
+          <seealso marker="#events">events</seealso> described below.</p>
+      </desc>
+    </func>
+    <func>
+      <name>delete_report_handler(Handler) -> Result</name>
+      <fsummary>Delete an event handler from the error logger</fsummary>
+      <type>
+        <v>Handler, Result -- see gen_event:delete_handler/3</v>
+      </type>
+      <desc>
+        <p>Deletes an event handler from the error logger by calling
+          <c>gen_event:delete_handler(error_logger, Handler, [])</c>,
+          see <seealso marker="stdlib:gen_event">gen_event(3)</seealso>.</p>
+      </desc>
+    </func>
+    <func>
+      <name>tty(Flag) -> ok</name>
+      <fsummary>Enable or disable printouts to the tty</fsummary>
+      <type>
+        <v>Flag = bool()</v>
+      </type>
+      <desc>
+        <p>Enables (<c>Flag == true</c>) or disables
+          (<c>Flag == false</c>) printout of standard events to the tty.</p>
+        <p>This is done by adding or deleting the standard event handler
+          for output to tty, thus calling this function overrides
+          the value of the Kernel <c>error_logger</c> configuration
+          parameter.</p>
+      </desc>
+    </func>
+    <func>
+      <name>logfile(Request) -> ok | Filename | {error, What}</name>
+      <fsummary>Enable or disable error printouts to a file</fsummary>
+      <type>
+        <v>Request = {open, Filename} | close | filename</v>
+        <v>&nbsp;Filename = atom() | string()</v>
+        <v>What = allready_have_logfile | no_log_file | term()</v>
+      </type>
+      <desc>
+        <p>Enables or disables printout of standard events to a file.</p>
+        <p>This is done by adding or deleting the standard event handler
+          for output to file, thus calling this function overrides
+          the value of the Kernel <c>error_logger</c> configuration
+          parameter.</p>
+        <p>Enabling file logging can be used in combination with calling
+          <c>tty(false)</c>, in order to have a silent system, where
+          all standard events are logged to a file only.
+          There can only be one active log file at a time.</p>
+        <p><c>Request</c> is one of:</p>
+        <taglist>
+          <tag><c>{open, Filename}</c></tag>
+          <item>
+            <p>Opens the log file <c>Filename</c>. Returns <c>ok</c> if
+              successful, or <c>{error, allready_have_logfile}</c> if
+              logging to file is already enabled, or an error tuple if
+              another error occurred. For example, if <c>Filename</c>
+              could not be opened.</p>
+          </item>
+          <tag><c>close</c></tag>
+          <item>
+            <p>Closes the current log file. Returns <c>ok</c>, or
+              <c>{error, What}</c>.</p>
+          </item>
+          <tag><c>filename</c></tag>
+          <item>
+            <p>Returns the name of the log file <c>Filename</c>, or
+              <c>{error, no_log_file}</c> if logging to file is not
+              enabled.</p>
+          </item>
+        </taglist>
+      </desc>
+    </func>
+  </funcs>
+
+  <section>
+    <marker id="events"></marker>
+    <title>Events</title>
+    <p>All event handlers added to the error logger must handle
+      the following events. <c>Gleader</c> is the group leader pid of
+      the process which sent the event, and <c>Pid</c> is the process
+      which sent the event.</p>
+    <taglist>
+      <tag><c>{error, Gleader, {Pid, Format, Data}}</c></tag>
+      <item>
+        <p>Generated when <c>error_msg/1,2</c> or <c>format</c> is
+          called.</p>
+      </item>
+      <tag><c>{error_report, Gleader, {Pid, std_error, Report}}</c></tag>
+      <item>
+        <p>Generated when <c>error_report/1</c> is called.</p>
+      </item>
+      <tag><c>{error_report, Gleader, {Pid, Type, Report}}</c></tag>
+      <item>
+        <p>Generated when <c>error_report/2</c> is called.</p>
+      </item>
+      <tag><c>{warning_msg, Gleader, {Pid, Format, Data}}</c></tag>
+      <item>
+        <p>Generated when <c>warning_msg/1,2</c> is called, provided
+          that warnings are set to be tagged as warnings.</p>
+      </item>
+      <tag><c>{warning_report, Gleader, {Pid, std_warning, Report}}</c></tag>
+      <item>
+        <p>Generated when <c>warning_report/1</c> is called, provided
+          that warnings are set to be tagged as warnings.</p>
+      </item>
+      <tag><c>{warning_report, Gleader, {Pid, Type, Report}}</c></tag>
+      <item>
+        <p>Generated when <c>warning_report/2</c> is called, provided
+          that warnings are set to be tagged as warnings.</p>
+      </item>
+      <tag><c>{info_msg, Gleader, {Pid, Format, Data}}</c></tag>
+      <item>
+        <p>Generated when <c>info_msg/1,2</c> is called.</p>
+      </item>
+      <tag><c>{info_report, Gleader, {Pid, std_info, Report}}</c></tag>
+      <item>
+        <p>Generated when <c>info_report/1</c> is called.</p>
+      </item>
+      <tag><c>{info_report, Gleader, {Pid, Type, Report}}</c></tag>
+      <item>
+        <p>Generated when <c>info_report/2</c> is called.</p>
+      </item>
+    </taglist>
+    <p>Note that also a number of system internal events may be
+      received, a catch-all clause last in the definition of
+      the event handler callback function <c>Module:handle_event/2</c>
+      is necessary. This also holds true for
+      <c>Module:handle_info/2</c>, as there are a number of system
+      internal messages the event handler must take care of as well.</p>
+  </section>
+
+  <section>
+    <title>SEE ALSO</title>
+    <p>gen_event(3), log_mf_h(3), kernel(6), sasl(6)</p>
+  </section>
+</erlref>
+