Windows Core APIs - Input/Output (I/O) Reference
This section provides detailed reference information for the core Windows Input/Output (I/O) functions, structures, and concepts. Efficient and robust I/O operations are fundamental to Windows application development.
File I/O
CreateFileW
HANDLE CreateFileW(
LPCWSTR lpFileName,
DWORD dwDesiredAccess,
DWORD dwShareMode,
LPSECURITY_ATTRIBUTES lpSecurityAttributes,
DWORD dwCreationDisposition,
DWORD dwFlagsAndAttributes,
HANDLE hTemplateFile
);
Creates or opens a file or I/O device. This is a foundational function for file operations.
Parameters
| Parameter | Type | Description |
|---|---|---|
lpFileName |
LPCWSTR |
The name of the file or device to be created or opened. |
dwDesiredAccess |
DWORD |
The generic access rights for the file or device. Can be a combination of GENERIC_READ, GENERIC_WRITE, etc. |
dwShareMode |
DWORD |
Specifies how the file or device can be shared by other threads or processes. |
dwCreationDisposition |
DWORD |
Specifies the action to take if the file exists or does not exist. |
dwFlagsAndAttributes |
DWORD |
Flags that control file attributes and operations. |
hTemplateFile |
HANDLE |
Handle to a template file with attributes similar to the one being created. |
Return Value
| Type | Description |
|---|---|
HANDLE |
A handle to the created or opened file or device. INVALID_HANDLE_VALUE on failure. |
Always check the return value of CreateFileW for INVALID_HANDLE_VALUE and use GetLastError to retrieve error information.
ReadFile
BOOL ReadFile(
HANDLE hFile,
LPVOID lpBuffer,
DWORD nNumberOfBytesToRead,
LPDWORD lpNumberOfBytesRead,
LPOVERLAPPED lpOverlapped
);
Reads data from a file or I/O device into a buffer.
Parameters
| Parameter | Type | Description |
|---|---|---|
hFile |
HANDLE |
A handle to the file or device from which data is to be read. |
lpBuffer |
LPVOID |
A pointer to the buffer that receives the data read from the file. |
nNumberOfBytesToRead |
DWORD |
The maximum number of bytes to be read. |
lpNumberOfBytesRead |
LPDWORD |
A pointer to a variable that receives the number of bytes read. |
lpOverlapped |
LPOVERLAPPED |
A pointer to an OVERLAPPED structure for asynchronous I/O. |
Return Value
| Type | Description |
|---|---|
BOOL |
TRUE if the operation is successful; otherwise, FALSE. |
WriteFile
BOOL WriteFile(
HANDLE hFile,
LPCVOID lpBuffer,
DWORD nNumberOfBytesToWrite,
LPDWORD lpNumberOfBytesWritten,
LPOVERLAPPED lpOverlapped
);
Writes data from a buffer to a file or I/O device.
Parameters
| Parameter | Type | Description |
|---|---|---|
hFile |
HANDLE |
A handle to the file or device to which data is to be written. |
lpBuffer |
LPCVOID |
A pointer to the buffer containing the data to be written. |
nNumberOfBytesToWrite |
DWORD |
The number of bytes to write. |
lpNumberOfBytesWritten |
LPDWORD |
A pointer to a variable that receives the number of bytes written. |
lpOverlapped |
LPOVERLAPPED |
A pointer to an OVERLAPPED structure for asynchronous I/O. |
Return Value
| Type | Description |
|---|---|
BOOL |
TRUE if the operation is successful; otherwise, FALSE. |
CloseHandle
BOOL CloseHandle(
HANDLE hObject
);
Closes an open object handle.
Parameters
| Parameter | Type | Description |
|---|---|---|
hObject |
HANDLE |
A handle to an open object. |
Return Value
| Type | Description |
|---|---|
BOOL |
TRUE if the handle was successfully closed; otherwise, FALSE. |
It is crucial to close all handles when they are no longer needed to prevent resource leaks.
Directory Management
FindFirstFileW
HANDLE FindFirstFileW(
LPCWSTR lpFindFileData,
LPWIN32_FIND_DATAW lpFindFileData
);
Searches a directory for a file or subdirectory that matches a specified pattern and retrieves information about that file or subdirectory.
Parameters
| Parameter | Type | Description |
|---|---|---|
lpFileName |
LPCWSTR |
The directory or path, and the file name or pattern. |
lpFindFileData |
LPWIN32_FIND_DATAW |
A pointer to a WIN32_FIND_DATAW structure that receives information about the found file or directory. |
Return Value
| Type | Description |
|---|---|
HANDLE |
A handle for subsequent searches. INVALID_HANDLE_VALUE on failure. |
FindNextFileW
BOOL FindNextFileW(
HANDLE hFindFile,
LPWIN32_FIND_DATAW lpFindFileData
);
Continues a file search started by a previous call to the FindFirstFileW function.
Parameters
| Parameter | Type | Description |
|---|---|---|
hFindFile |
HANDLE |
A handle returned by the FindFirstFileW function. |
lpFindFileData |
LPWIN32_FIND_DATAW |
A pointer to a WIN32_FIND_DATAW structure that receives information about the next file or directory. |
Return Value
| Type | Description |
|---|---|
BOOL |
TRUE if another file or directory was found; FALSE if no more files or directories are found or an error occurred. |
FindClose
BOOL FindClose(
HANDLE hFindFile
);
Closes the search handle and releases any resources associated with the find operation.
Parameters
| Parameter | Type | Description |
|---|---|---|
hFindFile |
HANDLE |
The search handle returned by FindFirstFileW. |
Return Value
| Type | Description |
|---|---|
BOOL |
TRUE if the handle was closed successfully; otherwise, FALSE. |
I/O Control
DeviceIoControl
BOOL DeviceIoControl(
HANDLE hDevice,
DWORD dwIoControlCode,
LPVOID lpInBuffer,
DWORD nInBufferSize,
LPVOID lpOutBuffer,
DWORD nOutBufferSize,
LPDWORD lpBytesReturned,
LPOVERLAPPED lpOverlapped
);
Sends a control code directly to a specified device driver, causing the driver to perform the specified operation.
Parameters
| Parameter | Type | Description |
|---|---|---|
hDevice |
HANDLE |
A handle to the device. |
dwIoControlCode |
DWORD |
The control code for the operation. |
lpInBuffer |
LPVOID |
A pointer to the buffer containing data to be written to the device. |
nInBufferSize |
DWORD |
The size, in bytes, of the buffer pointed to by lpInBuffer. |
lpOutBuffer |
LPVOID |
A pointer to the buffer that receives data from the device. |
nOutBufferSize |
DWORD |
The size, in bytes, of the buffer pointed to by lpOutBuffer. |
lpBytesReturned |
LPDWORD |
A pointer to a variable that receives the size, in bytes, of the data received in lpOutBuffer. |
lpOverlapped |
LPOVERLAPPED |
A pointer to an OVERLAPPED structure. |
Return Value
| Type | Description |
|---|---|
BOOL |
TRUE if the operation is successful; otherwise, FALSE. |