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 the file or I/O device (such as a socket or pipe) that is being written to. This handle must have been created with the `GENERIC_WRITE` access right.
`lpBuffer`	A pointer to a buffer that contains the data to be written to the file or device.
`nNumberOfBytesToWrite`	The number of bytes, in bytes, to write to the file or device.
`lpNumberOfBytesWritten`	A pointer to a variable that receives the number of bytes actually written by this function. If this parameter is `NULL` and the function returns `TRUE`, the number of bytes written is zero. If this parameter is `NULL` and the function returns `FALSE`, the function sets the last error to `ERROR_INVALID_PARAMETER`.
`lpOverlapped`	A pointer to an `OVERLAPPED` structure, which is required for asynchronous I/O operations and can be used for synchronous operations. If this parameter is `NULL`, the function blocks until all of the data is written to the file or device before returning. If this parameter is not `NULL`, the function returns immediately, and the bytes are written to the specified file or device as part of an asynchronous operation. For asynchronous operations, the `hEvent` member of the `OVERLAPPED` structure must be set to a valid event handle.

Return Value

If the function succeeds, the return value is nonzero (TRUE).

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

Important

To ensure that the data is written to disk, call the FlushFileBuffers function.

Remarks

WriteFile writes data to the file specified by the hFile parameter, starting at the current file position. It requires that the handle was created with the GENERIC_WRITE access right.

The function can operate in either synchronous or asynchronous mode, depending on how the file handle was created and whether the lpOverlapped parameter is NULL.

Synchronous Operation: If lpOverlapped is NULL, WriteFile blocks until the data is written or an error occurs. The number of bytes written is returned in lpNumberOfBytesWritten.
Asynchronous Operation: If lpOverlapped is not NULL and the handle was created with FILE_FLAG_OVERLAPPED, WriteFile returns immediately. The actual write operation occurs in the background. The lpNumberOfBytesWritten parameter is valid only after the asynchronous operation has completed. You can use GetOverlappedResult to obtain the number of bytes written.

If lpOverlapped is not NULL, the Offset member of the OVERLAPPED structure specifies the starting position in the file for writing. If FILE_FLAG_RANDOM_ACCESS is specified, the starting position is the Offset. If FILE_FLAG_SEQUENTIAL_SCAN is specified, the Offset is ignored, and data is written at the current file position.

If the file is opened with FILE_APPEND_ACCESS, the file position is automatically set to the end of the file before writing, regardless of the lpOverlapped parameter.

Note

When writing to a communications device, the nNumberOfBytesToWrite parameter should not exceed the size of the buffer specified in the COMMTIMEOUTS structure associated with the communications device.

Microsoft Learn