File Times
A file time represents the specific date and time at which a given file was created, last accessed, or last written to. Windows records file times whenever applications create, access, and write to files. Windows records the times using a 64-bit value specifying the number of 100-nanosecond intervals that have elapsed since 12:00 A.M. January 1, 1601 (UTC). Writing to a file changes the last write time; writing to or reading from the file (including running an executable file) changes the last access time.

Note Not all file systems can record creation and last access time. In particular, the file allocation table (FAT) file system records only last-write times.

You can retrieve the file times for a given file by using the GetFileTime function. GetFileTime copies the creation, last access, and last write times to individual FILETIME structures. Each structure consists of two 32-bit values that combine to form the single 64-bit value. You can also retrieve the file times by using the FindFirstFile and FindNextFile functions. These functions copy the times to FILETIME structures in a WIN32_FIND_DATA structure.

You can set the file times for a file by using 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 indicating which time is greater or returns zero if the times are equal.
To make a file time more meaningful to a user, you can extract the month, day, year, and time of day from a file time by using the FileTimeToSystemTime function. FileTimeToSystemTime converts the file time and copies the individual values for date and time of day to a SYSTEMTIME structure.

Windows records all file times in UTC-based times, but you can convert a file time to the local time for your time zone by using the FileTimeToLocalFileTime function. Before displaying a file time to a user, applications typically convert the file time to local time, then extract the month, day, year and time of day using FileTimeToSystemTime.
If you plan to modify file times for given 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 FILETIME structure by calling the GetSystemTimeAsFileTime function.

If the original date and time of day are given in the local time for your time zone, you can convert the resulting file time to UTC by using the LocalFileTimeToFileTime function. Always make sure the file times you set using SetFileTime are valid UTC-based times.

The GetFileTime function retrieves the date and time that a file was created, last accessed, and last modified.

BOOL GetFileTime(

HANDLE hFile, // identifies the file
LPFILETIME lpCreationTime, // address of creation time
LPFILETIME lpLastAccessTime, // address of last access time
LPFILETIME lpLastWriteTime // address of last write time
);

Parameters

hFile

Identifies the files for which to get dates and times. The file handle must have been created with GENERIC_READ access to the file.

lpCreationTime

Points to a FILETIME structure to receive the date and time the file was created. This parameter can be NULL if the application does not require this information.

lpLastAccessTime

Points to a FILETIME structure to receive the date and time the file was last accessed. The last access time includes the last time the file 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.

lpLastWriteTime

Points to a FILETIME structure to receive the date and time the file was last written to. This parameter can be NULL if the application does not require this information.


Return Values

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

The FAT and New Technology file systems support the file creation, last access, and last write time values.
Windows 95: The precision of the time for a file in a FAT file system is 2 seconds. The time precision for files in other file systems, such as those connected through a network depends on the file system but may also be limited by the remote device.

See Also

FILETIME, GetFileSize, GetFileType, SetFileTime

The FILETIME structure is a 64-bit value representing the number of 100-nanosecond intervals since January 1, 1601.

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


Members

dwLowDateTime   -  Specifies the low-order 32 bits of the file time.

dwHighDateTime      - Specifies the high-order 32 bits of the file time.

Remarks

It is not recommended that you add and subtract values from the FILETIME structure to obtain relative times. Instead, you should

· Copy the resulting FILETIME structure to a LARGE_INTEGER structure.
· Use normal 64-bit arithmetic on the LARGE_INTEGER value.

See Also

CompareFileTime, GetFileTime, LARGE_INTEGER

The WIN32_FIND_DATA structure describes a file found by the FindFirstFile or FindNextFile function.

typedef struct _WIN32_FIND_DATA { // wfd
DWORD dwFileAttributes;
FILETIME ftCreationTime;
FILETIME ftLastAccessTime;
FILETIME ftLastWriteTime;
DWORD nFileSizeHigh;
DWORD nFileSizeLow;
DWORD dwReserved0;
DWORD dwReserved1;
TCHAR cFileName[ MAX_PATH ];
TCHAR cAlternateFileName[ 14 ];
} WIN32_FIND_DATA;


Members

dwFileAttributes - Specifies the file attributes of the file found. This member can be one or more of the following values:

Value Meaning
FILE_ATTRIBUTE_ARCHIVE  - The file is an archive file. Applications use this value to mark files for backup or removal.

FILE_ATTRIBUTE_COMPRESSED  -  The file or directory is compressed. For a file, this means that all of the data in the file is compressed. For a directory, this means that compression is the default for newly created files and subdirectories.

FILE_ATTRIBUTE_DIRECTORY  - The file is a directory.

FILE_ATTRIBUTE_HIDDEN  - The file is hidden. It is not included in an ordinary directory listing.

FILE_ATTRIBUTE_NORMAL  - The file has no other attributes set. This value is valid only if used alone.

FILE_ATTRIBUTE_OFFLINE  - The data of the file is not immediately available. Indicates that the file data has been physically moved to offline storage.

FILE_ATTRIBUTE_READONLY  - The file is read-only. Applications can read the file but cannot write to it or delete it.

FILE_ATTRIBUTE_SYSTEM  - The file is part of the operating system or is used exclusively by it.

FILE_ATTRIBUTE_TEMPORARY  - The file is being used for temporary storage. Applications should write to the file only if absolutely necessary. Most of the file's data remains in memory without being flushed to the media because the file will soon be deleted.

ftCreationTime

Specifies a FILETIME structure containing the time the file was created. FindFirstFile and FindNextFile report file times in Coordinated Universal Time (UTC) format. These functions set the FILETIME members to zero if the file system containing the file does not support this time member. You can use the FileTimeToLocalFileTime function to convert from UTC to local time, and then use the FileTimeToSystemTime function to convert the local time to a SYSTEMTIME structure containing individual members for the month, day, year, weekday, hour, minute, second, and millisecond.

ftLastAccessTime

Specifies a FILETIME structure containing the time that the file was last accessed. The time is in UTC format; the FILETIME members are zero if the file system does not support this time member.

ftLastWriteTime

Specifies a FILETIME structure containing the time that the file was last written to. The time is in UTC format; the FILETIME members are zero if the file system does not support this time member.

nFileSizeHigh

Specifies the high-order DWORD value of the file size, in bytes. This value is zero unless the file size is greater than MAXDWORD. The size of the file is equal to (nFileSizeHigh * MAXDWORD) + nFileSizeLow.

nFileSizeLow

Specifies the low-order DWORD value of the file size, in bytes.

dwReserved0

Reserved for future use.

dwReserved1

Reserved for future use.

cFileName

A null-terminated string that is the name of the file.

cAlternateFileName

A null-terminated string that is an alternative name for the file. This name is in the classic 8.3 (filename.ext) filename format.



Remarks

If a file has a long filename, the complete name appears in the cFileName field, and the 8.3 format truncated version of the name appears in the cAlternateFileName field. Otherwise, cAlternateFileName is empty. As an alternative, you can use the GetShortPathName function to find the 8.3 format version of a filename.

See Also

FindFirstFile, FindNextFile, FILETIME, FileTimeToLocalFileTime, FileTimeToSystemTime, GetShortPathName

The SetFileTime function sets the date and time that a file was created, last accessed, or last modified.

SetFileTime
Windows NT Yes
Win95 Yes
Win32s Yes
Import Library kernel32.lib
Header File winbase.h
Unicode No
Platform Notes None
 

BOOL SetFileTime(

HANDLE hFile, // identifies 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
);


Parameters

hFile

Identifies the file for which to set the dates and times. The file handle must have been created with GENERIC_WRITE access to the file.

lpCreationTime

Points to a FILETIME structure that contains the date and time the file was created. This parameter can be NULL if the application does not need to set this information.

lpLastAccessTime

Points to a FILETIME structure that contains the date and time the file was last accessed. The last access time includes the last time the file was written to, read from, or (in the case of executable files) run. This parameter can be NULL if the application does not need to set this information.

lpLastWriteTime

Points to a FILETIME structure that contains the date and time the file was last written to. This parameter can be NULL if the application does not want to set this information.



Return Values

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

The FAT and New Technology file systems support the file creation, last access, and last write time values.

See Also

FILETIME, GetFileSize, GetFileTime, GetFileType

The CompareFileTime function compares two 64-bit file times.

LONG CompareFileTime(

CONST FILETIME *lpFileTime1, // pointer to first file time
CONST FILETIME *lpFileTime2 // pointer to second file time
);


Parameters

lpFileTime1

Points to a FILETIME structure that specifies the first 64-bit file time.

lpFileTime2

Points to a FILETIME structure that specifies the second 64-bit file time.



Return Values

If the function succeeds, the return value is one of the following values:

Value Meaning
-1 First file time is less than second file time.
0 First file time is equal to second file time.
+1 First file time is greater than second file time.


See Also

GetFileTime, FILETIME

The FileTimeToSystemTime function converts a 64-bit file time to system time format.

BOOL FileTimeToSystemTime(

CONST FILETIME *lpFileTime, // pointer to file time to convert
LPSYSTEMTIME lpSystemTime // pointer to structure to receive system time
);


Parameters

lpFileTime

Pointer to a FILETIME structure containing the file time to convert to system date and time format.
The FileTimeToSystemTime function only works with FILETIME values that are less than 0x8000000000000000. The function fails with values equal to or greater than that.

lpSystemTime

Pointer to a SYSTEMTIME structure to receive the converted file time.



Return Values

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

As noted above, the function fails for FILETIME values that are equal to or greater than 0x8000000000000000.

See Also

DosDateTimeToFileTime, FILETIME, FileTimeToDosDateTime, SYSTEMTIME, SystemTimeToFileTime

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

typedef struct _SYSTEMTIME { // st
WORD wYear;
WORD wMonth;
WORD wDayOfWeek;
WORD wDay;
WORD wHour;
WORD wMinute;
WORD wSecond;
WORD wMilliseconds;
} SYSTEMTIME;


Members

wYear - Specifies the current year.

wMonth - Specifies the current month; January = 1, February = 2, and so on.

wDayOfWeek - Specifies the current day of the week; Sunday = 0, Monday = 1, and so on.

wDay - Specifies the current day of the month.

wHour - Specifies the current hour.

wMinute - Specifies the current minute.

wSecond - Specifies the current second.

wMilliseconds - Specifies the current millisecond.

Remarks

It is not recommended that you add and subtract values from the SYSTEMTIME structure to obtain relative times. Instead, you should

· Convert the SYSTEMTIME structure to a FILETIME structure.
· Copy the resulting FILETIME structure to a LARGE_INTEGER structure.
· Use normal 64-bit arithmetic on the LARGE_INTEGER value.


See Also

FILETIME, GetSystemTime, LARGE_INTEGER, SetSystemTime

The FileTimeToLocalFileTime function converts a file time based on the Coordinated Universal Time (UTC) to a local file time.

BOOL FileTimeToLocalFileTime(

CONST FILETIME *lpFileTime, // pointer to UTC file time to convert
LPFILETIME lpLocalFileTime // pointer to converted file time
);


Parameters

lpFileTime

Points to a FILETIME structure containing the UTC-based file time to be converted into a local file time.

lpLocalFileTime

Points to a FILETIME structure to receive the converted local file time. This parameter cannot be the same as the lpFileTime parameter.



Return Values

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.

See Also

FILETIME, LocalFileTimeToFileTime

The SystemTimeToFileTime function converts a system time to a file time.

BOOL SystemTimeToFileTime(

CONST SYSTEMTIME *lpSystemTime, // address of system time to convert
LPFILETIME lpFileTime // address of buffer for converted file time
);


Parameters

lpSystemTime

Points to a SYSTEMTIME structure that contains the time to be converted.
The wDayOfWeek member of the SYSTEMTIME structure is ignored.

lpFileTime

Points to a FILETIME structure to receive the converted system time.



Return Values

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.

See Also

DosDateTimeToFileTime, FILETIME, FileTimeToDosDateTime, FileTimeToSystemTime, SYSTEMTIME

The GetSystemTimeAsFileTime function obtains the current system date and time. The information is in Coordinated Universal Time (UTC) format.

VOID GetSystemTimeAsFileTime(

LPFILETIME lpSystemTimeAsFileTime // pointer to a file time structure
);

Parameters

lpSystemTimeAsFileTime - Pointer to a FILETIME structure to receive the current system date and time in UTC format.

Return Values -  This function does not return a value.

Remarks

The GetSystemTimeAsFileTime function is equivalent to the following code sequence:

FILETIME ft;
SYSTEMTIME st;

GetSystemTime(&st);
SystemTimeToFileTime(&st,&ft);

See Also

FILETIME, GetSystemTime, SYSTEMTIME, SystemTimeToFileTime

The LocalFileTimeToFileTime function converts a local file time to a file time based on the Coordinated Universal Time (UTC).

BOOL LocalFileTimeToFileTime(

CONST FILETIME *lpLocalFileTime, // address of local file time to convert
LPFILETIME lpFileTime // address of converted file time
);


Parameters

lpLocalFileTime

Points to a FILETIME structure that specifies the local file time to be converted into a UTC-based file time.

lpFileTime

Points to a FILETIME structure to receive the converted UTC-based file time. This parameter cannot be the same as the lpLocalFileTime parameter.

Return Values

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

See Also

FILETIME, FileTimeToLocalFileTime