Microsoft KB Archive/188768

INFO: Working with the FILETIME Structure

Q188768

The information in this article applies to:

Microsoft Win32 Application Programming Interface (API), used with:
- Microsoft Windows 95
- the operating system: Microsoft Windows NT, versions 3.5, 3.51, 4.0
- Microsoft Windows CE versions 1.0, 2.0 for the Handheld PC
- the operating system: Microsoft Windows 2000

SUMMARY

A file time represents the specific date and time at which a given file was created, last accessed, or last written to. A file time is stored in a FILETIME structure. This structure is used with various Win32 API calls.

MORE INFORMATION

The FILETIME structure represents the number of 100-nanosecond intervals since January 1, 1601. The structure consists of two 32-bit values that combine to form a single 64-bit value.

   typedef struct _FILETIME {
     DWORD dwLowDateTime;
     DWORD dwHighDateTime;
   } FILETIME;

Note that the FILETIME structure is based on 100-nanosecond intervals. It is helpful to define the following symbols when working with file times. For example:

   #define _SECOND ((int64) 10000000)
   #define _MINUTE (60 * _SECOND)
   #define _HOUR   (60 * _MINUTE)
   #define _DAY    (24 * _HOUR)

Performing Arithmetics with File Times

It is often necessary to perform a simple arithmetic on file times. For example, you might need to know when a file is 30 days old. To perform an arithmetic on a file time, you need to convert the FILETIME to a quadword (a 64-bit integer), perform the arithmetic, and then convert the result back to a FILETIME.

Assuming ft is a FILETIME structure containing the creation time of a file, the following sample code adds 30 days to the time:

   ULONGLONG qwResult;

   // Copy the time into a quadword.
   qwResult = (((ULONGLONG) ft.dwHighDateTime) << 32) + ft.dwLowDateTime;

   // Add 30 days.
   qwResult += 30 * _DAY;

   // Copy the result back into the FILETIME structure.
   ft.dwLowDateTime  = (DWORD) (qwResult & 0xFFFFFFFF );
   ft.dwHighDateTime = (DWORD) (qwResult >> 32 );

Setting File Times

You can set the file times for a file by using the SetFileTime() function.

   BOOL SetFileTime(
     HANDLE hFile,                     // Handle to the file.
     CONST FILETIME *lpCreationTime,   // Time the file was created.
     CONST FILETIME *lpLastAccessTime, // Time the file was last accessed.
     CONST FILETIME *lpLastWriteTime   // Time the file was last
                                       // written to.
   );

This function lets you modify creation, last access, and last write times without changing the content of the file. To use this function, you must have a handle to the open file. This file handle can be obtained from a call to CreateFile() or OpenFile(). The file must be opened with GENERIC_WRITE access. After the file times have been set, you should release the file handle through a call to CloseHandle().

Assuming szFilename is a valid filename and ft is a FILETIME structure, the following sample code sets the creation date for the file to the time contained in ft:

   BOOL bResult;
   HANDLE hFile = CreateFile( szFilename,
      GENERIC_WRITE, // The file must be opened with write access.
      FILE_SHARE_READ | FILE_SHARE_WRITE, NULL, OPEN_EXISTING, 0, NULL );

   if (hFile != INVALID_HANDLE_VALUE) {
      bResult = SetFileTime( hFile, &ft, NULL, NULL );
      CloseHandle(hFile);
   }

Displaying File Times

The file time is based on coordinated universal time (UTC). UTC-based time is loosely defined as the current date and time of day in Greenwich, England. You will most likely want to display the file time with respect to the local time (that is, the date and time of day for your time zone). To do this, you can use FileTimeToLocalFileTime() as follows:

   BOOL FileTimeToLocalFileTime(
     CONST FILETIME *lpFileTime,  // Pointer to UTC file time to convert.
     LPFILETIME lpLocalFileTime   // Pointer to converted file time.
   );

Note that this function uses the current settings for the time zone and daylight saving time. Therefore, if it is daylight savings time, this function will take daylight savings time into account, even if the time you are converting is in standard time.

To display the file time in a meaningful way, you first need to convert it to a system time using FileTimeToSystemTime() as follows:

   BOOL FileTimeToSystemTime(
     CONST FILETIME *lpFileTime, // Pointer to file time to convert.
     LPSYSTEMTIME lpSystemTime   // Pointer to structure to receive
   );                            // system time.

The SYSTEMTIME structure represents a date and time using individual members for the month, day, year, weekday, hour, minute, second, and millisecond.

It is also preferable to display the date and time in a format consistent with the current locale selected for the system. You can do this by using GetDateFormat() and GetTimeFormat() as follows:

   int GetDateFormat(
     LCID Locale,              // Locale for which date is to be formatted.
     DWORD dwFlags,            // Flags specifying function options.
     CONST SYSTEMTIME *lpDate, // Date to be formatted.
     LPCTSTR lpFormat,         // Date format string.
     LPTSTR lpDateStr,         // Buffer for storing formatted string.
     int cchDate               // Size of buffer.
   );

   int GetTimeFormat(
     LCID Locale,              // Locale for which time is to be formatted.
     DWORD dwFlags,            // Flags specifying function options.
     CONST SYSTEMTIME *lpTime, // Time to be formatted.
     LPCTSTR lpFormat,         // Time format string.
     LPTSTR lpTimeStr,         // Buffer for storing formatted string.
     int cchTime               // Size of buffer.
   );

By passing LOCALE_USER_DEFAULT as the first parameter to these functions, you tell them to format the passed date/time according to the default format for the current locale. In this case, you can pass NULL for the lpFormat parameters.

Assuming ft is a FILETIME structure containing a UTC value, the following sample code prints the date stored in ft:

   SYSTEMTIME st;
   char szLocalDate[255], szLocalTime[255];

   FileTimeToLocalFileTime( &ft, &ft );
   FileTimeToSystemTime( &ft, &st );
   GetDateFormat( LOCALE_USER_DEFAULT, DATE_LONGDATE, &st, NULL,
     szLocalDate, 255 );
   GetTimeFormat( LOCALE_USER_DEFAULT, 0, &st, NULL, szLocalTime, 255 );
   printf( "%s %s\n", szLocalDate, szLocalTime );

Additional query words:

Keywords : kbAPI kbDateTime kbFileIO kbKernBase kbOSWinNT350 kbOSWinNT351 kbOSWinNT400 kbOSWin2000 kbOSWinCEsearch kbDSupport kbGrpDSKernBase
Issue type : kbinfo
Technology : kbAudDeveloper kbWin32sSearch kbWin32API