<!DOCTYPE File PUBLIC "-//Liam Quin//DTD C API Documentation v1.1//EN" "doc.dtd"><File>
<Entry dir="liblqerror">
<Function File="../../src/liblqerror/error.c">
<Name>Error</Name>
<Class>Error Handling
<Purpose>
<P>Prints an error message, treating the given format argument as a
printf-style format.  The remaining arguments are optional, as
for printf.</P>
<P>The error message is prepended by the command name (using the
cmdname global variable, if set, or the value of the $CMDNAME
environment variable otherwise), the program name (using the
value of the global `progname', assigned by LQT_InitFromArgv from
argv[0] if not already set), and a string denoting the severity
of the error, as determined by the Severity argument.</P>
<P>The Severity argument is a combination using bitwise or of
the values defined in &lt;error.h&gt;, of which the most commonly used
are as follows:</P>
<P>E_FATAL, which makes Error call exit and terminate the
program;</P>.
<P>E_WARN,
which makes Error print <var>warning: </var>, and does
not call exit;</P>
<P>E_BUG, used on an assertion failure or on detecting a severe
problem that should be caught by testing; if any trace flags are
set, E_BUG makes Error call abort to generate a core dump.</P>
<P>E_MEMORY; you should always include this if you think it might
not be safe to call malloc, for example because the heap is
corrupted or there is no more free memory.</P>
<P>E_SYS, which indicates a failed system or library call, and
makes Error print the corresponding system error message using
errno; be warned that on most systems, printf and other stdio
functions may cause errno to be set even when there is no error,
since they call isatty, which sets errno as a side-effect.</P>
<P>E_INTERNAL, which makes Error prepend the message with the
string <var>internal error: </var>;</P>
<P>E_MULTILINE, which should be used on all lines of a multi-line
error message where Error is called multiple times; the last call
to Error in the sequence must include the E_LASTLINE flag;</P>
<P>E_LASTLINE, which is only ever used on the last of a sequence
of several successive calls to Error to build up a single message
that spans several lines; in the case of E_FATAL errors, it is
only on this call that Error will call exit, for example.</P>
<Bugs>
An embedded newline in a string will cause a core dump on some
systems.
Error appends a newline automatically, so the safest
thing to do is to omit the newline.
</Function>
<Decl>
VARARGS2*/
void
Error(Severity, format, a, b, c, d, e, f, g, h)
    unsigned int Severity;
    CONST char *format;
    int a, b, c, d, e, f, g, h;
</Decl>
</Entry>
