File Operations

This section provides comprehensive documentation on Windows API functions for performing file input and output operations. Learn how to create, read, write, delete, and manage files and directories.

Key Concepts

File operations in Windows involve interacting with the file system to manage data stored on persistent storage devices. Key concepts include:

• File Handles: A unique identifier returned by the system when a file is opened. All subsequent operations on that file use this handle.
• File Paths: The string representation of a file or directory's location within the file system hierarchy.
• File Attributes: Metadata associated with a file, such as read-only, hidden, system, archive, etc.
• File I/O Modes: How data is read from or written to a file (e.g., sequential, random access).
• Asynchronous I/O: Performing I/O operations without blocking the calling thread, allowing for better application responsiveness.

Common File Operation Functions

The Windows API provides a rich set of functions for managing files and directories:

Function Name	Description
CreateFile	Creates or opens a file, disk, tape, communication resource, printer, or console screen buffer.
ReadFile	Reads data from a file or input/output (I/O) device.
WriteFile	Writes data to a file or device.
CloseHandle	Closes an open object handle.
DeleteFile	Deletes an existing file.
CopyFile	Copies an existing file to a new location.
MoveFile	Moves an existing file from one directory to another.
GetFileAttributes	Retrieves the attributes of a specified file or directory.
SetFileAttributes	Sets the attributes for a specified file or directory.
CreateDirectory	Creates a new directory.
RemoveDirectory	Deletes an empty directory.
FindFirstFile	Searches a directory for a file or subdirectory with a name that matches a specified string and retrieves information about that occurrence.
FindNextFile	Continues a file search operation.
FindClose	Closes the specified search handle.

CreateFile

The CreateFile function is the primary mechanism for interacting with files. It allows you to specify the file name, desired access permissions, sharing modes, security attributes, and creation disposition.

HANDLE CreateFile(
  LPCSTR               lpFileName,
  DWORD                dwDesiredAccess,
  DWORD                dwShareMode,
  LPSECURITY_ATTRIBUTES lpSecurityAttributes,
  DWORD                dwCreationDisposition,
  DWORD                dwFlagsAndAttributes,
  HANDLE               hTemplateFile
);
        

Parameters:

• lpFileName: The name of the file.
• dwDesiredAccess: The generic access rights to the file (e.g., GENERIC_READ, GENERIC_WRITE).
• dwShareMode: The desired sharing mode (e.g., FILE_SHARE_READ, FILE_SHARE_WRITE).
• lpSecurityAttributes: Security descriptor for the file.
• dwCreationDisposition: Action to take if the file exists or does not exist (e.g., OPEN_EXISTING, CREATE_ALWAYS).
• dwFlagsAndAttributes: File attributes and flags (e.g., FILE_ATTRIBUTE_NORMAL).
• hTemplateFile: Handle to a template file.

Return Value: A handle to the opened file, or INVALID_HANDLE_VALUE on failure.

ReadFile

Reads data from a file or device. This is a synchronous operation by default.

BOOL ReadFile(
  HANDLE       hFile,
  LPVOID       lpBuffer,
  DWORD        nNumberOfBytesToRead,
  LPDWORD      lpNumberOfBytesRead,
  LPOVERLAPPED lpOverlapped
);
        

WriteFile

Writes data to a file or device. This is also a synchronous operation by default.

BOOL WriteFile(
  HANDLE       hFile,
  LPCVOID      lpBuffer,
  DWORD        nNumberOfBytesToWrite,
  LPDWORD      lpNumberOfBytesWritten,
  LPOVERLAPPED lpOverlapped
);
        

CloseHandle

Releases the specified open handle. It is crucial to close handles when they are no longer needed to free up system resources.

BOOL CloseHandle(
  HANDLE hObject
);
        

DeleteFile

Deletes an existing file from the file system.

BOOL DeleteFile(
  LPCSTR lpFileName
);
        

CopyFile

Copies an existing file to a new location. This function can also be used to overwrite an existing destination file.

BOOL CopyFile(
  LPCSTR lpExistingFileName,
  LPCSTR lpNewFileName,
  BOOL   bFailIfExists
);
        

MoveFile

Moves an existing file or directory from one location to another. If the destination is on a different drive, this operation is equivalent to copying and then deleting the source.

BOOL MoveFile(
  LPCSTR lpExistingFileName,
  LPCSTR lpNewFileName
);
        

GetFileAttributes

Retrieves the attributes (like read-only, hidden, etc.) of a specified file or directory.

DWORD GetFileAttributes(
  LPCSTR lpFileName
);
        

The returned value is a combination of attribute flags (e.g., FILE_ATTRIBUTE_READONLY, FILE_ATTRIBUTE_DIRECTORY).

SetFileAttributes

Sets the attributes for a specified file or directory. For example, you can make a file read-only using this function.

BOOL SetFileAttributes(
  LPCSTR lpFileName,
  DWORD  dwFileAttributes
);
        

CreateDirectory

Creates a new directory in the specified path. The parent directories must already exist.

BOOL CreateDirectory(
  LPCSTR               lpPathName,
  LPSECURITY_ATTRIBUTES lpSecurityAttributes
);
        

RemoveDirectory

Deletes an empty directory. If the directory is not empty, the operation will fail.

BOOL RemoveDirectory(
  LPCSTR lpPathName
);
        

FindFirstFile

Initiates a search for a file or subdirectory within a specified directory. It returns information about the first matching entry found.

HANDLE FindFirstFile(
  LPCSTR            lpFileName,
  LPWIN32_FIND_DATA lpFindFileData
);
        

lpFindFileData is a pointer to a WIN32_FIND_DATA structure that receives information about the found file.

FindNextFile

Continues a file search operation that was previously initiated by a call to FindFirstFile.

BOOL FindNextFile(
  HANDLE             hFindFile,
  LPWIN32_FIND_DATA lpFindFileData
);
        

FindClose

Closes a file search handle opened by a previous call to FindFirstFile.

BOOL FindClose(
  HANDLE hFindFile
);