GetFileInformationByHandle function
Applies to: desktop apps only
Retrieves file information for the specified file.
For a more advanced version of this function, see GetFileInformationByHandleEx.
To set file information using a file handle, see SetFileInformationByHandle.
Syntax
BOOL WINAPI GetFileInformationByHandle( __in HANDLE hFile, __out LPBY_HANDLE_FILE_INFORMATION lpFileInformation );
Parameters
- hFile [in]
-
A handle to the file that contains the information to be retrieved.
This handle should not be a pipe handle.
- lpFileInformation [out]
-
A pointer to a BY_HANDLE_FILE_INFORMATION structure that receives the file information.
Return value
If the function succeeds, the return value is nonzero and file information data is contained in the buffer pointed to by the lpFileInformation parameter.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Remarks
Depending on the underlying network features of the operating system and the type of server connected to, the GetFileInformationByHandle function may fail, return partial information, or full information for the given file.
You can compare the VolumeSerialNumber and FileIndex members returned in the BY_HANDLE_FILE_INFORMATION structure to determine if two paths map to the same target; for example, you can compare two file paths and determine if they map to the same directory.
Transacted Operations
If there is a transaction bound to the thread at the time of the call, then the function returns the compressed file size of the isolated file view. For more information, see About Transactional NTFS.
Requirements
|
Minimum supported client | Windows XP |
|---|---|
|
Minimum supported server | Windows Server 2003 |
|
Header |
|
|
Library |
|
|
DLL |
|
See also
Send comments about this topic to Microsoft
Build date: 4/17/2012
If you want to get up-to-date information, you'd better use GetFileInformationByHandle.
From FindFileFirst MSDN doc: "In rare cases, file attribute information on NTFS file systems may not be current at the time you call this function. To be assured of getting the current NTFS file system file attributes, call the GetFileInformationByHandle function."
I dare to say that on heavily loaded system running software heavily optimized for performance (i.e. which doesn't call FlushFileBuffers on the left and on the right) these cases are not rare at all, and it is relatively easy to reproduce.
The thing is that FindFirstFile() retrieves information from directory entry which is updated lazily. Maximum latency for directory entry update (if memory serves me well) -- in absense of FlushFileBuffers() calls on modified handle -- is 5 minutes; that's the best we can hope for.
[edit ph:] It should be added that the file still may me modified between querying and evaluating the information. If this is an issue, there are the following possibilities:
- opening the handle exclusively, which might not be desired under all circumstances,
- Using transactional features of the file system (opening the handle via CreateFielTransacted)
- Working on a read-only volume shadow copy (when running for volume-wide operations)
- 3/8/2008
- andrew1165
- 2/10/2011
- unuseddisplayname
If it's a pipe handle the API and similiar API will hang your thread/process.
- 3/14/2009
- eriklitze
- 3/6/2007
- Jack Mathews
