HOWTO: FileTimeToLocalFileTime() Adjusts for Daylight Saving Time

ID: Q128126

The information in this article applies to:

Microsoft Win32 Application Programming Interface (API), used with:
- Microsoft Windows NT versions 3.5, 4.0
- Microsoft Windows 2000

SUMMARY

Under NTFS, the API GetFileTime() returns the create time, last access time, and last write time for the specified file. The times returned in the FILETIME structures are in Universal Coordinated Time (UTC). This is also the time that NTFS uses. You can use FileTimeToLocalFileTime() to convert a file time to a local time. However, if you automatically adjust for Daylight Saving Time, FileTimeToLocalFileTime() will adjust for Daylight Saving Time based on whether the current date should be adjusted for Daylight Saving Time, not based on whether the date represented by the FILETIME structure should be adjusted.

The behavior in this situation is different under FAT, but may be changed to match the behavior under NTFS in a future version of Windows NT.

MORE INFORMATION

The result of this behavior, which is by design, is that reported file times under NTFS may change with the start and end of Daylight Saving Time. For example, suppose that the file TEST.C has a last write FILETIME representing Jan 1, 1995 9:00pm (UTC), it is not Daylight Saving Time, and you are in the Pacific time zone. Both the DIR command and the following sample code report the file time as 1:00pm (LocalTime = UTC - 8).

Sample Code 1


   #include <windows.h>

   void main()
   {
      HANDLE hFile;
      FILETIME ftCreate, ftLastAccess, ftLastWrite, ftLocal;
      SYSTEMTIME st;

      char buf[80];

   // Open the file.

      hFile = CreateFile( "test.c",
                          GENERIC_READ,
                          0,
                          NULL,
                          OPEN_EXISTING,
                          FILE_ATTRIBUTE_NORMAL,
                          NULL );

   // Get the file time (in UTC) and convert to local time.

      GetFileTime( hFile, &ftCreate, &ftLastAccess, &ftLastWrite );
      FileTimeToLocalFileTime( &ftLastWrite, &ftLocal );

   // Display the time, as a test.

      FileTimeToSystemTime( &ftLocal, &st );
      GetTimeFormat( LOCALE_USER_DEFAULT, 0, &st, NULL, buf, sizeof(buf) );
      MessageBox( NULL, buf, " FILE TIME", MB_OK );
   }

Now, set the date to 7/1/95 and enable Automatically Adjust for Daylight Saving Time. The DIR command and the sample code above will report the file time as 2:00pm, because FileTimeToLocalFileTime() has adjusted for Daylight Saving Time (LocalTime = UTC - 7).

The following sample code will correctly report the file time of TEST.C with the date set to 7/1/95 under NTFS. The FILETIME structure is converted to a SYSTEMTIME structure with FileTimeToSystemTime(). Then the time is converted using SystemTimeToTzSpecificLocalTime(). If you need to convert back to a FILETIME structure, use SystemTimeToFileTime() after the conversion to local time.

Sample Code 2


   #include <windows.h>

   void main()
   {
      HANDLE hFile;
      FILETIME ftCreate, ftLastAccess, ftLastWrite;
      SYSTEMTIME stUTC, st;
      char buf[80];

   // Open the file.

      hFile = CreateFile( "test.c",
                          GENERIC_READ,
                          0,
                          NULL,
                          OPEN_EXISTING,
                          FILE_ATTRIBUTE_NORMAL,
                          NULL );

   // Get the file time (in UTC) and convert to local time.

      GetFileTime( hFile, &ftCreate, &ftLastAccess, &ftLastWrite );
      FileTimeToSystemTime( &ftLastWrite, &stUTC );
      SystemTimeToTzSpecificLocalTime( NULL, &stUTC, &st);

   // Display the time, as a test.

      GetTimeFormat( LOCALE_USER_DEFAULT, 0, &st, NULL, buf, sizeof(buf) );
      MessageBox( NULL, buf, "FILE TIME", MB_OK );
   }

The FAT file system stores local time, not UTC. GetFileTime() gets cached UTC times from FAT. In this sample, the time stored is 1pm and the cached time is 9pm. When it becomes Daylight Saving Time, sample codes 1 and 2 will demonstrate the same behavior that they do under NTFS, because 9pm is still used. However, when you restart the machine, the new cached time will be 8pm (UTC = LocalTime + 7). The call to FileTimeToLocalFileTime() cancels the adjustment made by GetFileTime() (LocalTime = UTC - 7). Therefore, sample code 1 will report the correct time under FAT, but sample code 2 will not.

On the other hand, FindFirstFile() on FAT always reads the time from the file (stored as local time) and converts it into UTC, adjusting for DST based on the current date. So if FindFirstFile() is called, the date is changed to a different DST season, and then FindFirstFile() is called again, the UTC returned by the two calls will be different.

Additional query words:

Keywords : kbcode kbAPI kbDateTime kbKernBase kbNTOS350 kbSDKWin32 kbDSupport kbGrpKernBase
Version : winnt:3.5,4.0
Platform : winnt
Issue type : kbhowto