File I/O API

This section provides documentation for the Win32 API functions used for file input and output operations. These functions allow applications to create, read, write, and manage files on the Windows operating system.

CreateFile

Creates or opens a file or I/O device. It returns a handle that can be used to access the file.

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

Parameters

  • lpFileName: The name of the file or device to be created or opened.
  • dwDesiredAccess: The access to the file or device. This can be a combination of generic access rights, such as GENERIC_READ, GENERIC_WRITE, or GENERIC_ALL.
  • dwShareMode: A bitmode that specifies how an application can share an opened handle to a file.
  • lpSecurityAttributes: A pointer to a SECURITY_ATTRIBUTES structure that contains security descriptor for the file.
  • dwCreationDisposition: Determines whether the file is created or opened. Possible values include CREATE_NEW, CREATE_ALWAYS, OPEN_EXISTING, OPEN_ALWAYS, TRUNCATE_EXISTING.
  • dwFlagsAndAttributes: The file attributes and flags. Common flags include FILE_ATTRIBUTE_NORMAL, FILE_FLAG_DELETE_ON_CLOSE.
  • hTemplateFile: A handle to a template file with the extended attributes and security that you want to apply to the file being created.

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

This is the primary function for file operations. It's crucial to understand each parameter to correctly manage file access and creation.

Tip: Always check for INVALID_HANDLE_VALUE and use GetLastError() to diagnose errors.

See Also

ReadFile

Reads data from a file or from the communication between the calling process and a character device.

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

Parameters

  • hFile: A handle to the file to be read.
  • 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 DWORD variable that receives the number of bytes actually read.
  • lpOverlapped: A pointer to an OVERLAPPED structure. Used for asynchronous operations.

Return Value

If the function succeeds, and the value of lpOverlapped is NULL, the return value is non-zero. If the function succeeds, and the value of lpOverlapped is not NULL, the return value is non-zero if the read operation is completed, or zero if the operation is pending.

If the function fails, the return value is zero.

Remarks

When reading from a file, lpNumberOfBytesRead will indicate how many bytes were successfully transferred into the buffer. If lpOverlapped is used, the function may return before the read is complete.

See Also

WriteFile

Writes data to a file or to the communication between the calling process and a character device.

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

Parameters

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

Return Value

If the function succeeds, and the value of lpOverlapped is NULL, the return value is non-zero. If the function succeeds, and the value of lpOverlapped is not NULL, the return value is non-zero if the write operation is completed, or zero if the operation is pending.

If the function fails, the return value is zero.

Remarks

Ensure that the handle hFile was opened with write access.

See Also

CloseHandle

Closes an open object handle. You must close file handles when you are finished with them.

BOOL CloseHandle(
  HANDLE hObject
);

Parameters

  • hObject: A handle to an open object.

Return Value

If the function succeeds, the return value is non-zero. If the function fails, the return value is zero.

Remarks

Closing a handle releases the system resources associated with it. Failure to close handles can lead to resource leaks.

See Also