error.3

Introduction to Library Functions                        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  ini-
     tially  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 trans-
     lation 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.

SunOS 5.10                Last change:                          1

Introduction to Library Functions                        ERROR(3)

     >= 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

SunOS 5.10                Last change:                          2

Introduction to Library Functions                        ERROR(3)

          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 liber-
     ror  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"

SunOS 5.10                Last change:                          3

Generated by GNU enscript 1.6.4.