Windows API Reference

Core File Functions

These functions are the building blocks for interacting with the file system.

• CreateFile - Creates or opens a file or I/O device.
• ReadFile - Reads data from a file or I/O device.
• WriteFile - Writes data to a file or I/O device.
• CloseHandle - Closes an open object handle.
• SetFilePointer - Moves the file pointer of the specified file.
• GetFileSizeEx - Retrieves the size of the specified file.

Directory Management

Functions for creating, enumerating, and managing directories.

• CreateDirectory - Creates a directory.
• RemoveDirectory - Deletes an empty directory.
• FindFirstFile - Searches a directory for a file or subdirectory that matches a given string.
• FindNextFile - Continues a file search.
• FindClose - Closes the search handle that the FindFirstFile or FindFirstFileEx function opened.

File Attributes and Metadata

Functions for getting and setting file attributes.

• GetFileAttributes - Retrieves the attributes of a specified file or directory.
• SetFileAttributes - Sets the attributes for a file or a directory.
• GetFileTime - Retrieves the last access, last write, and creation times for a specified file.

CreateFile

Prototype:

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

Description: Creates or opens a file, directory, removable media device, or named pipe described by the `lpFileName` string. This is a versatile function for file system access.

Parameters:

Parameter	Type	Description
lpFileName	LPCSTR	The name of the file or device to be created or opened.
dwDesiredAccess	DWORD	The requested access to the file or device. Common values include GENERIC_READ, GENERIC_WRITE.
dwShareMode	DWORD	A bitmask of the sharing mode that the caller requests for the file or device.
dwCreationDisposition	DWORD	Specifies an action to take if the file exists or does not exist.
dwFlagsAndAttributes	DWORD	File attributes and flags.
lpSecurityAttributes	LPSECURITY_ATTRIBUTES	A pointer to a SECURITY_ATTRIBUTES structure that specifies the security descriptor for the file or directory.
hTemplateFile	HANDLE	A handle to a template file with the desired attributes.

Return Value: 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.

Remarks: For detailed information on values and behaviors, refer to the official Microsoft Docs.

ReadFile

Prototype:

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

Description: Reads data from the specified file or input device. The start of a read operation can be near the end of the file for compressed or encrypted files.

Parameters:

Parameter	Type	Description
hFile	HANDLE	A handle to the file or device that is being read.
lpBuffer	LPVOID	A buffer that receives the data read from the specified file or device.
nNumberOfBytesToRead	DWORD	The maximum number of bytes to be read.
lpNumberOfBytesRead	LPDWORD	A pointer to a variable that receives the number of bytes actually read.
lpOverlapped	LPOVERLAPPED	A pointer to an OVERLAPPED structure or NULL.

Return Value: If the function succeeds, the return value is nonzero. If the function fails, the return value is zero.

Remarks: This function supports both synchronous and asynchronous read operations.

WriteFile

Prototype:

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

Description: Writes data to the specified file or I/O device. This function is suitable for sequential file access.

Parameters:

Parameter	Type	Description
hFile	HANDLE	A handle to the file or device that the data is being written to.
lpBuffer	LPCVOID	A pointer to a buffer that contains the data to be written to the file or device.
nNumberOfBytesToWrite	DWORD	The number of bytes to be written to the file or device.
lpNumberOfBytesWritten	LPDWORD	A pointer to a variable that receives the number of bytes actually written.
lpOverlapped	LPOVERLAPPED	A pointer to an OVERLAPPED structure or NULL.

Return Value: If the function succeeds, the return value is nonzero. If the function fails, the return value is zero.

Remarks: For network file I/O, the `lpOverlapped` parameter should not be NULL if the file is opened with the FILE_FLAG_OVERLAPPED flag.

CreateDirectory

Prototype:

BOOL CreateDirectory(
  LPCSTR lpPathName,
  LPSECURITY_ATTRIBUTES lpAttribute
);

Description: Creates a new directory with the specified path. If the directory already exists, the function fails.

Parameters:

Parameter	Type	Description
lpPathName	LPCSTR	The path of the directory to be created.
lpAttribute	LPSECURITY_ATTRIBUTES	A pointer to a SECURITY_ATTRIBUTES structure that determines whether the handle can be inherited by child processes.

Return Value: If the function succeeds, the return value is nonzero. If the function fails, the return value is zero.

Remarks: Use CreateDirectoryEx for more control over attributes and template files.