Home Library Learn Downloads Support Community
Sign in | United States - English | |
2 out of 3 rated this helpful - Rate this topic

SystemTimeToTzSpecificLocalTime function

Applies to: desktop apps | Metro style apps

Converts a time in Coordinated Universal Time (UTC) to a specified time zone's corresponding local time.

Syntax

Copy 
BOOL WINAPI SystemTimeToTzSpecificLocalTime(
  __in_opt  LPTIME_ZONE_INFORMATION lpTimeZone,
  __in      LPSYSTEMTIME lpUniversalTime,
  __out     LPSYSTEMTIME lpLocalTime
);

Parameters

lpTimeZone [in, optional]

A pointer to a TIME_ZONE_INFORMATION structure that specifies the time zone of interest.

If lpTimeZone is NULL, the function uses the currently active time zone.

lpUniversalTime [in]

A pointer to a SYSTEMTIME structure that specifies the UTC time to be converted. The function converts this universal time to the specified time zone's corresponding local time.

lpLocalTime [out]

A pointer to a SYSTEMTIME structure that receives the local time.

Return value

If the function succeeds, the return value is nonzero, and the function sets the members of the SYSTEMTIME structure pointed to by lpLocalTime to the appropriate local time values.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The SystemTimeToTzSpecificLocalTime function takes into account whether daylight saving time (DST) is in effect for the local time to which the system time is to be converted.

The SystemTimeToTzSpecificLocalTime function may calculate the local time incorrectly under the following conditions:

  • The time zone uses a different UTC offset for the old and new years.
  • The UTC time to be converted and the calculated local time are in different years.

Examples

For an example, see Retrieving the Last-Write Time.

Requirements

Minimum supported client

Windows 2000 Professional

Minimum supported server

Windows 2000 Server

Header
Winbase.h (include Windows.h)

Library
Kernel32.lib

DLL
Kernel32.dll

See also

GetSystemTime
GetTimeZoneInformation
System Time
SYSTEMTIME
Time Functions
TIME_ZONE_INFORMATION
TzSpecificLocalTimeToSystemTime

 

 

Send comments about this topic to Microsoft

Build date: 3/6/2012

Did you find this helpful?
(1500 characters remaining)
Community Content Add
Annotations FAQ
The function may also calculate the local time incorrectly under the following conditions:
In countries where the daylight saving date is changed from year to year (Brasilia GMT-3 is a good example), daylight saving may be applied incorrectly. For example... Set the system clock to a date in 2011 and the Time Zone to Brasilia and ask for a conversion to local time for UTC 23 February 2010 03:00 and you get BRS 23/02/2010 00:00 Set the system clock to a date in 2012 and the Time Zone to Brasilia and ask for a conversion to local time for UTC 23 February 2010 03:00 and you get BRS 23/02/2010 01:00 The first answer is correct as Daylight Saving Time ended on Saturday, 20 February 2010 in Brasilia (http://www.timeanddate.com/worldclock/timezone.html?n=45) so the bias should be 3 hours.. The problem is this.... Occasionally [in Brasilia], in years when the Carnival celebrations fall on the 3rd Sunday of February, DST's ending is postponed to the following Sunday (http://en.wikipedia.org/wiki/Time_in_Brazil). 2012 is such a year and so the SystemTimeToTzSpecificLocalTime function uses the 4th Sunday of February in all of its daylight saving calculations even on years which used the 3rd Sunday of February.. The answer, of course, is to use the GetTimeZoneInformationForYear function and pass it in as the lpTimeZone parameter in the SystemTimeToTzSpecificLocalTime. BUT: this is only available on Windows Server 2008 and Vista - no good for anyone on Server 2003 or XP....
History
Possible error in File Time description
The first sentence (copied here) of the description of _File Times_ really disturbs me:
"A file time is a 64-bit value that represents the number of 100-nanosecond intervals that have elapsed since 12:00 A.M. January 1, 1601 Coordinated Universal Time (UTC). The system records file times when applications create, access, and write to files."
Just for the MSDN author's information, UTC time uses constant length seconds. (http://en.wikipedia.org/wiki/Coordinated_Universal_Time)
So who knows how many UTC 100-nanosecond intervals have elapsed since 12:00 A.M. January 1, 1601? How ever many there are, the number is not likely to be the number of UT1 100-nanosecond intervals during the same period. And if the author made a mistake there, I would suggest checking the "12:00 A.M." time. Did maybe he mean 12:00 noon (following a definition of Julian time) instead of midnight at the beginning of the day?
History
C# syntax 
[DllImport("kernel32.dll", SetLastError=true)]
private static extern long SystemTimeToTzSpecificLocalTime(IntPtr lpTimeZoneInformation, ref SYSTEMTIME lpUniversalTime, ref SYSTEMTIME lpLocalTime);
History
vb.net syntax 
<DllImport("kernel32.dll", SetLastError:=True)> _
Public Shared Function SystemTimeToTzSpecificLocalTime(ByVal lpTimeZoneInformation As IntPtr, ByRef lpUniversalTime As SYSTEMTIME, ByRef lpLocalTime As SYSTEMTIME) As Long
End Function
History