perror(3C) perror(3C) NAME perror(), strerror(), strerror_r(), errno, sys_errlist, sys_nerr - system error messages SYNOPSIS #include <errno.h> void perror(const char *s); char *strerror(int errnum); int strerror_r(int errnum, char *buffer, int buflen); extern int errno; extern char *sys_errlist[]; extern int sys_nerr; DESCRIPTION perror() writes a language-dependent message to the standard error output, describing the last error encountered during a call to a system or library function. The argument string s is printed first, followed by a colon, a blank, the message, and a new-line. To be most useful, the argument string should include the name of the program that incurred the error. The error number is taken from the external variable errno, which is set when errors occur but not cleared when non-erroneous calls are made. The contents of the message is identical to those returned by the strerror() function with errno as the argument. If given a NULL string, the perror() function prints only the message and a new-line. To simplify variant formatting of messages, the strerror() function and the sys_errlist array of message strings are provided. The strerror() function maps the error number in errnum to a language- dependent error message string and returns a pointer to the string. The message string is returned without a new-line. errno can be used as an index into sys_errlist to get an untranslated message string without the new-line. sys_nerr is the largest message number provided for in the table; it should be checked because new error codes might be added to the system before they are added to the table. strerror() must be used to retrieve messages when translations are desired. strerror_r() is identical to strerror(), except that the result string is passed back in the supplied buffer. A buffer length of 80 is recommended. If an error is detected or the buffer is of insufficient length, -1 is returned. If the operation is successful, 0 is returned. EXTERNAL INFLUENCES Environment Variables The language of the message returned by strerror() and printed by perror() is specified by the LANG environment variable. If the language-dependent message is not available, or if LANG is not set or is set to the empty string, the default version of the message associated with the "C" language (see lang(5)) is used. International Code Set Support Single- and multi-byte character code sets are supported. RETURN VALUE perror() returns no value. If the errnum message number is valid, strerror() returns a pointer to a language-dependent message string. The array pointed to should not be modified by the program, and might be overwritten by a subsequent call to the function. If a valid errnum message number does not have a corresponding language-dependent message, strerror() uses errnum as an index into sys_errlist to get the message string. If the errnum message number is invalid, strerror() returns a pointer to a NULL string. WARNINGS The return value for strerror() points to static data whose content is overwritten by each call. strerror() is unsafe for multi-thread applications. strerror_r() is MT-Safe and should be used instead. SEE ALSO errno(2), lang(5), environ(5). STANDARDS CONFORMANCE perror(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C strerror(): AES, SVID3, XPG3, XPG4, ANSI C sys_errlist(): SVID2, SVID3, XPG2 sys_nerr(): SVID2, SVID3, XPG2 Hewlett-Packard Company - 2 - HP-UX Release 10.20: July 1996