wcsftime(3C)wcsftime(3C)NAMEwcsftime() - convert date and time to wide-character string
SYNOPSIS
Remarks
This function is compliant with the XPG4 Worldwide Portability Inter‐
face wide-character formatting functions. It parallels the 8-bit char‐
acter formatting function defined in strftime(3C).
DESCRIPTION
converts the contents of a structure (see ctime(3C)) to a formatted
date and time wide-character string.
places wide characters into the array pointed to by ws as controlled by
the string pointed to by format. The format string consists of zero or
more directives and ordinary characters. A directive consists of a
character, an optional field width and precision specification, and a
terminating character that determines the directive's behavior. All
ordinary characters (including the terminating null character) are con‐
verted into corresponding wide characters and are copied into the
array. No more than maxsize wide characters are placed into the array.
Each directive is replaced by the appropriate wide characters as
described in the following list. The appropriate wide characters are
determined by the program's locale, by the values contained in the
structure pointed to by timeptr, and by the environment variable (see
External Influences below).
The definition for this function and the type are provided in the
header.
Unix Standards Only
places wide characters into the array pointed to by ws as controlled by
the wide-character string pointed by format. The functionality of is
the same except for data type of format.
Directives
The following directives, shown without the optional field width and
precision specification, are replaced by the corresponding wide charac‐
ters as indicated:
Locale's abbreviated weekday name.
Locale's full weekday name.
Locale's abbreviated month name.
Locale's full month name.
Locale's appropriate date and time representation.
The century number (the year divided by 100 and truncated to an
integer)
as a decimal number [00-99].
Day of the month as a decimal number [01,31].
Equivalent to the directive string
Day of the month as a decimal number [1,31]; a single digit is
preceded by a space.
Equivalent to %b.
Hour (24-hour clock) as a decimal number [00,23].
Hour (12-hour clock) as a decimal number [01,12].
Day of the year as a decimal number [001,366].
Month as a decimal number [01,12].
Minute as a decimal number [00,59].
The New-line character.
Locale's equivalent of either AM or PM.
The time in AM and PM notation; in the POSIX locale this is
equivalent to
The time in 24 hour notation (%H:%M).
Second as a decimal number [00,61].
The Tab character.
The time in hours, minutes, and seconds (%H:%M:%S).
The weekday as a decimal number [1(Monday),7].
Week number of the year
(Sunday as the first day of the week) as a decimal
number [00,53]. All days in a new year preceding the
first Sunday are considered to be in week 0.
The week number of the year (Monday as the first day of the
week) as a
decimal number [01,53]. If the week containing Janu‐
ary 1st has four or more days in the new year, then it
is considered week 1; otherwise, it is week 53 of the
previous year, and the next week is week 1.
Weekday as a decimal number [0(Sunday),6].
Week number of the year
(Monday as the first day of the week) as a decimal
number [00,53]. All days in a new year preceding the
first Monday are considered to be in week 0.
Locale's appropriate date representation.
Locale's appropriate time representation.
Year without century as a decimal number [00,99].
Year with century as a decimal number.
Time zone name (or by no characters if no time zone exists).
The percent (%) character.
The following directives are provided for backward compatibility with
the directives supported by and the functions. These directives may be
removed in a future release. It is recommended that the directives
above be used in preference to those below.
Locale's combined Emperor/Era name and year (use
instead).
Locale's full month name (use
instead).
Locale's Emperor/Era name (use
instead).
Locale's Emperor/Era year (use
instead).
Time zone name (or by no characters if no time zone exists) (use
instead).
If a directive is not one of the above, the behavior is undefined.
Modified Conversion Specifiers
Some conversion specifiers can be modified by the E or O modifier char‐
acters to indicate that an alternative format or specification should
be used rather than the one normally used by the unmodified conversion
specifier. If the alternative format or specification does not exist
for the current locale, the behavior will be as if the unmodified con‐
version specification were used. Alternative numeric symbols refers to
those symbols defined by the (see langinfo(5)) in the locale.
The locales alternative appropriate date and time representa‐
tion.
The name of the base year (period/Emperor/Era) in the locale's
alternative
representation.
The locale's alternative date representation
The locale's alternative time representation.
The offset from %EC (year only) in the locale's alternative
representation.
The full alternative year representation.
The day of the month, using the locale's alternative numeric
symbols,
filled as needed with leading zeros if there is any
alternative symbol for zero, otherwise with leading
spaces.
the day of the month, using the locale's alternative numeric
symbols, filled as needed with leading spaces.
The hour (24-hour clock) using the locale's alternative numeric
symbols.
The hour (12-hour clock) using the locale's alternative numeric
symbols.
The month using the locale's alternative numeric symbols.
The minutes using the locale's alternative numeric symbols.
The seconds using the locale's alternative numeric symbols.
The weekday as a number in the locale's alternative representa‐
tion (Monday=1).
The week number of the year (Sunday as the first day of the
week, rules corresponding to %U) using the locale's alternative
numeric symbols.
The week number of the year (Monday as the first day of the
week, rules corresponding to %V) using tht locale's alternative
numeric symbols.
The number of the weekday (Sunday=0) using the locale's alterna‐
tive numeric symbols.
The week number of the year (Monday as the first day of the
week) using the locale's alternative numeric symbols.
The year (offset from %C) in the locale's alternative represen‐
tation and using the locale's alternative symbols.
Field Width and Precision
An optional field width and precision specification can immediately
follow the initial of a directive in the following order:
The decimal digit string
w specifies a minimum field width in which the
result of the conversion is right- or left-justi‐
fied. It is right-justified (with space padding)
by default. If the optional character is speci‐
fied, it is left-justified with space padding on
the right. If the optional character is speci‐
fied, it is right-justified and padded with zeros
on the left.
The decimal digit string
p specifies the minimum number of digits to
appear for the and directives, and the maximum
number of corresponding wide characters to be
used from the and directives. In the first case,
if a directive supplies fewer digits than speci‐
fied by the precision, it is expanded with lead‐
ing zeros. In the second case, if a directive
supplies more characters than specified by the
precision, excess characters are truncated on the
right.
If no field width or precision is specified for a or directive, a
default of is used for all but for which is used.
APPLICATION USAGE
The "Unix Standards Only" prototype of is available to applications if
they are:
a. conformant.
b. Compiled with macro with a value >=500.
c. Compiled with macro with a value >= 200112.
Also the application must be compiled with the environment variable set
to the value 98 or above and exported.
EXTERNAL INFLUENCES
Environment Variables
The category determines the characters to be substituted for those
directives described above as being from the locale.
The category determines the interpretation of the bytes within format
as single and/or multi-byte characters as well as how wide-character
conversions are done.
The category determines the characters used to form numbers for those
directives that produce numbers in the output. If (see langinfo(5)) is
defined for the locale, the characters so specified are used in place
of the default ASCII characters. If both and is defined for the
locale, will take precedence over
Environment Variables
determines the time zone name substituted for the and directives. The
time zone name is determined by calling the function which sets the
external variable (see ctime(3C)).
International Code Set Support
Single- and multi-byte character code sets are supported.
RETURN VALUE
If the total number of resulting wide characters including the termi‐
nating null wide character is not more than returns the number of wide
characters placed into the array pointed to by ws, not including the
terminating null wide character. Otherwise, zero is returned and the
contents of the array are indeterminate.
EXAMPLES
If the timeptr argument contains the following values:
the following combinations of the category and format strings produce
the indicated output:
│ │
LC_TIME │ Format String │ Output
─────────────┼───────────────────┼───────────────────
en_US.roman8 │ %x │ Mon, Jul 4, 1988
de_De.roman8 │ %x │ Mo., 4. Juli 1988
en_US.roman8 │ %X │ 03:09:04 PM
fr_FR.roman8 │ %X │ 15h09 04
any * │ %H:%M:%S │ 15:09:04
any * │ %.1H:%.1M:%.1S │ 15:9:4
any * │ %2.1H:%-3M:%03.1S │ 15:9 :004
* The directives used in these examples are not affected by the
category of the locale.
WARNINGS
The function is called upon every invocation of (whether or not the
time zone name is copied to the output array).
The range of values for ([0,61]) extends to 61 to allow for the occa‐
sional one or two leap seconds. However, the system does not accumu‐
late leap seconds and the structure generated by the functions and (see
ctime(3C)) never reflects any leap seconds.
Results are undefined if values contained in the structure pointed to
by timeptr exceed the ranges defined for the structure (see ctime(3C))
or are not consistent (such as if the element is set to 0, indicating
the first day of January, while the element is set to 11, indicating a
day in December).
AUTHOR
was developed by OSF and HP.
SEE ALSOdate(1), ctime(3C), setlocale(3C), environ(5), langinfo(5),
thread_safety(5), glossary(9).
STANDARDS CONFORMANCEwcsftime(3C)
