File Positioning

This section details the functions and concepts related to managing the current position within a file for read and write operations in the Windows API.

Core Concepts

When working with files, it's crucial to understand how the operating system tracks the current read/write position. This position determines where the next read or write operation will begin.

File Pointers

Each open file handle has an associated file pointer. This pointer is an offset from the beginning of the file. When you read from or write to a file, the file pointer is advanced by the number of bytes read or written.

Seek Operations

You can explicitly change the file pointer's position using seek operations. This allows you to read from or write to specific locations within a file without sequentially processing the intervening data.

Key Functions

`SetFilePointerEx`

The SetFilePointerEx function sets the file pointer for the specified file. This is the recommended function for setting the file pointer as it supports 64-bit offsets.


BOOL SetFilePointerEx(
  HANDLE hFile,
  LARGE_INTEGER liDistanceToMove,
  PLARGE_INTEGER lpNewFilePointer,
  DWORD dwMoveMethod
);

Parameters:

hFile: A handle to the file.
liDistanceToMove: The number of bytes to move the file pointer.
lpNewFilePointer: An optional pointer to a LARGE_INTEGER that receives the new file pointer.
dwMoveMethod: The starting point for the move. This can be one of the following:
- FILE_BEGIN: The file pointer is set to liDistanceToMove bytes from the beginning of the file.
- FILE_CURRENT: The file pointer is moved liDistanceToMove bytes from its current position.
- FILE_END: The file pointer is set to liDistanceToMove bytes from the end of the file.

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.

Note

For compatibility with older systems or simpler scenarios, SetFilePointer is also available, but SetFilePointerEx is preferred for its 64-bit support.

`GetFilePointerEx`

The GetFilePointerEx function retrieves the current position of the file pointer for the specified file.


BOOL GetFilePointerEx(
  HANDLE hFile,
  PLARGE_INTEGER lpNewFilePointer
);

Parameters:

hFile: A handle to the file.
lpNewFilePointer: A pointer to a LARGE_INTEGER that receives the current file pointer.

Return Value:

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

Usage Examples

Moving to the Beginning of a File


HANDLE hFile = CreateFile(...); // Assume hFile is valid
LARGE_INTEGER zero = {0};
SetFilePointerEx(hFile, zero, NULL, FILE_BEGIN);

Moving to the End of a File


HANDLE hFile = CreateFile(...); // Assume hFile is valid
LARGE_INTEGER offset = {0}; // Offset from end doesn't matter if FILE_END
SetFilePointerEx(hFile, offset, NULL, FILE_END);

Seeking Relative to the Current Position


HANDLE hFile = CreateFile(...); // Assume hFile is valid
LARGE_INTEGER moveBy = {100}; // Move 100 bytes forward
SetFilePointerEx(hFile, moveBy, NULL, FILE_CURRENT);