The R13B03 release.OTP_R13B03

1 files changed, 136 insertions, 0 deletions

diff --git a/lib/erl_interface/doc/src/erl_error.xml b/lib/erl_interface/doc/src/erl_error.xml
new file mode 100644
index 0000000000..4a3f34fac7
--- /dev/null
+++ b/lib/erl_interface/doc/src/erl_error.xml
@@ -0,0 +1,136 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE cref SYSTEM "cref.dtd">
+
+<cref>
+  <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>erl_error</title>
+    <prepared>Torbj&ouml;rn T&ouml;rnkvist</prepared>
+    <responsible>Torbj&ouml;rn T&ouml;rnkvist</responsible>
+    <docno></docno>
+    <approved>Bjarne D&auml;cker</approved>
+    <checked>Torbj&ouml;rn T&ouml;rnkvist</checked>
+    <date>961014</date>
+    <rev>A</rev>
+    <file>erl_error.sgml</file>
+  </header>
+  <lib>erl_error</lib>
+  <libsummary>Error Print Routines</libsummary>
+  <description>
+    <p>This module contains some error printing routines taken
+      from <em>Advanced Programming in the UNIX Environment</em> 
+      by W. Richard Stevens. </p>
+    <p>These functions are all called in the same manner as
+      <c><![CDATA[printf()]]></c>, i.e. with a string containing format specifiers
+      followed by a list of corresponding arguments. All output from
+      these functions is to <c><![CDATA[stderr]]></c>.</p>
+  </description>
+  <funcs>
+    <func>
+      <name><ret>void</ret><nametext>erl_err_msg(FormatStr, ... )</nametext></name>
+      <fsummary>Non-fatal error, and not system call error</fsummary>
+      <type>
+        <v>const char *FormatStr;</v>
+      </type>
+      <desc>
+        <p>The message provided by the caller is printed. This
+          function is simply a wrapper for <c><![CDATA[fprintf()]]></c>.</p>
+      </desc>
+    </func>
+    <func>
+      <name><ret>void</ret><nametext>erl_err_quit(FormatStr, ... )</nametext></name>
+      <fsummary>Fatal error, but not system call error</fsummary>
+      <type>
+        <v>const char *FormatStr;</v>
+      </type>
+      <desc>
+        <p>Use this function when a fatal error has occurred that
+          is not due to a system call. The message provided by the
+          caller is printed and the process terminates with an exit
+          value of 1. The function does not return.</p>
+      </desc>
+    </func>
+    <func>
+      <name><ret>void</ret><nametext>erl_err_ret(FormatStr, ... )</nametext></name>
+      <fsummary>Non-fatal system call error</fsummary>
+      <type>
+        <v>const char *FormatStr;</v>
+      </type>
+      <desc>
+        <p>Use this function after a failed system call. The message
+          provided by the caller is printed followed by a string
+          describing the reason for failure. </p>
+      </desc>
+    </func>
+    <func>
+      <name><ret>void</ret><nametext>erl_err_sys(FormatStr, ... )</nametext></name>
+      <fsummary>Fatal system call error</fsummary>
+      <type>
+        <v>const char *FormatStr;</v>
+      </type>
+      <desc>
+        <p>Use this function after a failed system call. The message
+          provided by the caller is printed followed by a string
+          describing the reason for failure, and the process
+          terminates with an exit value of 1. The function does not
+          return.</p>
+      </desc>
+    </func>
+  </funcs>
+
+  <section>
+    <title>Error Reporting</title>
+    <p>Most functions in erl_interface report failures to the caller by
+      returning some otherwise meaningless value (typically <c><![CDATA[NULL]]></c>
+      or a negative number). As this only tells you that things did not
+      go well, you will have to examine the error code in
+      <c><![CDATA[erl_errno]]></c> if you want to find out more about the failure.</p>
+  </section>
+  <funcs>
+    <func>
+      <name><ret>volatile int</ret><nametext>erl_errno</nametext></name>
+      <fsummary>The variable <c><![CDATA[erl_errno]]></c>contains the erl_interface error number. You can change the value if you wish. </fsummary>
+      <desc>
+        <p><c><![CDATA[erl_errno]]></c> is initially (at program startup) zero and
+          is then set by many erl_interface functions on failure to a
+          non-zero error code to indicate what kind of error it
+          encountered. A successful function call might change
+          <c><![CDATA[erl_errno]]></c> (by calling some other function that
+          fails), but no function will ever set it to zero. This means
+          that you cannot use <c><![CDATA[erl_errno]]></c> to see <em>if</em> a
+          function call failed. Instead, each function reports failure
+          in its own way (usually by returning a negative number or
+          <c><![CDATA[NULL]]></c>), in which case you can examine <c><![CDATA[erl_errno]]></c>
+          for details.</p>
+        <p><c><![CDATA[erl_errno]]></c> uses the error codes defined in your
+          system's <c><![CDATA[<errno.h>]]></c>.</p>
+        <note>
+          <p>Actually, <c><![CDATA[erl_errno]]></c> is a "modifiable lvalue" (just
+            like ISO C defines <c><![CDATA[errno]]></c> to be) rather than a
+            variable. This means it might be implemented as a macro
+            (expanding to, e.g., <c><![CDATA[*_erl_errno()]]></c>). For reasons of
+            thread- (or task-)safety, this is exactly what we do on most
+            platforms.</p>
+        </note>
+      </desc>
+    </func>
+  </funcs>
+</cref>
+