Documentation > Windows > API Reference > FileAPI > SetFilePointerEx

Windows API Reference

SetFilePointerEx Function

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

The SetFilePointerEx function updates the file pointer for the specified file. The file pointer determines where the next read or write operation begins.

Syntax

BOOL SetFilePointerEx(
  [in]            HANDLE  hFile,
  [in]            LARGE_INTEGER liDistanceToMove,
  [out, optional] PLARGE_INTEGER lpNewFilePointer,
  [in]            DWORD   dwMoveMethod
);

Parameters

Parameter Description
hFile A handle to the file. This handle must have been created by the CreateFile function with the FILE_FLAG_RANDOM_ACCESS flag.
liDistanceToMove A LARGE_INTEGER structure that specifies the number of bytes to move the file pointer. This value can be positive or negative.
lpNewFilePointer A pointer to a LARGE_INTEGER structure that receives the new file pointer. This parameter can be NULL.
dwMoveMethod The starting point for the move. This parameter can be one of the following values:
  • FILE_BEGIN: The file pointer is moved from the beginning of the file.
  • FILE_CURRENT: The file pointer is moved from its current position.
  • FILE_END: The file pointer is moved 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.

Remarks

The SetFilePointerEx function allows for moving the file pointer by a value up to 64 bits, which is necessary for working with large files.

If lpNewFilePointer is not NULL, the new value of the file pointer is copied into the QuadPart member of the LARGE_INTEGER structure pointed to by lpNewFilePointer.

To seek to a position in a file that is larger than 4 gigabytes, you must use the SetFilePointerEx function. The older SetFilePointer function can only seek to positions up to 4 gigabytes.

Requirements

Requirement Value
Minimum supported client Windows Vista [desktop apps only]
Minimum supported server Windows Server 2008 [desktop apps only]
Header fileapi.h
Library kernel32.lib
DLL Kernel32.dll

See Also

Example

// C++
#include <windows.h>
#include <iostream>

int main() {
    HANDLE hFile = CreateFile(
        L"C:\\example.txt",
        GENERIC_READ | GENERIC_WRITE,
        0,
        NULL,
        CREATE_ALWAYS,
        FILE_ATTRIBUTE_NORMAL,
        NULL
    );

    if (hFile == INVALID_HANDLE_VALUE) {
        std::cerr << "Error creating file: " << GetLastError() << std::endl;
        return 1;
    }

    // Write some data
    const char* data = "Hello, Windows API!";
    DWORD bytesWritten;
    if (!WriteFile(hFile, data, strlen(data), &bytesWritten, NULL)) {
        std::cerr << "Error writing to file: " << GetLastError() << std::endl;
        CloseHandle(hFile);
        return 1;
    }

    // Set the file pointer to the beginning
    LARGE_INTEGER offset;
    offset.QuadPart = 0;
    if (!SetFilePointerEx(hFile, offset, NULL, FILE_BEGIN)) {
        std::cerr << "Error setting file pointer: " << GetLastError() << std::endl;
        CloseHandle(hFile);
        return 1;
    }

    std::cout << "File pointer set to the beginning." << std::endl;

    // Seek to the 7th byte from the beginning
    LARGE_INTEGER newPos;
    offset.QuadPart = 7;
    if (SetFilePointerEx(hFile, offset, &newPos, FILE_BEGIN)) {
        std::cout << "New file pointer position: " << newPos.QuadPart << std::endl;
    } else {
        std::cerr << "Error setting file pointer: " << GetLastError() << std::endl;
    }

    // Seek to 5 bytes before the end
    offset.QuadPart = -5;
    if (SetFilePointerEx(hFile, offset, &newPos, FILE_END)) {
        std::cout << "New file pointer position (from end): " << newPos.QuadPart << std::endl;
    } else {
        std::cerr << "Error setting file pointer: " << GetLastError() << std::endl;
    }


    CloseHandle(hFile);
    return 0;
}