United States-English |
|
|
HP-UX Reference > Wwcsftime(3C)HP-UX 11i Version 3: February 2007 |
|
NAMEwcsftime() — convert date and time to wide-character string SYNOPSIS#include <wchar.h> size_t wcsftime( wchar_t *__restrict ws, size_t maxsize, const char *__restrict format, const struct tm *__restrict timeptr ); Unix Standards Only size_t wcsftime( wchar_t *__restrict ws, size_t maxsize, const wchar_t *__restrict format, const struct tm *__restrict timeptr ); RemarksThis function is compliant with the XPG4 Worldwide Portability Interface wide-character formatting functions. It parallels the 8-bit character formatting function defined in strftime(3C). DESCRIPTIONwcsftime() converts the contents of a tm structure (see ctime(3C)) to a formatted date and time wide-character string. wcsftime() 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 converted 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 TZ environment variable (see External Influences below). The definition for this function and the type wchar_t are provided in the <wchar.h> header. Unix Standards Onlywcsftime() places wide characters into the array pointed to by ws as controlled by the wide-character string pointed by format. The functionality of wcsftime() is the same except for data type of format. DirectivesThe following directives, shown without the optional field width and precision specification, are replaced by the corresponding wide characters as indicated:
The following directives are provided for backward compatibility with the directives supported by date and the ctime functions. These directives may be removed in a future release. It is recommended that the directives above be used in preference to those below.
If a directive is not one of the above, the behavior is undefined. Modified Conversion SpecifiersSome conversion specifiers can be modified by the E or O modifier characters 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 conversion specification were used. Alternative numeric symbols refers to those symbols defined by the ALT_DIGIT (see langinfo(5)) in the locale.
Field Width and PrecisionAn optional field width and precision specification can immediately follow the initial % of a directive in the following order:
If no field width or precision is specified for a d, H, I, m, M, S, U, W, y, or j directive, a default of .2 is used for all but j for which .3 is used. APPLICATION USAGEThe "Unix Standards Only" prototype of wcsftime() is available to applications if they are:
Also the application must be compiled with the environment variable UNIX_STD set to the value 98 or above and exported. EXTERNAL INFLUENCESEnvironment VariablesThe LC_TIME category determines the characters to be substituted for those directives described above as being from the locale. The LC_CTYPE 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 LC_NUMERIC category determines the characters used to form numbers for those directives that produce numbers in the output. If ALT_DIGITS (see langinfo(5)) is defined for the locale, the characters so specified are used in place of the default ASCII characters. If both ALT_DIGITS and ALT_DIGIT is defined for the locale, ALT_DIGITS will take precedence over ALT_DIGIT. Environment VariablesTZ determines the time zone name substituted for the %Z and %z directives. The time zone name is determined by calling the function tzset() which sets the external variable tzname (see ctime(3C)). RETURN VALUEIf the total number of resulting wide characters including the terminating null wide character is not more than maxsize, wcsftime() 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. EXAMPLESIf the timeptr argument contains the following values: timeptr->tm_sec = 4; timeptr->tm_min = 9; timeptr->tm_hour = 15; timeptr->tm_mday = 4; timeptr->tm_mon = 6; timeptr->tm_year = 88; timeptr->tm_wday = 1; timeptr->tm_yday = 185; timeptr->tm_isdst = 1; the following combinations of the LC_TIME category and format strings produce the indicated output:
WARNINGSThe function tzset() is called upon every invocation of wcsftime() (whether or not the time zone name is copied to the output array). The range of values for %S ([0,61]) extends to 61 to allow for the occasional one or two leap seconds. However, the system does not accumulate leap seconds and the tm structure generated by the functions localtime() and gmtime() (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 tm structure (see ctime(3C)) or are not consistent (such as if the tm_yday element is set to 0, indicating the first day of January, while the tm_mon element is set to 11, indicating a day in December). |
Printable version | ||
|