Updated: 2022/Sep/29

Please read Privacy Policy. It's for your privacy.

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.

NetBSD 10.99                     April 4, 2020                    NetBSD 10.99