diff options
Diffstat (limited to 'lib/erl_interface/doc/src/erl_error.xml')
| -rw-r--r-- | lib/erl_interface/doc/src/erl_error.xml | 136 |
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örn Törnkvist</prepared> + <responsible>Torbjörn Törnkvist</responsible> + <docno></docno> + <approved>Bjarne Däcker</approved> + <checked>Torbjörn Tö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> + |