WriteFile Function

The WriteFile function writes data to a specified file or input/output (I/O) device.

Syntax

BOOL WriteFile(
  HANDLE       hFile,
  const VOID   *lpBuffer,
  DWORD        nNumberOfBytesToWrite,
  LPDWORD      lpNumberOfBytesWritten,
  LPOVERLAPPED *lpOverlapped
);

Parameters

Parameter	Description
`hFile`	A handle to a file or I/O device. The handle must have been created by the `CreateFile` function and have the `GENERIC_WRITE` access right.
`lpBuffer`	A pointer to a buffer that contains the data to be written to the file.
`nNumberOfBytesToWrite`	The number of bytes to be written to the file.
`lpNumberOfBytesWritten`	A pointer to a variable that receives the number of bytes actually written by this function. If `lpOverlapped` is `NULL`, this parameter can be `NULL`.
`lpOverlapped`	A pointer to a `OVERLAPPED` structure. If `hFile` was opened with `FILE_FLAG_OVERLAPPED`, this parameter is required. If `hFile` was opened without `FILE_FLAG_OVERLAPPED`, this parameter can be `NULL`.

Return Value

Value	Description
`TRUE`	The function succeeded and all data was written.
`FALSE`	The function failed. To get extended error information, call `GetLastError`.

Remarks

If the file is opened in non-overlapping mode, WriteFile blocks until all data is written to the file. If the file is opened in overlapping mode, WriteFile returns immediately, and the system uses the OVERLAPPED structure to track the write operation.

The file pointer is advanced by the number of bytes written.

To write data to a file, you typically use the following sequence:

Call CreateFile to get a handle to the file.
Prepare a buffer containing the data to be written.
Call WriteFile with the file handle, buffer, and number of bytes to write.
Check the return value and the number of bytes written.
Call CloseHandle when finished with the file.

Example Code

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

int main() {
    HANDLE hFile;
    DWORD dwBytesWritten;
    const char *dataToWrite = "This is some sample data to write to the file.\n";
    DWORD dwBytesToWrite = strlen(dataToWrite);

    hFile = CreateFile(
        "sample.txt",                // File name
        GENERIC_WRITE,                 // Access mode
        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 << "Error creating file: " << GetLastError() << std::endl;
        return 1;
    }

    if (!WriteFile(
        hFile,                         // Handle to the file
        dataToWrite,                   // Data to write
        dwBytesToWrite,                // Number of bytes to write
        &dwBytesWritten,               // Number of bytes written
        NULL)) {                       // Overlapped structure
        std::cerr << "Error writing to file: " << GetLastError() << std::endl;
        CloseHandle(hFile);
        return 1;
    }

    std::cout << dwBytesWritten << " bytes written successfully." << std::endl;

    CloseHandle(hFile);
    return 0;
}