GetFileTime function

Retrieves the date and time that a file or directory was created, last accessed, and last modified.

Syntax


BOOL WINAPI GetFileTime(
  _In_       HANDLE hFile,
  _Out_opt_  LPFILETIME lpCreationTime,
  _Out_opt_  LPFILETIME lpLastAccessTime,
  _Out_opt_  LPFILETIME lpLastWriteTime
);

Parameters

hFile [in]

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.

lpCreationTime [out, optional]

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.

lpLastAccessTime [out, optional]

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.

lpLastWriteTime [out, optional]

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.

Examples

For an example, see Retrieving the Last-Write Time.

Requirements

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

FileAPI.h (include Windows.h);
WinBase.h on Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003, and Windows XP (include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll

See also

File Times
FILETIME
GetFileSize
GetFileType
SetFileTime
Time Functions

 

 

Community Additions

ADD
Show:
© 2014 Microsoft