File I/O API

This section provides documentation for functions used to perform file input and output operations in the Windows operating system.

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

Creates or opens a file or device. This is the primary function for interacting with files.

Parameters

  • lpFileName: The name of the file or device to be created or opened.
  • dwDesiredAccess: The requested access to the file. Can be GENERIC_READ, GENERIC_WRITE, or a combination.
  • dwShareMode: How the file may be shared. Can be FILE_SHARE_READ, FILE_SHARE_WRITE, etc.
  • lpSecurityAttributes: Security descriptor for the file. Usually NULL.
  • dwCreationDisposition: How to create or open the file. e.g., CREATE_NEW, OPEN_ALWAYS, TRUNCATE_EXISTING.
  • dwFlagsAndAttributes: File attributes and flags. e.g., FILE_ATTRIBUTE_NORMAL, FILE_FLAG_OVERLAPPED.
  • hTemplateFile: A handle to a template file with duplicated attributes. Usually NULL.

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. To get extended error information, call GetLastError.

Remarks

  • This function is versatile and can be used to create new files, open existing files, or open devices like COM ports and pipes.
  • Properly managing the returned handle by closing it with CloseHandle is crucial to prevent resource leaks.
  • Error handling using GetLastError is essential to diagnose issues. Common error codes include ERROR_FILE_NOT_FOUND, ERROR_ACCESS_DENIED, and ERROR_SHARING_VIOLATION.

See Also

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

Reads data from a file or device into an application buffer.

Parameters

  • hFile: A handle to the file or device from which data is to be read.
  • lpBuffer: A pointer to the buffer that receives the data read from the file or device.
  • nNumberOfBytesToRead: The maximum number of bytes to be read.
  • lpNumberOfBytesRead: A pointer to a variable that receives the number of bytes read.
  • lpOverlapped: A pointer to an OVERLAPPED structure for asynchronous read operations.

Return Value

  • 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.

Remarks

  • The lpOverlapped parameter is used for asynchronous I/O. If it's NULL, the read operation is synchronous.
  • For synchronous reads, lpNumberOfBytesRead will contain the actual number of bytes read upon successful completion.
  • For asynchronous reads, lpNumberOfBytesRead may be NULL, and the result is determined by the status of the OVERLAPPED structure after the I/O operation completes.

See Also

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

Writes data to a file or device. It returns the number of bytes written, which may be less than the number requested.

Parameters

  • hFile: A handle to the file or device to which data is to be written.
  • lpBuffer: A pointer to a buffer containing the data to be written to the file or device.
  • nNumberOfBytesToWrite: The number of bytes to write to the file or device.
  • lpNumberOfBytesWritten: A pointer to a variable that receives the number of bytes actually written.
  • lpOverlapped: A pointer to an OVERLAPPED structure for asynchronous write operations.

Return Value

  • 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.

Remarks

  • Similar to ReadFile, the lpOverlapped parameter determines if the operation is synchronous or asynchronous.
  • For synchronous writes, lpNumberOfBytesWritten will contain the actual number of bytes written upon successful completion.
  • The function may write fewer bytes than requested. Always check the value pointed to by lpNumberOfBytesWritten.

See Also

CloseHandle BOOL CloseHandle(HANDLE hObject);

Closes an open object handle. It is essential for freeing system resources.

Parameters

  • hObject: A handle to an open object.

Return Value

  • 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.

Remarks

  • Every handle obtained from functions like CreateFile, CreateEvent, CreateProcess, etc., must be closed using CloseHandle when it is no longer needed.
  • Failure to close handles can lead to resource leaks, system instability, and performance degradation.