newlib/libc/time/wcsftime.c

   1 /*
   2  * wcsftime.c
   3  * Original Author:     Craig Howland, for Newlib
   4  *
   5  * Source actually uses strftime.c.
   6  * Documentation for wcsftime() here, with minimal overlap.
   7  */
   8
   9 /*
  10 FUNCTION
  11 <<wcsftime>>---convert date and time to a formatted wide-character string
  12
  13 INDEX
  14         wcsftime
  15
  16 SYNOPSIS
  17         #include <time.h>
  18         #include <wchar.h>
  19         size_t wcsftime(wchar_t *<[s]>, size_t <[maxsize]>,
  20                         const wchar_t *<[format]>, const struct tm *<[timp]>);
  21
  22 DESCRIPTION
  23 <<wcsftime>> is equivalent to <<strftime>>, except that:
  24
  25 O+
  26 o The argument s points to the initial element of an array of wide characters
  27 into which the generated output is to be placed.
  28
  29 o The argument maxsize indicates the limiting number of wide characters.
  30
  31 o The argument format is a wide-character string and the conversion specifiers
  32 are replaced by corresponding sequences of wide characters.
  33
  34 o The return value indicates the number of wide characters.
  35 O-
  36 (The difference in all of the above being wide characters versus regular
  37 characters.)
  38
  39 See <<strftime>> for the details of the format specifiers.
  40
  41 RETURNS
  42 When the formatted time takes up no more than <[maxsize]> wide characters,
  43 the result is the length of the formatted wide string.  Otherwise, if the
  44 formatting operation was abandoned due to lack of room, the result is
  45 <<0>>, and the wide-character string starting at <[s]> corresponds to just those
  46 parts of <<*<[format]>>> that could be completely filled in within the
  47 <[maxsize]> limit.
  48
  49 PORTABILITY
  50 C99 and POSIX require <<wcsftime>>, but do not specify the contents of
  51 <<*<[s]>>> when the formatted string would require more than
  52 <[maxsize]> characters.  Unrecognized specifiers and fields of
  53 <<timp>> that are out of range cause undefined results.  Since some
  54 formats expand to 0 bytes, it is wise to set <<*<[s]>>> to a nonzero
  55 value beforehand to distinguish between failure and an empty string.
  56 This implementation does not support <<s>> being NULL, nor overlapping
  57 <<s>> and <<format>>.
  58
  59 <<wcsftime>> requires no supporting OS subroutines.
  60
  61 SEEALSO
  62 <<strftime>>
  63 */
  64
  65 #include <time.h>
  66 #include <wchar.h>
  67 #define MAKE_WCSFTIME
  68 #include "../time/strftime.c"