strerror(3)

📦

version 6.20 · 15 versions

👑 strerror, strerrorname_np, strerrordesc_np, strerror_r, strerror_l 💅

okay so welcome to strerror(3), lovingly ripped from the Library Functions Manual, and it's giving "the entire friend group that turns a chaotic little error number into actual words." bestie, they all do the same vibe, just with different ✨personalities✨.

🌸 NAME 🌸

strerror, strerrorname_np, strerrordesc_np, strerror_r, strerror_l — string error-string

📚 LIBRARY 📚

Standard C library (libc, -lc). that's the one, no cap 🫶

✨ SYNOPSIS ✨

#include <string.h>

char *strerror(int errnum);
const char *strerrorname_np(int errnum);
const char *strerrordesc_np(int errnum);

int strerror_r(size_t size;
               int errnum, char buf[size], size_t size);
               /* XSI-compliant */

char *strerror_r(size_t size;
               int errnum, char buf[size], size_t size);
               /* GNU-specific */

char *strerror_l(int errnum, locale_t locale);

🧚 Feature Test Macro Requirements for glibc

(peep feature_test_macros(7) for the tea, bestie)

strerrorname_np(), strerrordesc_np():

_GNU_SOURCE

strerror_r():

The XSI-compliant version is provided if:
    (_POSIX_C_SOURCE >= 200112L) && ! _GNU_SOURCE
Otherwise, the GNU-specific version is provided.

💖 DESCRIPTION 💖

so strerror() hands you back a pointer to a string that describes whatever error code you passed in as errnum — and yes, it might use the LC_MESSAGES part of your current locale to pick the right language. (like, if errnum is EINVAL, the description it gives you is "Invalid argument". iconic.) 💅

careful though: your app must not modify this string, and that returned pointer gets invalidated on a subsequent call to strerror() or strerror_l(), OR if the thread that grabbed the string just… exits. 💀 no other library function — including perror(3) — will touch this string.

Like strerror(), the strerrordesc_np() function returns a pointer to a string that describes the error code passed in the argument errnum, but with one glow-up difference: the returned string is not translated according to the current locale. so it's the no-makeup version, fr fr.

The strerrorname_np() function returns a pointer to a string containing the name of the error code passed in the argument errnum. for example, hand it EPERM and you get back a pointer to the string "EPERM". hand it 0 and — plot twist 🌈 — you get back a pointer to the string "0".

🍓 strerror_r()

strerror_r() is like strerror(), but it might use the buffer you supplied (buf) instead of allocating one internally. little miss independent ✨

and there are two versions of her:

XSI-compliant version — specified in POSIX.1-2001 (available since glibc 2.3.4, but not POSIX-compliant until glibc 2.13)
GNU-specific version — available since glibc 2.0

you get the XSI-compliant one when the feature test macros are set up like in the SYNOPSIS; otherwise it's GNU-specific that shows up. and if no feature test macros are explicitly defined, then (since glibc 2.4) _POSIX_C_SOURCE is defined by default with the value 200112L, so the XSI-compliant version of strerror_r() is what you get by default. slay, defaults. 🎀

The XSI-compliant strerror_r() is the one you want for portable applications — periodt. it returns the error string in your user-supplied buffer buf of size size.

The GNU-specific strerror_r() returns a pointer to a string containing the error message. this may be either a pointer to a string the function stores in buf, or a pointer to some (immutable) static string — in which case buf is just sitting there unused, ignored, unbothered 🙈. if the function does store a string in buf, then at most size bytes are stored (and yeah, the string may get truncated if size is too small and errnum is unknown). the string always includes a terminating null byte ('\0'). always, bestie.

🌈 strerror_l()

strerror_l() is like strerror(), but it maps errnum to a locale-dependent error message in the locale specified by locale.

⚠️ undefined behaviour alert: the behavior of strerror_l() is undefined if locale is the special locale object LC_GLOBAL_LOCALE, or if it isn't a valid locale object handle. don't do it. i'm begging. 😭

🫶 RETURN VALUE 🫶

strerror(), strerror_l(), and the GNU-specific strerror_r() return the appropriate error description string — or, if the error number is unknown, an "Unknown error nnn" message. that's the fallback fit, and it ate. 💅

On success, strerrorname_np() and strerrordesc_np() return the appropriate error description string. but if errnum is an invalid error number, these functions return NULL. 💀

The XSI-compliant strerror_r() function returns 0 on success. on error, it returns a (positive) error number (since glibc 2.13) — or, before glibc 2.13, it returned -1 and set errno to indicate the error.

POSIX.1-2001 and POSIX.1-2008 require that a successful call to strerror() or strerror_l() shall leave errno unchanged, and they note that — since no function return value is reserved to indicate an error — an application that wishes to check for errors should initialize errno to zero before the call, and then check errno after the call. that's the whole strategy. write it down. 📝

💀 ERRORS 💀

EINVAL — The value of errnum is not a valid error number.
ERANGE — Insufficient storage was supplied to contain the error description string.

🎀 ATTRIBUTES 🎀

for an explanation of the terms used in this section, see attributes(7).

strerror() — Thread safety: MT-Safe
strerrorname_np(), strerrordesc_np() — Thread safety: MT-Safe
strerror_r(), strerror_l() — Thread safety: MT-Safe

throwback: Before glibc 2.32, strerror() is not MT-Safe. so if you're on ancient glibc, tread lightly, queen. 🙈

⭐ STANDARDS ⭐

strerror()

C11, POSIX.1-2008.

strerror_r(), strerror_l()

POSIX.1-2008.

strerrorname_np(), strerrordesc_np()

GNU.

also, the lore: POSIX.1-2001 permits strerror() to set errno if the call encounters an error, but it does not specify what value should be returned as the function result in the event of an error. on some systems, strerror() returns NULL if the error number is unknown. on other systems, strerror() returns a string something like "Error nnn occurred" and sets errno to EINVAL if the error number is unknown. C99 and POSIX.1-2008 require the return value to be non-NULL. so… systems differ, bestie. iykyk. 🌈

🦋 HISTORY 🦋