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

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

$1$2warning:warning:warning:warning:warning:warning:warning:warning: is added after $1$2error_info.iderror_info.iderror_info.iderror_info.iderror_info.iderror_info.iderror_info.iderror_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 $1$2exit(level-2)exit(level-2)exit(level-2)exit(level-2)exit(level-2)exit(level-2)exit(level-2)exit(level-2) is called after the message is emitted.

ERROR_PANIC [77]

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

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

$1$2ERROR_SYSTEMERROR_SYSTEMERROR_SYSTEMERROR_SYSTEMERROR_SYSTEMERROR_SYSTEMERROR_SYSTEMERROR_SYSTEM

The error text for errno is appended to the message.

$1$2ERROR_OUTPUTERROR_OUTPUTERROR_OUTPUTERROR_OUTPUTERROR_OUTPUTERROR_OUTPUTERROR_OUTPUTERROR_OUTPUT

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

$1$2ERROR_SOURCEERROR_SOURCEERROR_SOURCEERROR_SOURCEERROR_SOURCEERROR_SOURCEERROR_SOURCEERROR_SOURCE

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

$1$2ERROR_USAGEERROR_USAGEERROR_USAGEERROR_USAGEERROR_USAGEERROR_USAGEERROR_USAGEERROR_USAGE

A usage message is emitted.

$1$2ERROR_PROMPTERROR_PROMPTERROR_PROMPTERROR_PROMPTERROR_PROMPTERROR_PROMPTERROR_PROMPTERROR_PROMPT

The trailing newline is suppressed.

$1$2ERROR_NOIDERROR_NOIDERROR_NOIDERROR_NOIDERROR_NOIDERROR_NOIDERROR_NOIDERROR_NOID

The error_info.id prefix is suppressed.

$1$2ERROR_LIBRARYERROR_LIBRARYERROR_LIBRARYERROR_LIBRARYERROR_LIBRARYERROR_LIBRARYERROR_LIBRARYERROR_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 $1$2ERROR_OPTIONSERROR_OPTIONSERROR_OPTIONSERROR_OPTIONSERROR_OPTIONSERROR_OPTIONSERROR_OPTIONSERROR_OPTIONS environment variable. $1$2ERROR_OPTIONSERROR_OPTIONSERROR_OPTIONSERROR_OPTIONSERROR_OPTIONSERROR_OPTIONSERROR_OPTIONSERROR_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 $1$2errorerrorerrorerrorerrorerrorerrorerror $1$2fatalfatalfatalfatalfatalfatalfatalfatal or $1$2panicpanicpanicpanicpanicpanicpanicpanic 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. $1$2exit()exit()exit()exit()exit()exit()exit()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

$1$2<debug.h><debug.h><debug.h><debug.h><debug.h><debug.h><debug.h><debug.h> provides debugging message macros when $1$2DEBUGDEBUGDEBUGDEBUGDEBUGDEBUGDEBUGDEBUG or $1$2_TRACE__TRACE__TRACE__TRACE__TRACE__TRACE__TRACE__TRACE_ are defined $1$2(((((((( is defined by makerules when $1$2CCFLAGSCCFLAGSCCFLAGSCCFLAGSCCFLAGSCCFLAGSCCFLAGSCCFLAGS contains $1$2-g-g-g-g-g-g-g-g All of the macros expand to nothing when both $1$2DEBUGDEBUGDEBUGDEBUGDEBUGDEBUGDEBUGDEBUG and $1$2_TRACE__TRACE__TRACE__TRACE__TRACE__TRACE__TRACE__TRACE_ are not defined. Otherwise $1$2debugdebugdebugdebugdebugdebugdebugdebug expands its arg and $1$2libmessagelibmessagelibmessagelibmessagelibmessagelibmessagelibmessagelibmessage and $1$2messagemessagemessagemessagemessagemessagemessagemessage call $1$2liberrorliberrorliberrorliberrorliberrorliberrorliberrorliberror and $1$2errorerrorerrorerrorerrorerrorerrorerror respectively if error_info.trace<0. Notice that $1$2libmessagelibmessagelibmessagelibmessagelibmessagelibmessagelibmessagelibmessage and $1$2messagemessagemessagemessagemessagemessagemessagemessage 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"