--- name: "strerror" section: "3" platform: "linux" package: "man-pages" version: "6.19-1" release: "Arch Linux 2026-11-01" platforms: ["linux", "freebsd", "macos"] url: "https://new.carta.tech/strerror" --- # strerror(3) string error-string ## NAME strerror, strerrorname\_np, strerrordesc\_np, strerror\_r, strerror\_l - string error-string ## LIBRARY Standard C library (*libc*, *-lc*) ## SYNOPSIS ``` #include ``` **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 (see [**feature\_test\_macros**(7)](/feature_test_macros/7.md)): **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 The **strerror**() function returns a pointer to a string that describes the error code passed in the argument *errnum*, possibly using the **LC\_MESSAGES** part of the current locale to select the appropriate language. (For example, if *errnum* is **EINVAL**, the returned description will be "Invalid argument".) This string must not be modified by the application, and the returned pointer will be invalidated on a subsequent call to **strerror**() or **strerror\_l**(), or if the thread that obtained the string exits. No other library function, including [**perror**(3)](/perror/3.md), will modify this string. Like **strerror**(), the **strerrordesc\_np**() function returns a pointer to a string that describes the error code passed in the argument *errnum*, with the difference that the returned string is not translated according to the current locale. The **strerrorname\_np**() function returns a pointer to a string containing the name of the error code passed in the argument *errnum*. For example, given **EPERM** as an argument, this function returns a pointer to the string "EPERM". Given **0** as an argument, this function returns a pointer to the string "0". ### strerror\_r() **strerror\_r**() is like **strerror**(), but might use the supplied buffer *buf* instead of allocating one internally. This function is available in two versions: an XSI-compliant version specified in POSIX.1-2001 (available since glibc 2.3.4, but not POSIX-compliant until glibc 2.13), and a GNU-specific version (available since glibc 2.0). The XSI-compliant version is provided with the feature test macros settings shown in the SYNOPSIS; otherwise the GNU-specific version is provided. 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 that the XSI-compliant version of **strerror\_r**() is provided by default. The XSI-compliant **strerror\_r**() is preferred for portable applications. It returns the error string in the 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 that the function stores in *buf*, or a pointer to some (immutable) static string (in which case *buf* is unused). If the function stores a string in *buf*, then at most *size* bytes are stored (the string may be truncated if *size* is too small and *errnum* is unknown). The string always includes a terminating null byte ('\\0'). ### strerror\_l() **strerror\_l**() is like **strerror**(), but maps *errnum* to a locale-dependent error message in the locale specified by *locale*. The behavior of **strerror\_l**() is undefined if *locale* is the special locale object **LC\_GLOBAL\_LOCALE** or is not a valid locale object handle. ## RETURN VALUE The **strerror**(), **strerror\_l**(), and the GNU-specific **strerror\_r**() functions return the appropriate error description string, or an "Unknown error nnn" message if the error number is unknown. On success, **strerrorname\_np**() and **strerrordesc\_np**() return the appropriate error description string. If *errnum* is an invalid error number, these functions return NULL. The XSI-compliant **strerror\_r**() function returns 0 on success. On error, a (positive) error number is returned (since glibc 2.13), or -1 is returned and *errno* is set to indicate the error (before glibc 2.13). POSIX.1-2001 and POSIX.1-2008 require that a successful call to **strerror**() or **strerror\_l**() shall leave *errno* unchanged, and 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. ## 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)](/attributes/7.md). | | | | | --- | --- | --- | | **Interface** | **Attribute** | **Value** | | **strerror**() | Thread safety | MT-Safe | | **strerrorname\_np**(), **strerrordesc\_np**() | Thread safety | MT-Safe | | **strerror\_r**(), **strerror\_l**() | Thread safety | MT-Safe | Before glibc 2.32, **strerror**() is not MT-Safe. ## STANDARDS - **strerror**() C11, POSIX.1-2008. - **strerror\_r**() **strerror\_l**() POSIX.1-2008. - **strerrorname\_np**() **strerrordesc\_np**() GNU. POSIX.1-2001 permits **strerror**() to set *errno* if the call encounters an error, but 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. ## HISTORY - **strerror**() POSIX.1-2001, C89. - **strerror\_r**() POSIX.1-2001. - **strerror\_l**() glibc 2.6. POSIX.1-2008. - **strerrorname\_np**() **strerrordesc\_np**() glibc 2.32. ## NOTES **strerrorname\_np**() and **strerrordesc\_np**() are thread-safe and async-signal-safe. ## SEE ALSO [**err**(3)](/err/3.md), [**errno**(3)](/errno/3.md), [**error**(3)](/error/3.md), [**perror**(3)](/perror/3.md), [**strsignal**(3)](/strsignal/3.md), [**locale**(7)](/locale/7.md), [**signal-safety**(7)](/signal-safety/7.md)