ERROR(3)C LIBRARY FUNCTIONSERROR(3)

NAME

error - error and debug trace message formatter

SYNOPSIS

#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

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 0. The remaining arguments are passed on to printf. A newline is appended to the message text, so none should appear in the printf format. If error_info.id is not 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 char* ERROR_translate(const char* text, int flag). By default ERROR_translate returns the text argument, but on some systems it may do language translation via lookup on the original source text. (error calls ERROR_translate with a 0 flag argument).

level may be one of:

<0
Negative values are for debug tracing. Debug messages are prefixed with debuglevel. 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]

warning: is added after 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 exit(level-2) is called after the message is emitted.
ERROR_PANIC [77]

(unrecoverable internal error) panic: is added after error_info.id.

The following may be inclusive-or'd into level for alternate behavior:

ERROR_SYSTEM

The error text for errno is appended to the message.
ERROR_OUTPUT

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

Then next two arguments are a file name and line number that are added to the message after error_info.id.
ERROR_USAGE

A usage message is emitted.
ERROR_PROMPT

The trailing newline is suppressed.
ERROR_NOID

The error_info.id prefix is suppressed.
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 ERROR_OPTIONS environment variable. 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 
ERROR_OPTIONS="core=level"
where level can be a number or one of error, fatal, or 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. exit() may still be called if appropriate for level. Initialized by 
ERROR_OPTIONS="trace=level"
where error_info.trace is set to the negative of level.

Library error messages, suppressed by default, are enabled by 

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

EXTENDED DESCRIPTION

<debug.h> provides debugging message macros when DEBUG or _TRACE_ are defined (_TRACE_ is defined by makerules when CCFLAGS contains -g). All of the macros expand to nothing when both DEBUG and _TRACE_ are not defined. Otherwise debug expands its arg and libmessage and message call liberror and error respectively if error_info.trace<0. Notice that libmessage and 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: 
export ERROR_OPTIONS="trace=3 library system"

November 07, 2006