Uses date and time information stored in a tm structure to create
a wide-character output string. The format of the output string
is controlled by a format string.
Format
#include <wchar.h>
size_t wcsftime (wchar_t *wcs, size_t maxsize, const char
*format, const struct tm *timeptr); (XPG4)
size_t wcsftime (wchar_t *wcs, size_t maxsize, const wchar_t
*format, const struct tm *timeptr); (ISO C)
1 – Function Variants
Compiling with the _DECC_V4_SOURCE and _VMS_V6_SOURCE feature-
test macros defined enables a local-time-based entry point to
the wcsftime function that is equivalent to the behavior before
OpenVMS Version 7.0.
2 – Arguments
wcs
A pointer to the resultant wide-character string.
maxsize
The maximum number of wide characters to be stored in the
resultant string.
format
A pointer to the string that controls the format of the output
string. For the XPG4 interface, this argument is a pointer to
a constant character string. For the ISO C interface, it is a
pointer to a constant wide-character string.
timeptr
A pointer to the local time structure. The tm structure is
defined in the <time.h> header file.
3 – Description
The wcsftime function uses data in the structure pointed to by
timeptr to create the wide-character string pointed to by wcs. A
maximum of maxsize wide characters is copied to wcs.
The format string consists of zero or more conversion
specifications and ordinary characters. All ordinary characters
(including the terminating null character) are copied unchanged
into the output string. A conversion specification defines how
data in the tm structure is formatted in the output string.
A conversion specification consists of a percent (%) character
followed by one or more optional characters (see Optional
Elements of wcsftime Conversion Specifications), and ending with
a conversion specifier (see wcsftime Conversion Specifiers).
If any of the optional characters listed in Optional Elements
of wcsftime Conversion Specifications are specified, they must
appear in the order shown in the table.
Table REF-13 Optional Elements of wcsftime Conversion
Specifications
Element Meaning
- Optional with the field width to specify that the field
is left-justified and padded with spaces. This cannot
be used with the 0 element.
0 Optional with the field width to specify that the field
is right-justified and padded with zeros. This cannot
be used with the - element.
field A decimal integer that specifies the maximum field
width width
.precision A decimal integer that specifies the precision of data
in a field.
For the d, H, I, j, m, M, o, S, U, w, W, y, and Y
conversion specifiers, the precision specifier is the
minimum number of digits to appear in the field. If
the conversion specification has fewer digits than that
specified by the precision, leading zeros are added.
For the a, A, b, B, c, D, E, h, n, N, p, r, t, T,
x, X, Z, and % conversion specifiers, the precision
specifier is the maximum number of wide characters to
appear in the field. If the conversion specification
has more characters than that specified by the
precision, characters are truncated on the right.
The default precision for the d, H, I, m, M, o, S,
U, w, W, y, and Y conversion specifiers is 2, and the
default precision for the j conversion specifier is 3.
Note that the list of optional elements of conversion
specifications from Optional Elements of wcsftime Conversion
Specifications are VSI extensions to the XPG4 specification.
wcsftime Conversion Specifiers lists the conversion specifiers.
The wcsftime function uses fields in the LC_TIME category of
the program's current locale to provide a value. For example, if
%B is specified, the function accesses the mon field in LC_TIME
to find the full month name for the month specified in the tm
structure. The result of using invalid conversion specifiers is
undefined.
Table REF-14 wcsftime Conversion Specifiers
SpecifierReplaced by
a The locale's abbreviated weekday name.
A The locale's full weekday name.
b The locale's abbreviated month name.
B The locale's full month name.
c The locale's appropriate date and time representation.
C The century number (the year divided by 100 and
truncated to an integer) as a decimal number (00 - 99).
d The day of the month as a decimal number (01 - 31).
D Same as %m/%d/%y.
e The day of the month as a decimal number (1 - 31) in a
2-digit field with the leading space character fill.
Ec The locale's alternative date and time representation.
EC The name of the base year (period) in the locale's
alternative representation.
Ex The locale's alternative date representation.
Ey The offset from the base year (%EC) in the locale's
alternative representation.
EY The locale's full alternative year representation.
h Same as %b.
H The hour (24-hour clock) as a decimal number (00 - 23).
I The hour (12-hour clock) as a decimal number (01 - 12).
j The day of the year as a decimal number (001 - 366).
m The month as a decimal number (01 - 12).
M The minute as a decimal number (00 - 59).
n The new-line character.
Od The day of the month using the locale's alternative
numeric symbols.
Oe The date of the month using the locale's alternative
numeric symbols.
OH The hour (24-hour clock) using the locale's alternative
numeric symbols.
OI The hour (12-hour clock) using the locale's alternative
numeric symbols.
Om The month using the locale's alternative numeric
symbols.
OM The minutes using the locale's alternative numeric
symbols.
OS The seconds using the locale's alternative numeric
symbols.
Ou The weekday as a number in the locale's alternative
representation (Monday=1).
OU The week number of the year (Sunday as the first day
of the week) using the locale's alternative numeric
symbols.
OV The week number of the year (Monday as the first day
of the week) as a decimal number (01 -53) using the
locale's alternative numeric symbols. If the week
containing January 1 has four or more days in the new
year, it is considered as week 1. Otherwise, it is
considered as week 53 of the previous year, and the
next week is week 1.
Ow The weekday as a number (Sunday=0) using the locale's
alternative numeric symbols.
OW The week number of the year (Monday as the first day
of the week) using the locale's alternative numeric
symbols.
Oy The year without the century using the locale's
alternative numeric symbols.
p The locale's equivalent of the AM/PM designations
associated with a 12-hour clock.
r The time in AM/PM notation.
R The time in 24-hour notation (%H:%M).
S The second as a decimal number (00 - 61).
t The tab character.
T The time (%H:%M:%S).
u The weekday as a decimal number between 1 and 7
(Monday=1).
U The week number of the year (the first Sunday as the
first day of week 1) as a decimal number (00 - 53).
V The week number of the year (Monday as the first day
of the week) as a decimal number (00 - 53). If the week
containing January 1 has four or more days in the new
year, it is considered as week 1. Otherwise, it is
considered as week 53 of the previous year, and the
next week is week 1.
w The weekday as a decimal number (0 [Sunday] - 6).
W The week number of the year (the first Monday as the
first day of week 1) as a decimal number (00 - 53).
x The locale's appropriate date representation
X The locale's appropriate time representation
y The year without century as a decimal number (00 - 99).
Y The year with century as a decimal number.
Z Time-zone name or abbreviation. If time-zone information
is not available, no character is output.
% Literal % character.
4 – Return Values
x The number of wide characters placed into the
array pointed to by wcs, not including the
terminating null character.
0 Indicates an error occurred. The contents of
the array are indeterminate.
5 – Example
/* Exercise the wcsftime formatting routine. */
/* NOTE: the format string is an "L" (or wide character) */
/* string indicating that this call is NOT in */
/* the XPG4 format, but rather in ISO C format. */
#include <stdlib.h>
#include <stdio.h>
#include <time.h>
#include <wchar.h>
#include <locale.h>
#include <errno.h>
#define NUM_OF_DATES 7
#define BUF_SIZE 256
/* This program formats a number of different dates, once using the */
/* C locale and then using the fr_FR.ISO8859-1 locale. Date and time */
/* formatting is done using wcsftime(). */
main()
{
int count,
i;
wchar_t buffer[BUF_SIZE];
struct tm *tm_ptr;
time_t time_list[NUM_OF_DATES] =
{500, 68200000, 694223999,
694224000, 704900000, 705000000,
705900000};
/* Display dates using the C locale */
printf("\nUsing the C locale:\n\n");
setlocale(LC_ALL, "C");
for (i = 0; i < NUM_OF_DATES; i++) {
/* Convert to a tm structure */
tm_ptr = localtime(&time_list[i]);
/* Format the date and time */
count = wcsftime(buffer, BUF_
SIZE, L"Date: %A %d %B %Y%nTime: %T%n%n",
tm_ptr);
if (count == 0) {
perror("wcsftime");
exit(EXIT_FAILURE);
}
/* Print the result */
printf("%S", buffer);
}
/* Display dates using the fr_FR.ISO8859-1 locale */
printf("\nUsing the fr_FR.ISO8859-1 locale:\n\n");
setlocale(LC_ALL, "fr_FR.ISO8859-1");
for (i = 0; i < NUM_OF_DATES; i++) {
/* Convert to a tm structure */
tm_ptr = localtime(&time_list[i]);
/* Format the date and time */
count = wcsftime(buffer, BUF_
SIZE, L"Date: %A %d %B %Y%nTime: %T%n%n",
tm_ptr);
if (count == 0) {
perror("wcsftime");
exit(EXIT_FAILURE);
}
/* Print the result */
printf("%S", buffer);
}
}
Running the example program produces the following result:
Using the C locale:
Date: Thursday 01 January 1970
Time: 00:08:20
Date: Tuesday 29 February 1972
Time: 08:26:40
Date: Tuesday 31 December 1991
Time: 23:59:59
Date: Wednesday 01 January 1992
Time: 00:00:00
Date: Sunday 03 May 1992
Time: 13:33:20
Date: Monday 04 May 1992
Time: 17:20:00
Date: Friday 15 May 1992
Time: 03:20:00
Using the fr_FR.ISO8859-1 locale:
Date: jeudi 01 janvier 1970
Time: 00:08:20
Date: mardi 29 février 1972
Time: 08:26:40
Date: mardi 31 décembre 1991
Time: 23:59:59
Date: mercredi 01 janvier 1992
Time: 00:00:00
Date: dimanche 03 mai 1992
Time: 13:33:20
Date: lundi 04 mai 1992
Time: 17:20:00
Date: vendredi 15 mai 1992
Time: 03:20:00