File Attributes

Introduction

File attributes are metadata associated with files and directories in the Windows operating system. These attributes provide information about the file's state, properties, and how it should be treated by the system and applications. Understanding these attributes is crucial for effective file management, security, and performance optimization.

The Windows API provides several functions to retrieve and set file attributes. The most common function for this purpose is GetFileAttributes and SetFileAttributes.

Common File Attributes

The following are some of the most commonly encountered file attributes:

• FILE_ATTRIBUTE_READONLY The file is read-only. Applications can read the file, but cannot write to it or delete it.
• FILE_ATTRIBUTE_HIDDEN The file is hidden. It is not included in an ordinary directory listing.
• FILE_ATTRIBUTE_SYSTEM The file is a system file. Files that have this attribute are protected by the operating system.
• FILE_ATTRIBUTE_DIRECTORY This attribute indicates that the file is a directory.
• FILE_ATTRIBUTE_ARCHIVE The file is an archive file. Applications use this attribute to mark files for backup or removal.
• FILE_ATTRIBUTE_NORMAL This attribute has no special meaning and can be used to distinguish a file that has no attributes set.
• 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 enabled and attributes are inherited from the directory.
• FILE_ATTRIBUTE_ENCRYPTED The file or directory is encrypted using the Encrypting File System (EFS). For a directory, this means that encryption is enabled, and attributes are inherited from that directory.
• FILE_ATTRIBUTE_TEMPORARY The file is a temporary file. Applications can move the file into memory to allow fast temporary access. The system can delete it when it has finished using it.

Retrieving File Attributes

The GetFileAttributes function retrieves the attributes for a specified file or directory.

Function Signature

DWORD GetFileAttributesA(
      LPCSTR lpFileName
    );

    DWORD GetFileAttributesW(
      LPCWSTR lpFileName
    );
    

Parameters:

• lpFileName: A null-terminated string that specifies the name of the file or directory.

Return Value:

• If the function succeeds, the return value is the attribute pack for the specified file or directory.
• If the function fails, the return value is INVALID_FILE_ATTRIBUTES (0xFFFFFFFF). To get extended error information, call GetLastError.

Example (C++)

#include <windows.h>
#include <iostream>

int main() {
    DWORD attributes = GetFileAttributesA("MyDocument.txt");

    if (attributes == INVALID_FILE_ATTRIBUTES) {
        std::cerr << "Error retrieving file attributes. Error code: " << GetLastError() << std::endl;
    } else {
        std::cout << "File Attributes for MyDocument.txt:" << std::endl;
        if (attributes & FILE_ATTRIBUTE_READONLY) std::cout << "- Read-Only" << std::endl;
        if (attributes & FILE_ATTRIBUTE_HIDDEN) std::cout << "- Hidden" << std::endl;
        if (attributes & FILE_ATTRIBUTE_SYSTEM) std::cout << "- System" << std::endl;
        if (attributes & FILE_ATTRIBUTE_DIRECTORY) std::cout << "- Directory" << std::endl;
        if (attributes & FILE_ATTRIBUTE_ARCHIVE) std::cout << "- Archive" << std::endl;
        if (attributes & FILE_ATTRIBUTE_NORMAL) std::cout << "- Normal" << std::endl;
        if (attributes & FILE_ATTRIBUTE_COMPRESSED) std::cout << "- Compressed" << std::endl;
        if (attributes & FILE_ATTRIBUTE_ENCRYPTED) std::cout << "- Encrypted" << std::endl;
        if (attributes & FILE_ATTRIBUTE_TEMPORARY) std::cout << "- Temporary" << std::endl;
    }
    return 0;
}
            

Setting File Attributes

The SetFileAttributes function modifies the attributes for a specified file or directory.

Function Signature

BOOL SetFileAttributesA(
      LPCSTR lpFileName,
      DWORD  dwFileAttributes
    );

    BOOL SetFileAttributesW(
      LPCWSTR lpFileName,
      DWORD   dwFileAttributes
    );
    

Parameters:

• lpFileName: A null-terminated string that specifies the name of the file or directory.
• dwFileAttributes: The new attribute pack for the file or directory. This parameter can be a combination of the attribute constants.

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.

Note: You cannot set the FILE_ATTRIBUTE_DIRECTORY attribute using this function. This attribute is managed by the file system.

Example (C++)

#include <windows.h>
#include <iostream>

int main() {
    // Make a file read-only
    if (SetFileAttributesA("MyFile.txt", FILE_ATTRIBUTE_READONLY)) {
        std::cout << "Successfully set MyFile.txt to read-only." << std::endl;
    } else {
        std::cerr << "Error setting file attributes. Error code: " << GetLastError() << std::endl;
    }

    // Remove the hidden attribute
    DWORD currentAttributes = GetFileAttributesA("AnotherFile.dat");
    if (currentAttributes != INVALID_FILE_ATTRIBUTES) {
        DWORD newAttributes = currentAttributes & ~FILE_ATTRIBUTE_HIDDEN; // Use bitwise NOT to clear the bit
        if (SetFileAttributesA("AnotherFile.dat", newAttributes)) {
            std::cout << "Successfully removed hidden attribute from AnotherFile.dat." << std::endl;
        } else {
            std::cerr << "Error removing hidden attribute. Error code: " << GetLastError() << std::endl;
        }
    }
    return 0;
}
            

Related APIs

Explore these related API functions for more comprehensive file system operations:

File Management Functions

Directory Operations

Access Control Lists (ACLs)