ERROR(3ast)

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
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 The remaining arguments are passed on to A newline is appended to the message text, so none should appear in the format. If error_info.id is not 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 By default returns the argument, but on some systems it may do language translation via lookup on the original source text. calls with a 0 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]
    is added after 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 is called after the message is emitted.

ERROR_PANIC [130]
    (unrecoverable internal error) is added after error_info.id.

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

The error text for
    errno is appended to the message.

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

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

A usage message is emitted.

The trailing
    newline is suppressed.

The error_info.id prefix is suppressed.

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 environment variable. 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 or 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. 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
provides debugging message macros when or are defined is defined by the Mamfiles when the a.k.a. option is passed to mamake(1), which the package(1) command does automatically when given the argument All of the macros expand to nothing when both and are not defined. Otherwise expands its arg and and call and respectively if error_info.trace<0. Notice that and 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"