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