diff options
Diffstat (limited to 'lib/erl_interface/doc/src/erl_error.xml')
-rw-r--r-- | lib/erl_interface/doc/src/erl_error.xml | 63 |
1 files changed, 36 insertions, 27 deletions
diff --git a/lib/erl_interface/doc/src/erl_error.xml b/lib/erl_interface/doc/src/erl_error.xml index 5b8d546e12..a85969d7ff 100644 --- a/lib/erl_interface/doc/src/erl_error.xml +++ b/lib/erl_interface/doc/src/erl_error.xml @@ -28,21 +28,23 @@ <docno></docno> <approved>Bjarne Däcker</approved> <checked>Torbjörn Törnkvist</checked> - <date>961014</date> + <date>1996-10-14</date> <rev>A</rev> <file>erl_error.xml</file> </header> <lib>erl_error</lib> - <libsummary>Error Print Routines</libsummary> + <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> + from "Advanced Programming in the UNIX Environment" + 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 + <c><![CDATA[printf()]]></c>, that is, 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> @@ -55,6 +57,7 @@ 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> @@ -63,11 +66,12 @@ </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> + is not because of a system call. The message provided by the + caller is printed and the process terminates with exit + value <c>1</c>. This 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> @@ -80,6 +84,7 @@ 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> @@ -90,7 +95,7 @@ <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 + terminates with exit value <c>1</c>. This function does not return.</p> </desc> </func> @@ -98,37 +103,41 @@ <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> + <p>Most functions in <c>Erl_Interface</c> 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> + go well, 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> + <fsummary>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 + <p><c><![CDATA[erl_errno]]></c> is initially (at program startup) zero + and is then set by many <c>Erl_Interface</c> functions on failure to + a non-zero error code to indicate what kind of error it + encountered. A successful function call can change <c><![CDATA[erl_errno]]></c> (by calling some other function that - fails), but no function will ever set it to zero. This means + fails), but no function does never 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> + <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 + <p><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> + variable. This means it can be implemented as a macro + (expanding to, for example, <c><![CDATA[*_erl_errno()]]></c>). + For reasons of thread safety (or task safety), this is exactly what + we do on most platforms.</p> </note> </desc> </func> |