File Operations

This section provides details on the Windows API functions for managing files and directories, including creating, reading, writing, and deleting files, as well as directory traversal.

CreateFile

Creates or opens a file or I/O device (such as a serial port, disk, or console).

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

Parameters

Parameter Description
lpFileName The name of the file or device.
dwDesiredAccess The generic access rights for the file (e.g., GENERIC_READ, GENERIC_WRITE).
dwShareMode The sharing mode (e.g., FILE_SHARE_READ, FILE_SHARE_WRITE).
lpSecurityAttributes Security attributes. Can be NULL.
dwCreationDisposition How to create or open the file (e.g., CREATE_ALWAYS, OPEN_EXISTING).
dwFlagsAndAttributes File attributes and flags (e.g., FILE_ATTRIBUTE_NORMAL).
hTemplateFile A handle to a template file. Can be NULL.
Return Value: A handle to the opened file or device. NULL if the function fails.

See Also

ReadFile

Reads data from a file or overlapping device.

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

Parameters

Parameter Description
hFile A handle to the file or device to read from.
lpBuffer A 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 An OVERLAPPED structure. Can be NULL for synchronous I/O.
Return Value: TRUE if the function succeeds, FALSE otherwise.

See Also

WriteFile

Writes data to a file or I/O device.

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

Parameters

Parameter Description
hFile A handle to the file or device to write to.
lpBuffer A 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 written.
lpOverlapped An OVERLAPPED structure. Can be NULL for synchronous I/O.
Return Value: TRUE if the function succeeds, FALSE otherwise.

See Also

CloseHandle

Closes an open object handle.

BOOL CloseHandle(
  HANDLE hObject
);

Parameters

Parameter Description
hObject A handle to an open object.
Return Value: TRUE if the function succeeds, FALSE otherwise.

See Also

GetFileAttributes

Retrieves file system attributes for a specified file or directory.

DWORD GetFileAttributes(
  LPCTSTR lpFileName
);

Parameters

Parameter Description
lpFileName The name of the file or directory.
Return Value: The attributes of the specified file or directory. INVALID_FILE_ATTRIBUTES if the function fails.

See Also

SetFilePointer

Reposition the file pointer of the specified file to a location based on the offset from the beginning, end, or current file pointer.

LONG SetFilePointer(
  HANDLE  hFile,
  LONG    lDistanceToMove,
  PLONG   lpDistanceToMoveHigh,
  DWORD   dwMoveMethod
);

Parameters

Parameter Description
hFile A handle to the file.
lDistanceToMove The number of bytes to move the file pointer.
lpDistanceToMoveHigh A pointer to the high-order 32 bits of the signed distance.
dwMoveMethod The starting point for the move (e.g., FILE_BEGIN, FILE_CURRENT, FILE_END).
Return Value: The final position of the file pointer. INVALID_SET_FILE_POINTER if the function fails.

See Also

DeleteFile

Deletes a specified file.

BOOL DeleteFile(
  LPCTSTR lpFileName
);

Parameters

Parameter Description
lpFileName The name of the file to be deleted.
Return Value: TRUE if the function succeeds, FALSE otherwise.

CopyFile

Copies an existing file to a new location.

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

Parameters

Parameter Description
lpExistingFileName The name of the existing file.
lpNewFileName The name of the new file.
bFailIfExists If TRUE and the new file already exists, the function fails.
Return Value: TRUE if the file was copied successfully, FALSE otherwise.

See Also

MoveFile

Moves an existing file or directory to a new location.

BOOL MoveFile(
  LPCTSTR lpExistingFileName,
  LPCTSTR lpNewFileName
);

Parameters

Parameter Description
lpExistingFileName The current name of the file or directory.
lpNewFileName The new name for the file or directory.
Return Value: TRUE if the function succeeds, FALSE otherwise.

See Also

FindFirstFile

Searches a directory for a file or subdirectory with a name that matches a specified string and retrieves information about that file or subdirectory.

HANDLE FindFirstFile(
  LPCTSTR             lpFileName,
  LPWIN32_FIND_DATA lpFindFileData
);

Parameters

Parameter Description
lpFileName The directory or path and file name string.
lpFindFileData A pointer to a WIN32_FIND_DATA structure that receives information about a found file or directory.
Return Value: A handle to the find first file. INVALID_HANDLE_VALUE if the function fails.

See Also

FindNextFile

Continues a file search.

BOOL FindNextFile(
  HANDLE             hFindFile,
  LPWIN32_FIND_DATA lpFindFileData
);

Parameters

Parameter Description
hFindFile A handle to the file search, returned by a previous call to the FindFirstFile function.
lpFindFileData A pointer to a WIN32_FIND_DATA structure that receives information about the next file.
Return Value: TRUE if information about a file was retrieved. FALSE if no more files are found or an error occurs.

See Also

FindClose

Closes the specified file search handle.

BOOL FindClose(
  HANDLE hFindFile
);

Parameters

Parameter Description
hFindFile A handle to the file search, returned by FindFirstFile.
Return Value: TRUE if the function succeeds, FALSE otherwise.

See Also