ERROR(3)

💖 ERROR(3) 💖

okay so bestie, this is the ERROR(3) page from the Library Functions Manual, and it’s literally the error and debug trace message formatter. group-chat energy: ON. 🫶

✨ NAME ✨

• error — error and debug trace message formatter. that’s the whole name section, icon behavior only. 💅

📚 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 🌸

okay so error is the error and debug trace message formatter, and 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:. yes, colon included, we don’t make the rules. 💅

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). cute.

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.
• >= 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 — the 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: 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"

---

xoxo, bestie 💖 — that was ERROR(3) from the Library Functions Manual. the footer didn’t print a version or date, so no cap, we’re not inventing one. stay slay. 💅