CreateFileA function

The CreateFileA function (and the wide-character version, CreateFileW) creates or opens a file or I/O device.

Syntax


HANDLE CreateFileA(

  LPCSTR lpFileName,

  DWORD dwDesiredAccess,

  DWORD dwShareMode,

  LPSECURITY_ATTRIBUTES lpSecurityAttributes,

  DWORD dwCreationDisposition,

  DWORD dwFlagsAndAttributes,

  HANDLE hTemplateFile

);

Parameters

lpFileName
LPCSTR
The name of the file or device to be created or opened. For more information, see the Remarks.
dwDesiredAccess
DWORD
The requested access to the file or device. For a list of valid values, see File Access Permissions. This parameter can be zero, but you cannot open a file or device without at least one access right specified. This parameter can be one or more of the following flags:
- GENERIC_READ
- GENERIC_WRITE
- GENERIC_EXECUTE
- GENERIC_ALL
dwShareMode
DWORD
A bitmask of the transmit attributes that the caller can have for the returned handle. This parameter can be zero or any combination of the following values:
- 0: Exclusive access.
- FILE_SHARE_READ
- FILE_SHARE_WRITE
- FILE_SHARE_DELETE
lpSecurityAttributes
LPSECURITY_ATTRIBUTES
A pointer to a SECURITY_ATTRIBUTES structure that contains the security descriptor for the file or device. If this parameter is NULL, the file or device receives a default security descriptor. The ACLs in the default security descriptor are inherited from the owner of the file or directory when it is created.
dwCreationDisposition
DWORD
An action to take if the file or device exists and what to do if it does not exist. This parameter can be one of the following values:
- CREATE_NEW
- CREATE_ALWAYS
- OPEN_EXISTING
- OPEN_ALWAYS
- TRUNCATE_EXISTING
dwFlagsAndAttributes
DWORD
Flags that specify the file attributes. For a list of valid values, see File Attribute Constants. You can combine values by using the bitwise OR (|) operator.
- FILE_ATTRIBUTE_ARCHIVE
- FILE_ATTRIBUTE_ENCRYPTED
- FILE_ATTRIBUTE_HIDDEN
- FILE_ATTRIBUTE_NORMAL
- FILE_ATTRIBUTE_OFFLINE
- FILE_ATTRIBUTE_READONLY
- FILE_ATTRIBUTE_SYSTEM
- FILE_ATTRIBUTE_TEMPORARY
- FILE_FLAG_BACKUP_SEMANTICS
- FILE_FLAG_DELETE_ON_CLOSE
- FILE_FLAG_NO_BUFFERING
- FILE_FLAG_OPEN_REPARSE_POINT
- FILE_FLAG_OVERLAPPED
- FILE_FLAG_POSIX_SEMANTICS
- FILE_FLAG_SEQUENTIAL_SCAN
- FILE_FLAG_SYNCHRONOUS_IO_ALERT
- FILE_FLAG_SYNCHRONOUS_IO_NONALERT
- FILE_FLAG_WRITE_THROUGH
hTemplateFile
HANDLE
A handle to a template file with the GENERIC_READ access right. The calling process must have the same permissions for the template file that you want the created file to have. This parameter can be NULL.

Return Value

If the function succeeds, the return value is an open handle to the specified file or device. If the function fails, the return value is INVALID_HANDLE_VALUE. To get extended error information, call GetLastError.

Remarks

The CreateFile function can return a handle to a regular file, a named pipe, a mail slot, a communications resource, a disk, or a console buffer.

To create or open a file, specify a file name for the lpFileName parameter. The file must be located on the file system specified by the path.

If the lpFileName parameter specifies a file that does not exist, and dwCreationDisposition is set to CREATE_ALWAYS or OPEN_ALWAYS, the function creates the file. If the file exists, and dwCreationDisposition is set to CREATE_ALWAYS or OPEN_ALWAYS, the function overwrites the existing file.

When opening a file, the dwShareMode parameter determines whether another thread can access the file while it is being opened.

Example

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

int main() {
    HANDLE hFile;
    const char* filename = "my_test_file.txt";

    hFile = CreateFileA(
        filename,                 // File name
        GENERIC_WRITE,            // Desired access
        0,                        // Share mode
        NULL,                     // Security attributes
        CREATE_ALWAYS,            // Creation disposition
        FILE_ATTRIBUTE_NORMAL,    // Flags and attributes
        NULL);                    // Template file

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

    // Write to the file (example)
    char data[] = "Hello, Windows API!";
    DWORD bytesWritten;
    if (!WriteFile(hFile, data, sizeof(data) - 1, &bytesWritten, NULL)) {
        std::cerr << "Failed to write to file. Error: " << GetLastError() << std::endl;
    } else {
        std::cout << "Successfully wrote " << bytesWritten << " bytes to " << filename << std::endl;
    }

    CloseHandle(hFile);
    return 0;
}
            
        