errc(3bsd)

💖 errc, verrc, warnc, vwarnc — formatted error messages 💖

okay bestie, so this is errc(3bsd), a little page from the BSD corner of your system (it lives under LOCAL in the manual shelf, if you were wondering) and it's literally the "tell me what went wrong, but make it formatted" squad 🫶

---

🌸 LIBRARY 🌸

Utility functions from BSD systems — that's libbsd, and you link it with -lbsd. ✨

---

✨ SYNOPSIS ✨

#include <err.h>

(peep libbsd(7) for how the include situation actually works, iykyk)

void
errc(int status, int code, const char *fmt, ...);

void
verrc(int status, int code, const char *fmt, va_list args);

void
warnc(int code, const char *fmt, ...);

void
vwarnc(int code, const char *fmt, va_list args);

---

💅 DESCRIPTION 💅

So the err() and warn() family of functions print a formatted error message out on standard error output. Every single one of them, no exceptions. And in all cases, they start you off with the last component of the program name, then a colon (:) character, then a space. Iconic little intro, honestly. 🎀

What comes after that depends on which function you called, bestie. The fmt specification — plus whatever arguments come with it — can be any format that printf(3) allows, or it can be NULL. If fmt is not NULL, then yeah, the formatted error message gets printed.

Now here's the tea: all of these functions also print an error message string that's affiliated with an error value (go look at strerror(3) if you want the lore on that one). That string gets preceded by a colon character and a space — but only if fmt is not NULL. So the output looks like this:

progname: fmt: error message string

when fmt is not NULL, or like this:

progname: error message string

when it is. 🦋

The code argument is used as the error value instead of whatever the global variable errno is currently holding. Not me swapping out errno's whole moment. 😭

And in all cases, the output gets a newline character tacked on at the end. Periodt.

Oh, and heads up: errc() and verrc() do not return. They exit with the value of the status argument. They're not coming back, they said what they said. 💀

---

🌈 EXAMPLES 🌈

Display the current errno information string and exit:

if ((p = malloc(size)) == NULL)
        err(1, NULL);
if ((fd = open(file_name, O_RDONLY, 0)) == -1)
        err(1, "%s", file_name);

Display an error message and exit:

if (tm.tm_hour < START_TIME)
        errx(1, "too early, wait until %s", start_time_string);

Warn of an error:

if ((fd = open(raw_device, O_RDONLY, 0)) == -1)
        warnx("%s: %s: trying the block device",
            raw_device, strerror(errno));
if ((fd = open(block_device, O_RDONLY, 0)) == -1)
        err(1, "%s", block_device);

---

👑 SEE ALSO 👑

err(3) exit(3), perror(3), printf(3), strerror(3)

---

🎀 HISTORY 🎀

The functions errc(), verrc(), warnc(), and vwarnc() first appeared in FreeBSD 3.0, NetBSD 7.0 and OpenBSD 5.6. They've been around, they've got seniority. ⭐

---

⚠️ CAVEATS ⚠️

bestie. listen. this part is not a vibe. this part is serious. 🚨

It is important — like, never-ever — to pass a string with user-supplied data as a format without using %s. Why? Because an attacker can put format specifiers in that string and mangle the stack, which leads to a possible security hole. And this holds true even if the string has been built "by hand" using a function like snprintf(), because the resulting string may still contain user-supplied conversion specifiers that get interpolated later by the err() and warn() family of functions. So yes, the danger is still lurking in there. 🙈

Always be sure to use the proper secure idiom:

errc(1, 0, "%s", string);

That's the one. That's the safe one. Use that one. 💜

---

and that's the whole page, bestie!! this one shipped with Debian, dated April 23, 2014 — go forth and format your errors securely, mwah 💅✨