Microsoft Learn

Opens or creates a file or I/O device (such as a COM port).

This function is typically used to perform general I/O operations on a file. For specific operations, consider using specialized functions such as CreateFileMapping, CreateNamedPipe, or CreateToolhelp32Snapshot.

Parameters

Return value

Remarks

The CreateFileW function is the most versatile function for opening files and devices. It can be used to open any file or device that can be accessed with a handle.

When opening a file, CreateFileW can return a handle to an existing file or create a new file, depending on the value of dwCreationDisposition.

When opening a device, such as a serial port, CreateFileW can be used to set various device parameters by specifying flags in dwFlagsAndAttributes.

File Attributes and Flags

The dwFlagsAndAttributes parameter can be used to specify various file attributes and flags. Some common flags include:

• FILE_ATTRIBUTE_NORMAL: Normal file. Applications use this attribute for files that do not have any other attributes set. This attribute is valid only on Windows.
• FILE_FLAG_BACKUP_SEMANTICS: This flag indicates that the file is being opened for backup or restore. The system ensures that the application can access the file even if the file contains data that cannot otherwise be accessed.
• FILE_FLAG_DELETE_ON_CLOSE: Indicates that a file or directory is to be deleted when the last handle to it is closed.
• FILE_FLAG_OVERLAPPED: The file is being opened for asynchronous I/O.

Sharing Mode

The dwShareMode parameter is crucial for concurrent access to files. Setting it to 0 effectively locks the file for the calling process until the handle is closed. Carefully choose the share mode to prevent data corruption in multi-threaded or multi-process scenarios.

Examples

Here's a simple example of how to create or open a file for writing:

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

int main() {
    HANDLE hFile = CreateFileW(
        L"my_document.txt",          // File name
        GENERIC_WRITE,               // Desired access: write only
        0,                           // Share mode: no sharing
        NULL,                        // Security attributes: default
        CREATE_ALWAYS,               // Creation disposition: create or overwrite
        FILE_ATTRIBUTE_NORMAL,       // Flags and attributes: normal
        NULL                         // Template file: none
    );

    if (hFile == INVALID_HANDLE_VALUE) {
        std::cerr << "Failed to open or create file. Error: " << GetLastError() << std::endl;
        return 1;
    }

    std::cout << "File opened/created successfully. Handle: " << hFile << std::endl;

    // Write some data to the file (example)
    const char* data = "Hello from CreateFileW!\r\n";
    DWORD bytesWritten;
    if (!WriteFile(hFile, data, strlen(data), &bytesWritten, NULL)) {
        std::cerr << "Failed to write to file. Error: " << GetLastError() << std::endl;
    } else {
        std::cout << "Successfully wrote " << bytesWritten << " bytes." << std::endl;
    }

    CloseHandle(hFile);
    std::cout << "File handle closed." << std::endl;

    return 0;
}
                

Requirements

	Value
Minimum supported client	Windows 2000 Professional
Minimum supported server	Windows 2000 Server
Header	fileapi.h (include Windows.h)
Library	Kernel32.lib
DLL	Kernel32.dll
Unicode and ANSI versions	CreateFileW (Unicode) and CreateFileA (ANSI) are available.

See also

• File Management Functions
• CreateFileMapping
• CreateNamedPipe
• CreateToolhelp32Snapshot
• GetLastError
• CloseHandle
• ReadFile
• WriteFile
• SECURITY_ATTRIBUTES