newlib/libc/string/strerror_r.c

   1 /* GNU variant of strerror_r. */
   2 /*
   3 FUNCTION
   4         <<strerror_r>>---convert error number to string and copy to buffer
   5
   6 INDEX
   7         strerror_r
   8
   9 SYNOPSIS
  10         #include <string.h>
  11         #ifdef _GNU_SOURCE
  12         char *strerror_r(int <[errnum]>, char *<[buffer]>, size_t <[n]>);
  13         #else
  14         int strerror_r(int <[errnum]>, char *<[buffer]>, size_t <[n]>);
  15         #endif
  16
  17 DESCRIPTION
  18 <<strerror_r>> converts the error number <[errnum]> into a
  19 string and copies the result into the supplied <[buffer]> for
  20 a length up to <[n]>, including the NUL terminator. The value of
  21 <[errnum]> is usually a copy of <<errno>>.  If <<errnum>> is not a known
  22 error number, the result is the empty string.
  23
  24 See <<strerror>> for how strings are mapped to <<errnum>>.
  25
  26 RETURNS
  27 There are two variants: the GNU version always returns a NUL-terminated
  28 string, which is <[buffer]> if all went well, but which is another
  29 pointer if <[n]> was too small (leaving <[buffer]> untouched).  If the
  30 return is not <[buffer]>, your application must not modify that string.
  31 The POSIX version returns 0 on success, <[EINVAL]> if <<errnum>> was not
  32 recognized, and <[ERANGE]> if <[n]> was too small.  The variant chosen
  33 depends on macros that you define before inclusion of <<string.h>>.
  34
  35 PORTABILITY
  36 <<strerror_r>> with a <[char *]> result is a GNU extension.
  37 <<strerror_r>> with an <[int]> result is required by POSIX 2001.
  38 This function is compliant only if <<_user_strerror>> is not provided,
  39 or if it is thread-safe and uses separate storage according to whether
  40 the second argument of that function is non-zero.  For more details
  41 on <<_user_strerror>>, see the <<strerror>> documentation.
  42
  43 POSIX states that the contents of <[buf]> are unspecified on error,
  44 although this implementation guarantees a NUL-terminated string for
  45 all except <[n]> of 0.
  46
  47 POSIX recommends that unknown <[errnum]> result in a message including
  48 that value, however it is not a requirement and this implementation
  49 provides only an empty string (unless you provide <<_user_strerror>>).
  50 POSIX also recommends that unknown <[errnum]> fail with EINVAL even
  51 when providing such a message, however it is not a requirement and
  52 this implementation will return success if <<_user_strerror>> provided
  53 a non-empty alternate string without assigning into its third argument.
  54
  55 <<strerror_r>> requires no supporting OS subroutines.
  56
  57 */
  58
  59 #undef __STRICT_ANSI__
  60 #define _GNU_SOURCE
  61 #include <errno.h>
  62 #include <string.h>
  63 #undef strerror_r
  64
  65 /* For backwards-compatible linking, this must be the GNU signature;
  66    see xpg_strerror_r.c for the POSIX version.  */
  67 char *
  68 strerror_r (int errnum,
  69         char *buffer,
  70         size_t n)
  71 {
  72   char *error = _strerror_r (_REENT, errnum, 1, NULL);
  73
  74   if (strlen (error) >= n)
  75     return error;
  76   return strcpy (buffer, error);
  77 }