Welcome  |  Sign In
Skip Navigation Links
Microsoft Developer Network
Click to Rate and Give Feedback
MSDN
MSDN Library
User Interface
 GetDateFormat
International Features
GetDateFormat

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

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

int GetDateFormat(
  LCID Locale,               
  DWORD dwFlags,             
  CONST SYSTEMTIME* lpDate,  
  LPCTSTR lpFormat,          
  LPTSTR lpDateStr,          
  int cchDate               
);

Parameters

Locale
[in] Locale identifier that specifies the locale for which this function formats the date string. 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 various function options that can be set if lpFormat is set to a null pointer. If lpFormat is not set to a null pointer, this parameter must be set to 0. The application can specify a combination of the following values.
Value Meaning
LOCALE_NOUSEROVERRIDE Format the string using the system default date format for the specified locale. If this flag is not set, the function formats the string using any user overrides to the default date format for the locale. This flag can only be set if lpFormat is set to a null pointer.
Note: Your applications are recommended to respect user overrides in most cases. There are several reasons for doing this, for example: users expect applications not to block their preferences; data can change, even when overrides are blocked; and ignoring overrides typically slows down an application.
LOCALE_USE_CP_ACP Use the system ANSI code page for string translation instead of the code page for the locale. See Code Page Identifiers for a list of ANSI and other code pages.
DATE_SHORTDATE Use the short date format. This is the default. This value cannot be used with DATE_LONGDATE or DATE_YEARMONTH.
DATE_LONGDATE Use the long date format. This value cannot be used with DATE_SHORTDATE or DATE_YEARMONTH.
DATE_YEARMONTH Windows 2000 and later: Use the year/month format. This value cannot be used with DATE_SHORTDATE or DATE_LONGDATE.
DATE_USE_ALT_CALENDAR Use the alternate calendar, if one exists, to format the date string. If this flag is set, the function uses the default format for that alternate calendar, rather than using any user overrides. The user overrides will be used only in the event that there is no default format for the specified alternate calendar.
DATE_LTRREADING Windows 2000 and later: Add marks for left-to-right reading layout. This value cannot be used with DATE_RTLREADING.
DATE_RTLREADING Windows 2000 and later: Add marks for right-to-left reading layout. This value cannot be used with DATE_LTRREADING

If you do not specify DATE_YEARMONTH, DATE_SHORTDATE, or DATE_LONGDATE, and lpFormat is NULL, then DATE_SHORTDATE is the default.

lpDate
[in] Pointer to a SYSTEMTIME structure that contains the date information to format. If this parameter is set to a null pointer, the function uses the current local system date.
lpFormat
[in] Pointer to a format picture string that is used to form the date string. The format picture string must be zero-terminated. If lpFormat is set to a null pointer, the function formats the string according to the date format for the specified locale. If lpFormat 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 day and month names for the locale.

The application uses the following elements to construct a format picture string. If it uses spaces to separate the elements in the format string, these spaces will appear in the same location in the output string. The letters must be in uppercase or lowercase as shown in the table, for example, "MM" not "mm". Characters in the format string that are enclosed in single quotation marks appear in the same location and unchanged in the output string.

Picture Meaning
d Day of month as digits with no leading zero for single-digit days.
dd Day of month as digits with leading zero for single-digit days.
ddd Day of week as a three-letter abbreviation. The function uses the LOCALE_SABBREVDAYNAME value associated with the specified locale.
dddd Day of week as its full name. The function uses the LOCALE_SDAYNAME value associated with the specified locale.
M Month as digits with no leading zero for single-digit months.
MM Month as digits with leading zero for single-digit months.
MMM Month as a three-letter abbreviation. The function uses the LOCALE_SABBREVMONTHNAME value associated with the specified locale.
MMMM Month as its full name. The function uses the LOCALE_SMONTHNAME value associated with the specified locale.
y Year as last two digits, but with no leading zero for years less than 10.
yy Year as last two digits, but with leading zero for years less than 10.
yyyy Year represented by full four or five digits, depending on the calendar used. Thai Buddhist and Korean calendars both have five digit years. The "yyyy" pattern will show five digits for these two calendars, and four digits for all other supported calendars.
yyyyy Identical to "yyyy".
gg Period/era string. The function uses the CAL_SERASTRING value associated with the specified locale. This element is ignored if the date to be formatted does not have an associated era or period string.

For example, to get the date string 

"Wed, Aug 31 94"

the application uses the following picture string: 

"ddd',' MMM dd yy"
lpDateStr
[out] Pointer to a buffer in which this function retrieves the formatted date string.
cchDate
[in] Size, in characters, of the lpDateStr buffer. The application can set this parameter to 0 to return the buffer size required to hold the formatted date string. In this case, the buffer indicated by lpDateStr is not used.

Return Values

Returns the number of characters written to the lpDateStr buffer if successful. If the cchDate parameter is set to 0, the function returns the number of characters required to hold the formatted date string, including the terminating null character.

The 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

Remarks

The earliest date supported by this function is January 1, 1601.

The day name, abbreviated day name, month name, and abbreviated month name are all localized based on the locale identifier.

The date values in the SYSTEMTIME structure pointed to by lpDate must be valid. The function checks each of the date values: year, month, day, and day of week. If the day of the week is incorrect, the function uses the correct value, and returns no error. If any of the other date values are outside the correct range, the function fails, and sets the last error to ERROR_INVALID_PARAMETER.

The function ignores the time members of the SYSTEMTIME structure indicated by lpDate. These include wHour, wMinute, wSecond, and wMilliseconds.

If the lpFormat parameter is a bad format string, the function returns no errors. The function just forms the best possible date string. For example, the only year pictures that are valid are L"yyyy" and L"yy", where the "L" indicates a Unicode (16-bit characters) string. If L"y" is passed in, the function assumes L"yy". If L"yyy" is passed in, the function assumes L"yyyy". If more than four date (L"dddd") or four month (L"MMMM") pictures are passed in, the function defaults to L"dddd" or L"MMMM".

The application should enclose any text that should remain in its exact form in the date string within single quotation marks in the date format picture. The single quotation mark can also be used as an escape character to allow the single quotation mark itself to be displayed in the date string. However, the escape sequence must be enclosed within two single quotation marks. For example, to display the date as "May '93", the format string is: L"MMMM ''''yy". The first and last single quotation marks are the enclosing quotation marks. The second and third single quotation marks are the escape sequence to allow the single quotation mark to be displayed before the century.

When the date picture contains both a numeric form of the day (either d or dd) and the full month name (MMMM), the genitive form of the month name is returned in the date string.

To obtain the default short and long date format without performing any actual formatting, the application should use the GetLocaleInfo function with the LOCALE_SSHORTDATE or LOCALE_SLONGDATE constant. To get the date format for an alternate calendar, the application uses GetLocaleInfo with the LOCALE_IOPTIONALCALENDAR constant. To get the date format for a particular calendar, the application uses GetCalendarInfo. It can call EnumCalendarInfo or EnumDateFormatsEx to retrieve date formats for a particular calendar.

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 GetDateFormatEx in preference to this function. GetDateFormatEx provides good support for supplemental locales. However, GetDateFormatEx is not supported for versions of Windows prior to Windows Vista.

Requirements

  Windows NT/2000/XP/Vista: Included in Windows NT 3.5 and later.
  Windows 95/98/Me: Included in Windows 95 and 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, EnumCalendarInfo, EnumDateFormatsEx, GetCalendarInfo, GetDateFormatEx, GetLocaleInfo, GetTimeFormat, SYSTEMTIME

Tags What's this?: Add a tag
Community Content   What is Community Content?
Add new content      
LOCALE_NOUSEROVERRIDE should be avoided      Shawn Steele - MSFT   |   Edit   |  

LOCALE_NOUSEROVERRIDE should be avoided

Users specify overrides for a reason :), and expect them to be used. If your app needs a specific format, it should pass in a format instead of depending on the locale data. (See "Culture data shouldn't be considered stable (except for Invariant)" http://blogs.msdn.com/shawnste/archive/2005/04/05/405694.aspx

Tags What's this?: Add a tag
Flag as ContentBug
GetDateFormatEx is preferred      Shawn Steele - MSFT   |   Edit   |  

GetDateFormatEx is preferred

Try to avoid LCIDs and use locale names if possible

Users can create custom locales which your application may not have access to if it doesn't use the locale name. Custom locales don't get their own LCIDs, so functionality is limited if your application relies on the LCID. See this blog http://blogs.msdn.com/shawnste/pages/custom-cultures-vista-custom-locales.aspx for more info about locales/custom locales and good behavior with locales.

Tags What's this?: Add a tag
Flag as ContentBug
Processing
© 2008 Microsoft Corporation. All rights reserved. Terms of Use  |  Trademarks  |  Privacy Statement
Page view tracker