ERROR(3ast) ERROR(3ast)

# [NAME](#NAME)

error - error and debug trace message formatter

# [SYNOPSIS](#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](#DESCRIPTION)

error is the error and debug trace message formatter. *level* is the severity level. Messages with *level &lt; 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 &gt; 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:

**&lt;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\]**](#ERROR_INFO)

Information only; no prefixes are added to the message.

[**ERROR\_WARNING \[1\]**](#ERROR_WARNING)

warning: is added after error\_info.id and *error\_info.warnings* is incremented.

[*ERROR\_ERROR \[2\]*](#ERROR_ERROR)

(soft error) *error\_info.errors* is incremented.

**&gt;= ERROR\_FATAL \[3]**

(hard error) *error\_info.errors* is incremented and exit(*level*-2) is called after the message is emitted.

[**ERROR\_PANIC \[130\]**](#ERROR_PANIC)

(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](#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*](#int)

If *error\_info.core != 0* then *level &gt;= 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*](#int~2)

If *error\_info.trace != 0* and *level &lt; 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](#EXTENDED_DESCRIPTION)

&lt;debug.h&gt; provides debugging message macros when DEBUG or \_BLD\_DEBUG are defined (\_BLD\_DEBUG is defined by the *Mamfile*s when the -G a.k.a. --debug-symbols option is passed to [**mamake**(1)](/man/os/ksh/mamake.1), which the [**package**(1)](/man/os/ksh/package.1) command does automatically when given the argument debug=1). All of the macros expand to nothing when both DEBUG and \_BLD\_DEBUG are not defined. Otherwise debug expands its arg and libmessage and message call liberror and error respectively if *error\_info.trace&lt;0*. Notice that libmessage and message are macro hacks that require double parentheses ((...)) around the arguments.

# [EXAMPLE](#EXAMPLE)

To enable debugging message level -3, library messages, and system *errno* text for all commands:

```
export ERROR_OPTIONS="trace=3 library system"
```

---

Document: error(3ast) from ksh 1.0.10-r37 (Chainguard OS)
Source: https://github.com/ksh93/ksh