common/man/error.3

        .fp 5 CW
..
.nr ;G \\n(.f
.Af "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9"
\\*(;G
..
.aF 5 \\n(.f "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7"
..
.aF 5 1 "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7"
..
.aF 1 5 "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7"
..


 0
..


..
 ERROR 3
 NAME
error - error and debug trace message formatter
 SYNOPSIS
.EX
#include <error.h>

Error_info_t error_info;

void error(int level, ...);
void errorv(const char* library, int level, va_alist args);
void liberror(const char* library, int level, ...);

#include <debug.h>

debug(statement)
message((int level, ...))
libmessage((const char* library, int level, ...))

 DESCRIPTION
.L error
is the error and debug trace message formatter.
 level is the severity level.
Messages with
 "level < error_info.trace" are suppressed.
 error_info.trace is initially
.LR 0 .
The remaining arguments are passed on to
.LR printf .
A
 newline is appended to the message text, so none should appear in the
.L printf
format.
If
 error_info.id is not
.L 0
then messages with
 "level > 0" are prefixed by
 error_info.id: .
Before the message text is output to standard error
it is passed to the function
.LR "char* ERROR_translate(const char* text, int flag)" .
By default
.L ERROR_translate
returns the
.L text
argument, but on some systems it may do language translation via lookup
on the original source text.
.RL ( error
calls
.L ERROR_translate
with a 0
.L flag
argument).

 level may be one of:

 <0 Negative values are for debug tracing.
Debug messages are prefixed with
 debug level. If
 "errno != error_info.last_errno" then
 error_info.last_errno is set to
 errno and the error text for errno is appended to the message.

 "ERROR_INFO [0]" Information only; no prefixes are added to the message.

 "ERROR_WARNING [1]" .L "warning:"
is added after
.L error_info.id
and
 error_info.warnings is incremented.

 "ERROR_ERROR [2]" (soft error)
 error_info.errors is incremented.

 ">= ERROR_FATAL [3]" (hard error)
 error_info.errors is incremented and
.L exit(level-2)
is called after the message is emitted.

 "ERROR_PANIC [77]" (unrecoverable internal error)
.L "panic:"
is added after
 error_info.id .
The following may be inclusive-or'd into
 level for alternate behavior:

.L ERROR_SYSTEM
The error text for
 errno is appended to the message.

.L ERROR_OUTPUT
The next argument is the file descriptor where the error message
should be emitted.

.L ERROR_SOURCE
Then next two arguments are a file name and line number that are added
to the message after
 error_info.id .
.L ERROR_USAGE
A usage message is emitted.

.L ERROR_PROMPT
The trailing
 newline is suppressed.

.L ERROR_NOID
The
 error_info.id prefix is suppressed.

.L ERROR_LIBRARY
The message is from a library routine.
 ENVIRONMENT
The elements of the global struct
 error_info control error output and actions.
Parts of
 error_info can be initialized from the
.L ERROR_OPTIONS
environment variable.
.L ERROR_OPTIONS
contains space separated
 name [ =value ] options, described below.

 "int core" If
 "error_info.core != 0" then
 "level >= error_info.core" generates a core dump.
Initialized by
.EX
ERROR_OPTIONS="core=level"

where
 level can be a number or one of
.LR error ,
.LR fatal ,
or
.LR panic .
 error_info.core is a handy way to get a stack trace at the exact point of error.

 "int error_info.trace" If
 "error_info.trace != 0" and
 "level < error_info.trace" then the error message text is suppressed.
.L exit()
may still be called if appropriate for
 level . Initialized by
.EX
ERROR_OPTIONS="trace=level"

where
 error_info.trace is set to the negative of
 level .
Library error messages, suppressed by default, are enabled by
.EX
ERROR_OPTIONS="library"

The system
 errno message text can be forced for each message by
.EX
ERROR_OPTIONS="system"

 "EXTENDED DESCRIPTION"
.L "<debug.h>"
provides debugging message macros when
.L DEBUG
or
.L _TRACE_
are defined
.RL ( _TRACE_
is defined by
 makerules when
.L CCFLAGS
contains
.LR -g ).
All of the macros expand to nothing when both
.L DEBUG
and
.L _TRACE_
are not defined.
Otherwise
.L debug
expands its arg and
.L libmessage
and
.L message
call
.L liberror
and
.L error
respectively if
 "error_info.trace<0" . Notice that
.L libmessage
and
.L message
are macro hacks that require double parentheses ((...)) around the
arguments.
 EXAMPLE
To enable debugging message level -3, library messages, and system
 errno text for all commands:
.EX
export ERROR_OPTIONS="trace=3 library system"