STRERROR(3)

STRERROR(3) | Library Functions Manual | STRERROR(3)

# NAME

`perror`, `strerror`, `strerror_l`, `strerror_r`, `sys_errlist`, `sys_nerr` —
system error messages

# LIBRARY

Standard C Library (libc, -lc)

# SYNOPSIS

`#include <stdio.h>`

void
`perror`(const char *string);

`#include <errno.h>`

extern const char * const sys_errlist[];
extern const int sys_nerr;

`#include <string.h>`

char *
`strerror`(int errnum);

int
`strerror_r`(int errnum, char *strerrbuf, size_t buflen);

char *
`strerror_l`(int errnum, locale_t loc);

# DESCRIPTION

The `strerror`(), `strerror_l`(), `strerror_r`(), and `perror`() functions look up the language-dependent error message string corresponding to an error number.

The `strerror`() function accepts an error number argument errnum and returns a pointer to the corresponding message string. The application should not attempt to modify the returned string, it may be shared, or read only.

The `strerror_r`() function renders the same result into strerrbuf for a maximum of buflen characters (including terminator) and returns 0 upon success.

The `strerror_l`() function is like `strerror`() but provides in loc the locale to be used to obtain the language for the message, rather than using the application's current locale.

The `perror`() function finds the error message corresponding to the current value of the global variable errno (intro(2)) and writes it, followed by a newline, to the standard error file descriptor. If the argument string is non-`NULL` and does not point to the nul character, this string is prepended to the message string and separated from it by a colon and space (“`:` ”); otherwise, only the error message string is printed. Note that in most cases the err(3) and warn(3) family of functions is preferable to `perror`(); they are more flexible and also print the program name.

If the error number is not recognized, these functions return an error message string containing “`Unknown error:` ” followed by the error number in decimal. To warn about this, `strerror`() and `strerror_l`() set `errno` to `EINVAL`, and `strerror_r`() returns `EINVAL`. In other cases, except where noted below, `errno` is not altered, so applications should set it to a known value (usually zero) before calling either `strerror`() or `strerror_l`() if the resulting value in `errno` is to be tested for this condition. Error numbers recognized by this implementation fall in the range 0 < errnum < sys_nerr.

If insufficient storage is provided in strerrbuf (as specified in buflen) to contain the error string, `strerror_r`() returns `ERANGE` and strerrbuf will contain an error message that has been truncated and `NUL` terminated to fit the length specified by buflen. In extraordinary cases, it is possible that the internal buffer used by `strerror`() and `strerror_l`() may be too small for a translated message, in which case it will be truncated as indicated for `strerror_r`() and `errno` will be set to `ERANGE`.

The POSIX locale message strings can be accessed directly using the external array sys_errlist. The external value sys_nerr contains a count of the messages in sys_errlist. The use of these variables is deprecated; one of the `strerror`() family of functions should be used instead.

# COMPATIBILITY

Programs that attempt to use the deprecated sys_errlist variable often fail to compile because they provide their own, inconsistent, declaration of it. Such programs should be updated to use `strerror`().

# ERRORS

These functions may fail if:

[`EINVAL`]
  The error number was out of range.
[`ERANGE`]
  The string buffer supplied was not large enough to hold the complete error message.

# SEE ALSO

intro(2), err(3), psignal(3), warn(3)

# STANDARDS

The `perror`() and `strerror`() functions conform to ISO/IEC 9899:1999 (“ISO C99”). The `strerror_r`() function conforms to IEEE Std 1003.1-2001 (“POSIX.1”). The `strerror_l`() function conforms to IEEE Std 1003.1-2008 (“POSIX.1”).

# HISTORY

The `perror`() function first appeared in Version 4 AT&T UNIX. The `strerror`() function first appeared in 4.3BSD-Reno. The `strerror_r`() function first appeared in NetBSD 4.0. The `strerror_l`() function was first released in NetBSD 7.0.

# BUGS

The `strerror`() function may return its result in a static buffer which will be overwritten by subsequent calls. For portable use, this must be assumed to be a subsequent call from the current, or any other, thread in the process. This implementation limits the issue to calls from the current thread. The `strerror_l`() function has a similar restriction, but even in other implementations, is required to use thread local storage, so only other calls from the calling thread can overwrite the result. Both `strerror`() and `strerror_l`() use the same thread local storage; a call to either will destroy the result from an earlier call by the same thread of either of them.

April 4, 2020 | NetBSD 10.1