aboutsummaryrefslogtreecommitdiffstats
path: root/lib/erl_interface/doc/src/erl_error.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/erl_interface/doc/src/erl_error.xml')
-rw-r--r--lib/erl_interface/doc/src/erl_error.xml136
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>
+