wcsftime(3C)															      wcsftime(3C)

NAME

       wcsftime() - convert date and time to wide-character string

SYNOPSIS

   Remarks
       This function is compliant with the XPG4 Worldwide Portability Interface 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  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 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 char-
       acters 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 January 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 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 (see langinfo(5)) in the locale.

	      The locales alternative appropriate date and time representation.

	      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 representation (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 alternative 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 representation 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-justified.  It is right-
			     justified (with space padding) by default.  If the optional character is specified, it is left-justified  with  space
			     padding  on  the  right.	If the optional character is specified, 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
			     specified by the precision, it is expanded with leading 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 terminating 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 occasional|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 ALSO
						       |		   |
       date(1), ctime(3C), setlocale(3C), environ(5), langinfo(5), thread_safety(5), glossary(9).
							       |		   |
STANDARDS CONFORMANCE
					       |		   |
							       |		   |						      wcsftime(3C)
							       |		   |
							       |		   |
							       |		   |
							       |		   |
							       |		   |
							       |		   |
							       |		   |
							       |		   |
							       |		   |
							       |		   |
							       |		   |
							       |		   |
							       |		   |
							       |		   |
							       |		   |
							       |		   |
							       |		   |
							       |		   |
							       |		   |
							       |		   |
							       |		   |
							       |		   |
							       |		   |
							       |		   |
							       |		   |
							       |		   |
							       |		   |
							       |		   |
							       |		   |
							       |		   |
							       |		   |
							       |		   |
							       |		   |
							       |		   |
							       |		   |
							       |		   |
							       |		   |