perror.3c (2010 09)

p
perror(3C) perror(3C)
NAME
perror(), strerror(), strerror_r() - write system error messages
SYNOPSIS
#include <stdio.h>
void perror(const char *s);
#include <string.h>
char *strerror(int errnum);
#include <errno.h>
extern char *sys_errlist[ ];
extern int sys_nerr;
#include <string.h>
int strerror_r(int errnum, char *buffer, size_t buflen);
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 newline character. 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 symbol
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 newline character.
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 newline character. errno can be used as an index into sys_errlist to get an
untranslated message string without the newline character. 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.
The
strerror_r() function maps the error number in errnum to a locale-dependent error message
string and returns the string in the buffer pointed to by buffer, which has length buflen.
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 mes-
sage 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.
Upon successful completion,
strerror_r() returns 0. Otherwise, an error number is returned to indi-
cate the error.
ERRORS
If the
strerror_r() function fails, it will return one of the following errors:
[EINVAL] The value of errnum is not a valid error number.
HP-UX 11i Version 3: September 2010 − 1 − Hewlett-Packard Company 1