Core Functions - File Management
This section details the Win32 API functions used for file and directory operations, including creating, reading, writing, deleting, and managing file system objects.
Creates or opens a file or I/O device. It returns a handle that can be used to access the file or device.
| Parameter | Description |
|---|---|
lpFileName |
The name of the file or device. |
dwDesiredAccess |
The access to the file or device. This can be read, write, or both. |
dwShareMode |
The sharing mode of an object, which is the combination of zero or more of the following flags. |
lpSecurityAttributes |
A pointer to a SECURITY_ATTRIBUTES structure that specifies the security descriptor for the object. |
dwCreationDisposition |
Determines whether the file is created or opened. |
dwFlagsAndAttributes |
The file system attributes and flags for the file. |
hTemplateFile |
A handle to a template file with the extended attributes that can be applied to the function. |
If the function succeeds, the return value is an open handle to the specified file or device. If the function fails, the return value is INVALID_HANDLE_VALUE. To get extended error information, call GetLastError.
Reads data from a file or overlapping I/O device. The position is set by the position indicator of the file handle.
| Parameter | Description |
|---|---|
hFile |
A handle to the file or device (CreateFile). |
lpBuffer |
A pointer to the buffer that receives the data read from the file. |
nNumberOfBytesToRead |
The maximum number of bytes to be read. |
lpNumberOfBytesRead |
A pointer to a variable that receives the number of bytes actually read. |
lpOverlapped |
A pointer to an OVERLAPPED structure, used for asynchronous operations. |
If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError.
Writes data to a file or I/O device. The position is set by the position indicator of the file handle.
| Parameter | Description |
|---|---|
hFile |
A handle to the file or device (CreateFile). |
lpBuffer |
A pointer to the buffer containing the data to be written. |
nNumberOfBytesToWrite |
The number of bytes to write. |
lpNumberOfBytesWritten |
A pointer to a variable that receives the number of bytes actually written. |
lpOverlapped |
A pointer to an OVERLAPPED structure, used for asynchronous operations. |
If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError.
Closes an open object handle. For files, this releases the handle and flushes any buffered data.
| Parameter | Description |
|---|---|
hObject |
A handle to an open object such as a file, a pipe, or a process. |
If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError.
Moves the file pointer of the specified file to a location within the file.
| Parameter | Description |
|---|---|
hFile |
A handle to the file. |
lDistanceToMove |
The number of bytes to move the file pointer. |
lpDistanceToMoveHigh |
A pointer to a signed 32-bit value that contains the high-order bits of the distance to move. |
dwMoveMethod |
The starting point for the move. |
If the function succeeds, the return value is the low-order 32 bits of the new file pointer. If the function fails, the return value is 0xFFFFFFFF.
Retrieves the size of the specified file.
| Parameter | Description |
|---|---|
hFile |
A handle to the file. |
lpFileSize |
A pointer to a LARGE_INTEGER structure that receives the file size. |
If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError.
Creates a new directory, including any necessary parent directories.
| Parameter | Description |
|---|---|
lpPathName |
The path of the directory to create. |
lpSecurityAttributes |
A pointer to a SECURITY_ATTRIBUTES structure. |
If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError.
Deletes an existing empty directory.
| Parameter | Description |
|---|---|
lpPathName |
The path of the directory to be removed. |
If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError.
Deletes a specified file.
| Parameter | Description |
|---|---|
lpFileName |
The name of the file to be deleted. |
If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError.
Copies an existing file to a new location.
| Parameter | Description |
|---|---|
lpExistingFileName |
The name of the existing file. |
lpNewFileName |
The name of the new file. |
bFailIfExists |
If this parameter is TRUE and the new file already exists, the function will fail. |
If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError.
Moves an existing file from one directory to another or renames a file.
| Parameter | Description |
|---|---|
lpExistingFileName |
The current name of the file. |
lpNewFileName |
The new name for the file. |
If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError.
Begins the process of searching for files that match a specific pattern.
| Parameter | Description |
|---|---|
lpFindFileData |
A pointer to a null-terminated string that specifies a valid file path or directory. The string can contain wildcard characters (* and ?). |
lpFindData |
A pointer to a WIN32_FIND_DATA structure that receives information about a found file or directory. |
If the function succeeds, the return value is a handle used by the FindNextFile function to retrieve subsequent files. If the function fails, the return value is INVALID_HANDLE_VALUE.
Continues a file search started by a call to the FindFirstFile function.
| Parameter | Description |
|---|---|
hFindFile |
A handle to the file search returned by a previous call to FindFirstFile. |
lpFindFileData |
A pointer to a WIN32_FIND_DATA structure that receives information about the next file. |
If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. If no more files can be found, the return value is zero and GetLastError returns ERROR_NO_MORE_FILES.
Closes the search handle opened by a previous call to FindFirstFile.
| Parameter | Description |
|---|---|
hFindFile |
A handle to the file search returned by FindFirstFile. |
If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError.
Retrieves specified information about an open file.
| Parameter | Description |
|---|---|
hFile |
A handle to the file. |
lpFileInformation |
A pointer to a BY_HANDLE_FILE_INFORMATION structure that receives the information. |
If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError.