perror(3) - NetBSD Manual Pages

Command:
Section:
Arch:
Collection:
>>>
STRERROR(3)             NetBSD 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 cur-
     rent value of the global variable errno (intro(2)) and writes it, fol-
     lowed by a newline, to the standard error file descriptor.  If the argu-
     ment 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 func-
     tions 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 num-
     ber 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 depre-
     cated; 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 cur-
     rent 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