COM_ERR(3)

💖 COM_ERR — the common error display routine 💖

okay bestie, sit down, hydrate, and let me tell you about com_err from section 3 of the library functions manual. this is the girl who prints your error messages. she's been doing it since 1988 and she has never once missed. ✨

🌸 SYNOPSIS 🌸

#include <et/com_err.h>
void (*proc) (const char *, long, const char *, va_list);

void com_err (const char *whoami, long code, const char *format, ...);

proc = set_com_err_hook (proc);

proc = reset_com_err_hook ();

void initialize_XXXX_error_table ();

🎀 DESCRIPTION 🎀

So. What does com_err actually do? She displays an error message on the standard error stream stderr — and yes, that's the one from stdio(3S), iykyk. The message she cooks up is literally a three-course meal:

1. the whoami string — that's the program name, or some subportion of the program, whatever you're calling yourself today 💅
2. an error message generated from the code value — and that code comes straight from compile_et(1), no cap
3. a string produced using the format string plus any following arguments, in the exact same style as fprintf(3)

she's giving printf but make it an error. iconic.

✨ changing her whole vibe: hooks ✨

The behavior of com_err can be modified using set_com_err_hook. What this does is define a procedure that gets called with the arguments passed to com_err — instead of the default internal procedure, the one that just sends the formatted text to error output. So basically you can reroute all your error messages to another form of diagnostic logging, like syslog(3), and honestly? slay.

reset_com_err_hook is the undo button — it restores the behavior of com_err back to its default form. 🫶

Both of these procedures return the previous "hook" value, so you can stack them like the little diva they are. And heads up: these "hook" procedures must have the declaration given for proc up in the synopsis. no freestyling, bestie, the compiler will know.

🦋 the initialize_XXXX_error_table routine 🦋

The initialize_XXXX_error_table routine is generated mechanically by compile_et(1) from a source file containing names and associated strings. Each table has a name of up to four characters, and that name gets used in place of the XXXX in the name of the routine. 🎀

⚠️ You should call these routines before any of the corresponding error codes are used — otherwise the com_err library won't recognize error codes from these tables when they show up. don't do it late, it's not cute.

💜 the include + link situation 💜

The com_err.h header file should be included in any source file that uses routines from the com_err library. And your executable files? They must be linked using -lcom_err in order to cause the com_err library to be included. like, mandatory. periodt.

-lcom_err

🌈 SEE ALSO 🌈

• compile_et (1) — the girl who generates your error tables
• syslog (3) — the other place your errors can go live

Also, shoutout to Ken Raeburn, author of "A Common Error Description Library for UNIX" — the blueprint, the blueprint. 👑

com_err, from section 3 of the library functions manual, brought to you by SIPB, dated 22 Nov 1988. yes she's old enough to be your mom and she still ate. 💅✨🫶