Home Library Learn Downloads Support Community
Sign in | United States - English | |
2 out of 12 rated this helpful - Rate this topic

GetFileAttributesEx function

Applies to: desktop apps | Metro style apps

Retrieves attributes for a specified file or directory.

To perform this operation as a transacted operation, use the GetFileAttributesTransacted function.

Syntax

Copy 
BOOL WINAPI GetFileAttributesEx(
  __in   LPCTSTR lpFileName,
  __in   GET_FILEEX_INFO_LEVELS fInfoLevelId,
  __out  LPVOID lpFileInformation
);

Parameters

lpFileName [in]

The name of the file or directory.

In the ANSI version of this function, the name is limited to MAX_PATH characters. To extend this limit to 32,767 wide characters, call the Unicode version of the function and prepend "\\?\" to the path. For more information, see Naming a File.

fInfoLevelId [in]

A class of attribute information to retrieve.

This parameter can be the following value from the GET_FILEEX_INFO_LEVELS enumeration.

ValueMeaning
GetFileExInfoStandard

The lpFileInformation parameter is a WIN32_FILE_ATTRIBUTE_DATA structure.

 

lpFileInformation [out]

A pointer to a buffer that receives the attribute information.

The type of attribute information that is stored into this buffer is determined by the value of fInfoLevelId.

Return value

If the function succeeds, the return value is a nonzero value.

If the function fails, the return value is zero (0). To get extended error information, call GetLastError.

Remarks

The GetFileAttributes function retrieves file system attribute information. GetFileAttributesEx can obtain other sets of file or directory attribute information. Currently, GetFileAttributesEx retrieves a set of standard attributes that is a superset of the file system attribute information.

When the GetFileAttributesEx function is called on a directory that is a mounted folder, it returns the attributes of the directory, not those of the root directory in the volume that the mounted folder associates with the directory. To obtain the attributes of the associated volume, call GetVolumeNameForVolumeMountPoint to obtain the name of the associated volume. Then use the resulting name in a call to GetFileAttributesEx. The results are the attributes of the root directory on the associated volume.

Symbolic link behavior—If the path points to a symbolic link, the function returns attributes for the symbolic link.

Transacted Operations

If a file is open for modification in a transaction, no other thread can open the file for modification until the transaction is committed. So if a transacted thread opens the file first, any subsequent threads that try modifying the file before the transaction is committed receives a sharing violation. If a non-transacted thread modifies the file before the transacted thread does, and the file is still open when the transaction attempts to open it, the transaction receives the error ERROR_TRANSACTIONAL_CONFLICT.

Requirements

Minimum supported client

Windows XP

Minimum supported server

Windows Server 2003

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

Unicode and ANSI names

GetFileAttributesExW (Unicode) and GetFileAttributesExA (ANSI)

See also

File Attribute Constants
File Management Functions
GetFileAttributes
GetFileAttributesTransacted
SetFileAttributes
Symbolic Links

 

 

Send comments about this topic to Microsoft

Build date: 4/17/2012

Did you find this helpful?
(1500 characters remaining)
Community Content Add
Annotations FAQ
Creation Time Problems
The creation time issue described below where deleting a file and creating a new one with the same name leaves the new file with the creation time of the first file is due to tunnelling. See this article: http://support.microsoft.com/default.aspx?scid=kb%3Ben-us%3B172190
History
Problem getting correct Creation Time after file was recreated
I tried to use GetFileAttributesEx and then get ftCreationTime field of the resulting WIN32_FILE_ATTRIBUTE_DATA structure. It works just fine at first, but after I delete file and recreate again, it keeps giving me the original already incorrect value until I restart the process again. The same problem happens for FindFirstFile API, as well. I use Window 2003. Any ideas?
History
Beware: Size values unpredictable for directories.
As the WIN32_FILE_ATTRIBUTE_DATA page says, the size values (nFileSizeHigh and nFileSizeLow) do not have meaning for directories.

Be careful not to use the size values at all for directories. In particular, you cannot rely on them being zero (even if you wipe the struct before the call).

The reported sizes are usually zero for directories but not always.

It may seem obvious to ignore directory sizes but I ran into this where my code was acting as a callback for a 3rd party library. That library did (for some reason) request the directory sizes and went horribly wrong if anything other than zero was returned. Things were fine until I ran into a directory which (for some reason) had its size reported as 0x1000 instead of the usual zero.

(Sorry if this appears multiple times. The server keeps returning an error when I submit.)
History
Doesn't always work
I've encountered some problems with GetFileAttributesEx.  For example, on some systems it fails with a sharing violation when attempting to get attributes for c:\pagefile.sys.  FindFirstFile doesn't appear to suffer from this problem, although that may have its own weaknesses.
History
Alternative to using unmanaged code

As an alternative to using this unmanaged API, consider using the System.IO.FileSystemInfo's GetAttributes. See http://msdn.microsoft.com/en-us/library/system.io.filesysteminfo.attributes.aspx for more details on this property.

History
C# syntax 
[DllImport("kernel32.dll", CharSet=CharSet.Auto, SetLastError=true)]
internal static extern bool GetFileAttributesEx(string name, int fileInfoLevel, ref WIN32_FILE_ATTRIBUTE_DATA lpFileInformation);
History
vb.net syntax 
<DllImport("kernel32.dll", CharSet:=CharSet.Auto, SetLastError:=True)> _
Public Shared Function GetFileAttributesEx(ByVal name As String, ByVal fileInfoLevel As Integer, ByRef lpFileInformation As WIN32_FILE_ATTRIBUTE_DATA) As Boolean
End Function
History