Formats time as a time string for a locale specified by identifier. The function formats either a specified time or the local system time.

Note: This function retrieves information only about a locale specified by identifier. Additional locales, features, and RFC 4646 names are supported by the GetTimeFormatEx function.

int GetTimeFormat(
  LCID Locale,              
  DWORD dwFlags,           
  CONST SYSTEMTIME* lpTime, 
  LPCTSTR lpFormat,        
  LPTSTR lpTimeStr,         
  int cchTime               
);

Parameters

Locale

[in] Locale identifier that specifies the locale. You can use the MAKELCID macro to create a locale identifier or use one of the following predefined values. For more information, see Locale Identifier Constants and Strings.

• LOCALE_INVARIANT
• LOCALE_SYSTEM_DEFAULT
• LOCALE_USER_DEFAULT

Windows Vista and later: The following custom locale identifiers are also supported.

• LOCALE_CUSTOM_DEFAULT
• LOCALE_CUSTOM_UI_DEFAULT
• LOCALE_CUSTOM_UNSPECIFIED

dwFlags

[in] Flags specifying function options. The application can specify a combination of the following values:

Value	Meaning
LOCALE_NOUSEROVERRIDE	Format the string using the system default time format for the specified locale. If this flag is not set, the function formats the string using any user overrides to the default time format for the locale. This flag can only be set if lpFormat is set to a null pointer. Note: Since LOCALE_NOUSEROVERRIDE disables user preferences, its use is discouraged.
LOCALE_USE_CP_ACP	Use the operating system ANSI code page instead of the locale code page for string translation. See Code Page Identifiers for a list of code pages.
TIME_NOMINUTESORSECONDS	Do not use minutes or seconds.
TIME_NOSECONDS	Do not use seconds.
TIME_NOTIMEMARKER	Donot use a time marker.
TIME_FORCE24HOURFORMAT	Always use a 24-hour time format.

lpTime

[in] Pointer to a SYSTEMTIME structure that contains the time information to format. The application can set this parameter to a null pointer if the function is to use the current local system time.

lpFormat

[in] Pointer to a format picture to use to format the time string. If this parameter is set to a null pointer, the function formats the string according to the time format of the specified locale. If the parameter is not set to a null pointer, the function uses the locale only for information not specified in the format picture string, for example, the locale-specific time markers. For information about the format picture string, see the Remarks section.

lpTimeStr

[out] Pointer to a buffer in which this function retrieves the formatted time string.

cchTime

[in] Size, in TCHAR values, for the time string buffer indicated by lpTimeStr.

Alternatively, the application can set this parameter to 0. In this case, the function returns the required size for the time string buffer, and does not use the lpTimeStr parameter.

Return Values

Returns the number of TCHAR values retrieved in the buffer indicated by lpTimeStr. If the cchTime parameter is set to 0, the function returns the size of the buffer required to hold the formatted time string, including a terminating null character.

This function returns 0 if it does not succeed. To get extended error information, the application can call GetLastError. GetLastError can return one of the following error codes:

• ERROR_INSUFFICIENT_BUFFER
• ERROR_INVALID_FLAGS
• ERROR_INVALID_PARAMETER
• ERROR_OUTOFMEMORY

Remarks

If a time marker exists and the TIME_NOTIMEMARKER flag is not set, the function localizes the time marker based on the specified locale identifier. Examples of time markers are "AM" and "PM" for English (United States).

The time values in the SYSTEMTIME structure indicated by lpTime must be valid. The function checks each of the time values to determine that it is within the appropriate range of values. If any of the time values are outside the correct range, the function fails, and sets the last error to ERROR_INVALID_PARAMETER.

The function ignores the date members of the SYSTEMTIME structure. These include: wYear, wMonth, wDayOfWeek, and wDay.

If TIME_NOMINUTESORSECONDS or TIME_NOSECONDS is specified, the function removes the separators preceding the minutes and/or seconds members.

If TIME_NOTIMEMARKER is specified, the function removes the separators preceding and following the time marker.

If TIME_FORCE24HOURFORMAT is specified, the function displays any existing time marker, unless the TIME_NOTIMEMARKER flag is also set.

The function does not include milliseconds as part of the formatted time string.

To use LOCALE_NOUSEROVERRIDE, the application must set lpFormat to a null pointer.

The function returns no errors for a bad format string. The function just forms the best possible time string. If more than two hour, minute, second, or time marker format pictures are passed in, the function defaults to two. For example, the only time marker pictures that are valid are "t" and "tt". If "ttt" is passed in, the function assumes "tt".

To obtain the time format without performing any actual formatting, the application should use the GetLocaleInfo function specifying LOCALE_STIMEFORMAT.

The application can use the following elements to construct a format picture string. If spaces are used to separate the elements in the format string, these spaces appear in the same location in the output string. The letters must be in uppercase or lowercase as shown, for example, "ss", not "SS". Characters in the format string that are enclosed in single quotation marks appear in the same location and unchanged in the output string.

For example, to get the time string

"11:29:40 PM"

the application should use the following picture string:

"hh':'mm':'ss tt"

Note: When the ANSI version of this function is used with a Unicode-only locale identifier, the function can succeed because the operating system uses the system code page. However, characters that are undefined in the system code page appear in the string as a question mark (?). To determine the identifiers that are Unicode-only, see Locale Identifier Constants and Strings.

Windows 95/98/Me: The Unicode version of this function is supported by the Microsoft Layer for Unicode. To use this version, you must add certain files to your application, as outlined in Microsoft Layer for Unicode on Windows 95/98/Me Systems.

This function can return data from custom locales. Locales are not guaranteed to be the same from computer to computer or between runs of an application. If your application must persist or transmit data, see Using Persistent Locale Data.

Applications that are intended to run only on Windows Vista and later should use GetTimeFormatEx in preference to this function. GetTimeFormatEx provides good support for supplemental locales. However, GetTimeFormatEx is not supported for versions of Windows prior to Windows Vista.

Requirements

  Windows NT/2000/XP/Vista: Included in Windows NT 3.5 or later.
  Windows 95/98/Me: Included in Windows 95 or later.
  Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000/XP. Also supported by Microsoft Layer for Unicode.
  Header: Declared in Winnls.h; include Windows.h.
  Library: Use Kernel32.lib.

See Also

National Language Support, National Language Support Functions, GetDateFormat, GetTimeFormatEx, GetLocaleInfo, SYSTEMTIME