Win32 File System API

This document outlines key functions and concepts for interacting with the file system in the Windows API (Win32).

Core File Operations

CreateFile
HANDLE CreateFile( _In_ LPCTSTR lpFileName, _In_ DWORD dwDesiredAccess, _In_ DWORD dwShareMode, _In_opt_ LPSECURITY_ATTRIBUTES lpSecurityAttributes, _In_ DWORD dwCreationDisposition, _In_ DWORD dwFlagsAndAttributes, _In_opt_ HANDLE hTemplateFile );

Creates or opens a file or I/O device. It is the primary function for accessing files.

Parameters:
  • lpFileName: The name of the file to be created or opened.
  • dwDesiredAccess: The type of access to the file (e.g., GENERIC_READ, GENERIC_WRITE).
  • dwShareMode: How the file will be shared.
  • lpSecurityAttributes: Security descriptor.
  • dwCreationDisposition: Action to take if the file exists or does not exist.
  • dwFlagsAndAttributes: File attributes and flags.
  • hTemplateFile: Handle to a template file.
Return Value:
  • If the function succeeds, the return value is an open handle to the specified file.
  • If the function fails, the return value is INVALID_HANDLE_VALUE.
ReadFile
BOOL ReadFile( _In_ HANDLE hFile, _Out_ LPVOID lpBuffer, _In_ DWORD nNumberOfBytesToRead, _Out_opt_ LPDWORD lpNumberOfBytesRead, _Inout_opt_ LPOVERLAPPED lpOverlapped );

Reads data from a file or from the communication port specified by a handle.

Parameters:
  • hFile: Handle to the file to be read.
  • lpBuffer: Pointer to the buffer that receives the data read from the file.
  • nNumberOfBytesToRead: The maximum number of bytes to be read.
  • lpNumberOfBytesRead: Pointer to the number of bytes read.
  • lpOverlapped: Pointer to an OVERLAPPED structure.
Return Value:
  • TRUE if the function succeeds or the function completes asynchronously.
  • FALSE if the function fails.
WriteFile
BOOL WriteFile( _In_ HANDLE hFile, _In_ LPCVOID lpBuffer, _In_ DWORD nNumberOfBytesToWrite, _Out_opt_ LPDWORD lpNumberOfBytesWritten, _Inout_opt_ LPVOID lpOverlapped );

Writes data to a file or to the communication port specified by a handle.

Parameters:
  • hFile: Handle to the file to be written to.
  • lpBuffer: Pointer to a buffer containing the data to be written.
  • nNumberOfBytesToWrite: The number of bytes to write.
  • lpNumberOfBytesWritten: Pointer to the number of bytes written.
  • lpOverlapped: Pointer to an OVERLAPPED structure.
Return Value:
  • TRUE if the function succeeds or the function completes asynchronously.
  • FALSE if the function fails.
CloseHandle
BOOL CloseHandle( _In_ HANDLE hObject );

Closes an open object handle. Applications must call this function for every handle that it opens.

Parameters:
  • hObject: A handle to an open object.
Return Value:
  • TRUE if the function succeeds.
  • FALSE if the function fails.

Directory Operations

CreateDirectory
BOOL CreateDirectory( _In_ LPCTSTR lpPathName, _In_opt_ LPSECURITY_ATTRIBUTES lpAttribute );

Creates a new directory with the specified path.

Parameters:
  • lpPathName: The path of the directory to create.
  • lpAttribute: Security attributes.
Return Value:
  • TRUE if the directory is created successfully.
  • FALSE if the directory creation fails.
RemoveDirectory
BOOL RemoveDirectory( _In_ LPCTSTR lpPathName );

Deletes an existing empty directory.

Parameters:
  • lpPathName: Path of the directory to be removed.
Return Value:
  • TRUE if the directory is removed successfully.
  • FALSE if the directory removal fails (e.g., directory not empty).

File Information

GetFileAttributes
DWORD GetFileAttributes( _In_ LPCTSTR lpFileName );

Retrieves the attributes of a specified file or directory.

Parameters:
  • lpFileName: The name of the file or directory.
Return Value:
  • If the function succeeds, the return value is the attribute bits for the specified file.
  • If the function fails, the return value is INVALID_FILE_ATTRIBUTES.
Common Attributes:
  • FILE_ATTRIBUTE_NORMAL
  • FILE_ATTRIBUTE_READONLY
  • FILE_ATTRIBUTE_HIDDEN
  • FILE_ATTRIBUTE_DIRECTORY
  • FILE_ATTRIBUTE_ARCHIVE
SetFileAttributes
BOOL SetFileAttributes( _In_ LPCTSTR lpszFileName, _In_ DWORD dwFileAttributes );

Sets the attributes of a specified file or directory.

Parameters:
  • lpszFileName: The name of the file or directory.
  • dwFileAttributes: The new file attributes.
Return Value:
  • TRUE if the function succeeds.
  • FALSE if the function fails.

Common Concepts

< Previous Next >