INFO: Working with the FILETIME Structure

This article was previously published under Q188768
A file time represents the specific date and time at which a given file wascreated, last accessed, or last written to. A file time is stored in aFILETIME structure. This structure is used with various Win32 API calls.
The FILETIME structure represents the number of 100-nanosecond intervalssince January 1, 1601. The structure consists of two 32-bit values thatcombine 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. Itis 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. Forexample, you might need to know when a file is 30 days old. To perform anarithmetic on a file time, you need to convert the FILETIME to a quadword(a 64-bit integer), perform the arithmetic, and then convert the resultback 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 timeswithout changing the content of the file. To use this function, you musthave a handle to the open file. This file handle can be obtained from acall to CreateFile() or OpenFile(). The file must be opened withGENERIC_WRITE access. After the file times have been set, you shouldrelease the file handle through a call to CloseHandle().

Assuming szFilename is a valid filename and ft is a FILETIME structure, thefollowing sample code sets the creation date for the file to the timecontained 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 timeis 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 tothe local time (that is, the date and time of day for your time zone). Todo 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 anddaylight saving time. Therefore, if it is daylight saving time, thisfunction will take daylight saving time into account, even if the time youare converting is in standard time.

To display the file time in a meaningful way, you first need to convert itto 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 individualmembers for the month, day, year, weekday, hour, minute, second, andmillisecond.

It is also preferable to display the date and time in a format consistentwith the current locale selected for the system. You can do this by usingGetDateFormat() 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 defaultformat for the current locale. In this case, you can pass NULL for thelpFormat parameters.

Assuming ft is a FILETIME structure containing a UTC value, the followingsample 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 );				

Article ID: 188768 - Last Review: 01/23/2007 19:29:00 - Revision: 3.3

Microsoft Win32 Application Programming Interface

  • kbinfo kbapi kbdatetime kbkernbase kbfileio KB188768