Scroll to navigation

ERROR(3) Library Functions Manual ERROR(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.
Information only; no prefixes are added to the message.
warning: is added after error_info.id and error_info.warnings is incremented.
(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.
(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.

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.
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"