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  pre-
              fixed  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 paren-
       theses ((...)) 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"

                                                                      ERROR(3)