FILETIME structure (minwinbase.h)
Contains a 64-bit value representing the number of 100-nanosecond intervals since January 1, 1601 (UTC).
Syntax
Members
The low-order part of the file time.
The high-order part of the file time.
Remarks
To convert a FILETIME structure into a time that is easy to display to a user, use the FileTimeToSystemTime function.
It is not recommended that you add and subtract values from the FILETIME structure to obtain relative times. Instead, you should copy the low- and high-order parts of the file time to a ULARGE_INTEGER structure, perform 64-bit arithmetic on the QuadPart member, and copy the LowPart and HighPart members into the FILETIME structure.
Do not cast a pointer to a FILETIME structure to either a ULARGE_INTEGER* or __int64* value because it can cause alignment faults on 64-bit Windows.
Not all file systems can record creation and last access time and not all file systems record them in the same manner. For example, on NT FAT, create time has a resolution of 10 milliseconds, write time has a resolution of 2 seconds, and access time has a resolution of 1 day (really, the access date). On NTFS, access time has a resolution of 1 hour. Therefore, the GetFileTime function may not return the same file time information set using the SetFileTime function. Furthermore, FAT records times on disk in local time. However, NTFS records times on disk in UTC. For more information, see File Times.
A function using the FILETIME structure can allow for values outside of zero or positive values typically specified by the dwLowDateTime and dwHighDateTime members. For example, the SetFileTime function uses 0xFFFFFFFF to specify that a file’s previous access time should be preserved. For more information, see the topic for the function you are calling.
GetFileTime function (fileapi.h)
Retrieves the date and time that a file or directory was created, last accessed, and last modified.
Syntax
Parameters
A handle to the file or directory for which dates and times are to be retrieved. The handle must have been created using the CreateFile function with the GENERIC_READ access right. For more information, see File Security and Access Rights.
A pointer to a FILETIME structure to receive the date and time the file or directory was created. This parameter can be NULL if the application does not require this information.
A pointer to a FILETIME structure to receive the date and time the file or directory was last accessed. The last access time includes the last time the file or directory was written to, read from, or, in the case of executable files, run. This parameter can be NULL if the application does not require this information.
A pointer to a FILETIME structure to receive the date and time the file or directory was last written to, truncated, or overwritten (for example, with WriteFile or SetEndOfFile). This date and time is not updated when file attributes or security descriptors are changed. This parameter can be NULL if the application does not require this information.
Return value
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
Not all file systems can record creation and last access times and not all file systems record them in the same manner. For example, on FAT, create time has a resolution of 10 milliseconds, write time has a resolution of 2 seconds, and access time has a resolution of 1 day (really, the access date). Therefore, the GetFileTime function may not return the same file time information set using the SetFileTime function.
NTFS delays updates to the last access time for a file by up to one hour after the last access. NTFS also permits last access time updates to be disabled. Last access time is not updated on NTFS volumes by default.
Windows ServerВ 2003 and WindowsВ XP:В В Last access time is updated on NTFS volumes by default.
For more information, see File Times.
If you rename or delete a file, then restore it shortly thereafter, Windows searches the cache for file information to restore. Cached information includes its short/long name pair and creation time.
SetFileTime function (fileapi.h)
Sets the date and time that the specified file or directory was created, last accessed, or last modified.
Syntax
Parameters
A handle to the file or directory. The handle must have been created using the CreateFile function with the FILE_WRITE_ATTRIBUTES access right. For more information, see File Security and Access Rights.
A pointer to a FILETIME structure that contains the new creation date and time for the file or directory. If the application does not need to change this information, set this parameter either to NULL or to a pointer to a FILETIME structure that has both the dwLowDateTime and dwHighDateTime members set to 0.
A pointer to a FILETIME structure that contains the new last access date and time for the file or directory. The last access time includes the last time the file or directory was written to, read from, or (in the case of executable files) run. If the application does not need to change this information, set this parameter either to NULL or to a pointer to a FILETIME structure that has both the dwLowDateTime and dwHighDateTime members set to 0.
To prevent file operations using the given handle from modifying the last access time, call SetFileTime immediately after opening the file handle and pass a FILETIME structure that has both the dwLowDateTime and dwHighDateTime members set to 0xFFFFFFFF.
A pointer to a FILETIME structure that contains the new last modified date and time for the file or directory. If the application does not need to change this information, set this parameter either to NULL or to a pointer to a FILETIME structure that has both the dwLowDateTime and dwHighDateTime members set to 0.
To prevent file operations using the given handle from modifying the last access time, call SetFileTime immediately after opening the file handle and pass a FILETIME structure that has both the dwLowDateTime and dwHighDateTime members set to 0xFFFFFFFF.
Return value
If the function succeeds, the return value is nonzero.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
Not all file systems can record creation and last access times and not all file systems record them in the same manner. For example, on FAT, create time has a resolution of 10 milliseconds, write time has a resolution of 2 seconds, and access time has a resolution of 1 day (really, the access date). Therefore, the GetFileTime function may not return the same file time information set using SetFileTime. NTFS delays updates to the last access time for a file by up to one hour after the last access.
Time Functions
The following functions are used with system time.
| Function | Description |
|---|---|
| GetSystemTime | Retrieves the current system date and time in UTC format. |
| GetSystemTimeAdjustment | Determines whether the system is applying periodic time adjustments to its time-of-day clock. |
| GetTimeFormat | Formats a system time as a time string for a specified locale. |
| NtQuerySystemTime | Returns the system time. |
| RtlLocalTimeToSystemTime | Converts the specified local time to system time. |
| RtlTimeToSecondsSince1970 | Converts the specified system time to the number of seconds since the first second of January 1, 1970. |
| SetSystemTime | Sets the current system time and date. |
| SetSystemTimeAdjustment | Enables or disables periodic time adjustments to the system’s time-of-day clock. |
| SystemTimeToFileTime | Converts a system time to a file time. |
| SystemTimeToTzSpecificLocalTime | Converts a UTC time to a specified time zone’s corresponding local time. |
| TzSpecificLocalTimeToSystemTime | Converts a local time to a UTC time. |
The following functions are used with local time.
| Function | Description |
|---|---|
| EnumDynamicTimeZoneInformation | Enumerates dynamic daylight saving time information entries stored in the registry. |
| FileTimeToLocalFileTime | Converts a UTC file time to a local file time. |
| GetDynamicTimeZoneInformation | Retrieves the current time zone and dynamic daylight saving time settings. |
| GetDynamicTimeZoneInformationEffectiveYears | Retrieves a range, expressed in years, for which a DYNAMIC_TIME_ZONE_INFORMATION has valid entries. |
| GetLocalTime | Retrieves the current local date and time. |
| GetTimeZoneInformation | Retrieves the current time zone settings. |
| GetTimeZoneInformationForYear | Retrieves the time zone settings for the specified year and time zone. |
| RtlLocalTimeToSystemTime | Converts the specified local time to system time. |
| SetDynamicTimeZoneInformation | Sets the current time zone and dynamic daylight saving time settings. |
| SetLocalTime | Sets the current local time and date. |
| SetTimeZoneInformation | Sets the current time zone settings. |
| SystemTimeToTzSpecificLocalTime | Converts a UTC time to a specified time zone’s corresponding local time. |
| SystemTimeToTzSpecificLocalTimeEx | Converts a UTC time with dynamic daylight saving time settings to a specified time zone’s corresponding local time. |
| TzSpecificLocalTimeToSystemTime | Converts a local time to a UTC time. |
| TzSpecificLocalTimeToSystemTimeEx | Converts a local time with dynamic daylight saving time settings to UTC time. |
The following functions are used with file time.
| Function | Description |
|---|---|
| CompareFileTime | Compares two file times. |
| FileTimeToLocalFileTime | Converts a UTC file time to a local file time. |
| FileTimeToSystemTime | Converts a file time to system time format. |
| GetFileTime | Retrieves the date and time that the specified file or directory was created, last accessed, and last modified. |
| GetSystemTimeAsFileTime | Retrieves the current system date and time in UTC format. |
| LocalFileTimeToFileTime | Converts a local file time to a file time based on UTC. |
| SetFileTime | Sets the date and time that the specified file or directory was created, last accessed, or last modified. |
| SystemTimeToFileTime | Converts a system time to a file time. |
The following functions are used with MS-DOS date and time.
| Function | Description |
|---|---|
| DosDateTimeToFileTime | Converts MS-DOS date and time values to a file time. |
| FileTimeToDosDateTime | Converts a file time to MS-DOS date and time values. |
The following functions are used with Windows time.
| Function | Description |
|---|---|
| GetSystemTimes | Retrieves system timing information. |
| GetTickCount | Retrieves the number of milliseconds that have elapsed since the system was started, up to 49.7 days. |
| GetTickCount64 | Retrieves the number of milliseconds that have elapsed since the system was started. |
The following functions are used with high-resolution performance counters.
| Function | Description |
|---|---|
| QueryPerformanceCounter | Retrieves the current value of the high-resolution performance counter. |
| QueryPerformanceFrequency | Retrieves the frequency of the high-resolution performance counter. |
The following functions are used with the auxiliary performance counter.
| Function | Description |
|---|---|
| QueryAuxiliaryCounterFrequency | Queries the auxiliary counter frequency. |
| ConvertAuxiliaryCounterToPerformanceCounter | Converts the specified auxiliary counter value to the corresponding performance counter value; optionally provides the estimated conversion error in nanoseconds due to latencies and maximum possible drift. |
| ConvertPerformanceCounterToAuxiliaryCounter | Converts the specified performance counter value to the corresponding auxiliary counter value; optionally provides the estimated conversion error in nanoseconds due to latencies and maximum possible drift. |
The following function is used with interrupt time.
File Times
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.
The NTFS file system stores time values in UTC format, so they are not affected by changes in time zone or daylight saving time. The FAT file system stores time values based on the local time of the computer. For example, a file that is saved at 3:00pm PST in Washington is seen as 6:00pm EST in New York on an NTFS volume, but it is seen as 3:00pm EST in New York on a FAT volume.
Time stamps are updated at various times and for various reasons. The only guarantee about a file time stamp is that the file time is correctly reflected when the handle that makes the change is closed.
Not all file systems can record creation and last access times, and not all file systems record them in the same manner. For example, the resolution of create time on FAT is 10 milliseconds, while write time has a resolution of 2 seconds and access time has a resolution of 1 day, so it is really the access date. The NTFS file system delays updates to the last access time for a file by up to 1 hour after the last access.
To retrieve the file times for a specified file, use the GetFileTime function. GetFileTime copies the creation, last access, and last write times to individual FILETIME structures. You can also retrieve file times using the FindFirstFile and FindNextFile functions. These functions copy the file times to FILETIME structures in a WIN32_FIND_DATA structure. When writing to a file, the last write time is not fully updated until all handles that are used for writing are closed.
To set the file times for a file, use the SetFileTime function. This function lets you modify creation, last access, and last write times without changing the content of the file. You can compare the times of different files by using the CompareFileTime function. The function compares two file times and returns a value that indicates which time is later or returns 0 (zero) if the times are equal.
If you plan to modify file times for specified files, you can convert a date and time of day to a file time by using the SystemTimeToFileTime function. You can also obtain the system time in a FILETIME structure by calling the GetSystemTimeAsFileTime function.
To make a file time easy to display to a user, use the FileTimeToSystemTime function. FileTimeToSystemTime converts the file time and copies the month, day, year, and time of day from the file time to a SYSTEMTIME structure.
File Times and Daylight Saving Time
You must take care when using file times if the user has set the system to automatically adjust for daylight saving time.
To convert a file time to local time, use the FileTimeToLocalFileTime function. However, FileTimeToLocalFileTime uses the current settings for the time zone and daylight saving time. Therefore, if it is daylight saving time, it takes daylight saving time into account, even if the file time you are converting is in standard time.
The FAT file system records times on disk in local time. GetFileTime retrieves cached UTC times from the FAT file system. When it becomes daylight saving time, the time retrieved by GetFileTime is off an hour, because the cache is not updated. When you restart the computer, the cached time that GetFileTime retrieves is correct. FindFirstFile retrieves the local time from the FAT file system and converts it to UTC by using the current settings for the time zone and daylight saving time. Therefore, if it is daylight saving time, FindFirstFile takes daylight saving time into account, even if the file time you are converting is in standard time.
The NTFS file system records times on disk in UTC. To account for daylight saving time when converting a file time to a local time, use the following sequence of functions instead of using FileTimeToLocalFileTime:
File Times and CDFS
The date and time stamps of files that are located on or originate from media using Compact Disc File System (CDFS) are adjusted for the local time zone. ISO 9660 states that CDFS is to display the date information correctly for the local time zone. This is done so that dates for files on CDFS are displayed the same as those on Universal Disk Format (UDF). UDF is the newer standard for distribution media. If your code depends on the unmodified date information for a file that resides on or originates from media using CDFS, it may not function correctly.
