File I/O Functions

The File I/O (Input/Output) API in the Windows operating system provides a comprehensive set of functions for managing files, directories, and data streams. These functions allow applications to create, read, write, delete, and control access to files on various storage devices.

Core Concepts

Handles: A handle is an identifier that represents an open file or other I/O object.
File Streams: Data is typically read from or written to files sequentially.
Asynchronous I/O: Allows applications to perform I/O operations without blocking the main thread.
File Attributes: Properties associated with a file, such as read-only, hidden, or system.

Key Functions

Creating and Opening Files

These functions are used to create new files or open existing ones for various operations.

Function Name	Description	Syntax Example
`CreateFile`	Creates or opens a file or I/O device. Returns a handle to the specified file.	`HANDLE CreateFile(LPCSTR lpFileName, DWORD dwDesiredAccess, DWORD dwShareMode, LPSECURITY_ATTRIBUTES lpSecurityAttributes, DWORD dwCreationDisposition, DWORD dwFlagsAndAttributes, HANDLE hTemplateFile);`
`OpenFile`	Opens an existing file. (Older API, `CreateFile` is generally preferred).	`int OpenFile(LPCSTR lpFileName, LPOVERLAPPED lpOverlapped, DWORD ulFlags);`

Reading from and Writing to Files

Functions for transferring data between memory and files.

Function Name	Description	Syntax Example
`ReadFile`	Reads data from a file or I/O device into memory.	`BOOL ReadFile(HANDLE hFile, LPVOID lpBuffer, DWORD nNumberOfBytesToRead, LPDWORD lpNumberOfBytesRead, LPOVERLAPPED lpOverlapped);`
`WriteFile`	Writes data from memory to a file or I/O device.	`BOOL WriteFile(HANDLE hFile, LPCVOID lpBuffer, DWORD nNumberOfBytesToWrite, LPDWORD lpNumberOfBytesWritten, LPOVERLAPPED lpOverlapped);`
`ReadFileEx`	Reads data from a file or I/O device asynchronously.	`BOOL ReadFileEx(HANDLE hFile, LPVOID lpBuffer, DWORD nNumberOfBytesToRead, LPOVERLAPPED lpOverlapped, LPOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine);`
`WriteFileEx`	Writes data from memory to a file or I/O device asynchronously.	`BOOL WriteFileEx(HANDLE hFile, LPCVOID lpBuffer, DWORD nNumberOfBytesToWrite, LPOVERLAPPED lpOverlapped, LPOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine);`

File Positioning and Information

Functions for controlling the current file position and retrieving file metadata.

Function Name	Description	Syntax Example
`SetFilePointer`	Moves the file pointer to a specified location within a file.	`DWORD SetFilePointer(HANDLE hFile, LONG lDistanceToMove, PLONG lpDistanceToMoveHigh, DWORD dwMoveMethod);`
`GetFileSizeEx`	Retrieves the size of a specified file.	`BOOL GetFileSizeEx(HANDLE hFile, PLARGE_INTEGER lpFileSize);`
`GetFileAttributes`	Retrieves the attributes of a specified file or directory.	`DWORD GetFileAttributes(LPCTSTR lpFileName);`
`SetFileAttributes`	Sets the attributes of a specified file or directory.	`BOOL SetFileAttributes(LPCTSTR lpFileName, DWORD dwFileAttributes);`

File Deletion and Management

Functions for deleting files and managing directory structures.

Function Name	Description	Syntax Example
`DeleteFile`	Deletes an existing file.	`BOOL DeleteFile(LPCTSTR lpFileName);`
`MoveFile`	Moves an existing file or directory from one location to another.	`BOOL MoveFile(LPCTSTR lpExistingFileName, LPCTSTR lpNewFileName);`
`CopyFile`	Copies an existing file to a new location.	`BOOL CopyFile(LPCTSTR lpExistingFileName, LPCTSTR lpNewFileName, BOOL bFailIfExists);`
`CreateDirectory`	Creates a new directory.	`BOOL CreateDirectory(LPCTSTR lpPathName, LPSECURITY_ATTRIBUTES lpAttribute);`
`RemoveDirectory`	Deletes an empty directory.	`BOOL RemoveDirectory(LPCTSTR lpPathName);`

Error Handling

Most file I/O functions return specific values or set the last-error code to indicate success or failure. The GetLastError function should be called to retrieve detailed error information.

DWORD dwError = GetLastError();
if (dwError != ERROR_SUCCESS) {
    // Handle the error
}

Note: This documentation provides a high-level overview. For detailed parameter descriptions, return values, and specific usage examples, please refer to the official Microsoft Developer Network (MSDN) documentation.