xref: /titanic_51/usr/src/lib/libast/common/man/error.3 (revision ab5c384599c214af20872d1d5b10cfd4c6486116)
.fp 5 CW .. .nr ;G \\n(.f .Af "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7" "\\$8" "\\$9" \\*(;G .. .aF 5 \\n(.f "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7" .. .aF 5 1 "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7" .. .aF 1 5 "\\$1" "\\$2" "\\$3" "\\$4" "\\$5" "\\$6" "\\$7" ..

0

..

..

ERROR 3
NAME
error - error and debug trace message formatter
SYNOPSIS
.EX #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
.L 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 .LR 0 . The remaining arguments are passed on to .LR printf . A newline is appended to the message text, so none should appear in the .L printf format. If error_info.id is not .L 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 .LR "char* ERROR_translate(const char* text, int flag)" . By default .L ERROR_translate returns the .L text argument, but on some systems it may do language translation via lookup on the original source text. .RL ( error calls .L ERROR_translate with a 0 .L flag argument).

level may be one of:

<0 Negative values are for debug tracing. Debug messages are prefixed with debug level. 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]" .L "warning:" is added after .L 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 .L exit(level-2) is called after the message is emitted.

"ERROR_PANIC [77]" (unrecoverable internal error) .L "panic:" is added after error_info.id .

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

.L ERROR_SYSTEM The error text for errno is appended to the message.

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

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

.L ERROR_USAGE A usage message is emitted.

.L ERROR_PROMPT The trailing newline is suppressed.

.L ERROR_NOID The error_info.id prefix is suppressed.

.L 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 .L ERROR_OPTIONS environment variable. .L 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 .EX ERROR_OPTIONS="core=level" where level can be a number or one of .LR error , .LR fatal , or .LR 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. .L exit() may still be called if appropriate for level . Initialized by .EX ERROR_OPTIONS="trace=level" where error_info.trace is set to the negative of level .

Library error messages, suppressed by default, are enabled by .EX ERROR_OPTIONS="library" The system errno message text can be forced for each message by .EX ERROR_OPTIONS="system"

"EXTENDED DESCRIPTION"
.L "<debug.h>" provides debugging message macros when .L DEBUG or .L _TRACE_ are defined .RL ( _TRACE_ is defined by makerules when .L CCFLAGS contains .LR -g ). All of the macros expand to nothing when both .L DEBUG and .L _TRACE_ are not defined. Otherwise .L debug expands its arg and .L libmessage and .L message call .L liberror and .L error respectively if "error_info.trace<0" . Notice that .L libmessage and .L 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: .EX export ERROR_OPTIONS="trace=3 library system"