STRERROR(3)

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

# NAME

`perror`, `strerror`, `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);

# DESCRIPTION

The `strerror`(), `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 `strerror_r`() function renders the same result into strerrbuf for a maximum of buflen characters and returns 0 upon success.

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 pass an error message string containing “`Unknown error:` ” followed by the error number in decimal. To warn about this, `strerror`() sets `errno` to `EINVAL`, and `strerror_r`() returns `EINVAL`. 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.

The 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; `strerror`() or `strerror_r`() should be used instead.

# 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”).

# 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.

# BUGS

For unknown error numbers, the `strerror`() function will return its result in a static buffer which may be overwritten by subsequent calls.

The return type for `strerror`() is missing a type-qualifier; it should actually be const char *.

Programs that use the deprecated sys_errlist variable often fail to compile because they declare it inconsistently.

May 9, 2015 | NetBSD 9.0