--- name: "error" section: "3" platform: "macos" package: "ksh" version: "42" release: "macOS 26.5" platforms: ["linux", "macos"] url: "https://new.carta.tech/error/3" --- # error(3) error and debug trace message formatter ## NAME error - error and debug trace message formatter ## SYNOPSIS ``` #include 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(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 **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\]** $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\\\\\\\\ 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" ```