Microsoft Docs

Feedback

SetFilePointerEx function

Applies to: Windows Server 2022, Windows 11, Windows 10, Windows Server 2019, Windows Server 2016, Windows 10 IoT Core, Windows 8.1, Windows 8, Windows Server 2012 R2, Windows Server 2012, Windows 8, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista, Windows Server 2003 R2, Windows Server 2003, Windows XP

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

Summary

Moves the file pointer of the specified file to a location that is relative to the beginning of the file, the end of the file, or the current file pointer.

Parameters

Parameter Description
hFile A handle to the file.
liDistanceToMove A LARGE_INTEGER structure that specifies the number of bytes to move the file pointer. This parameter can be positive, negative, or zero.
lpNewFilePointer A pointer to a LARGE_INTEGER structure that receives the new file pointer position. If this parameter is NULL, the new file pointer is not returned.
dwMoveMethod The starting position for the move. This parameter can be one of the following values:
  • FILE_BEGIN
  • FILE_CURRENT
  • FILE_END

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

To change the file pointer, you must open the file with the GENERIC_READ or GENERIC_WRITE access right.

  • The SetFilePointerEx function is a more robust version of the SetFilePointer function. SetFilePointerEx supports files larger than 2 gigabytes (GB).
  • If dwMoveMethod is FILE_BEGIN, the pointer is set to the beginning of the file plus the offset specified by liDistanceToMove.
  • If dwMoveMethod is FILE_CURRENT, the pointer is set to the current file pointer plus the offset specified by liDistanceToMove.
  • If dwMoveMethod is FILE_END, the pointer is set to the end of the file plus the offset specified by liDistanceToMove. The offset can be negative or positive.
  • If liDistanceToMove is zero and dwMoveMethod is FILE_CURRENT, the file pointer is not changed.
  • If the file is opened with the CREATE_DISPOSE flag, the file pointer is positioned at the end of the file.

See also