SetFilePointer

Description

Moves the file pointer of the specified file.

This function stores the file pointer in two LONG values. To work with file pointers that are larger than a single LONG value, it is easier to use the SetFilePointerEx function.

Syntax

DWORD WINAPI SetFilePointer(
  _In_         HANDLE hFile,
  _In_         LONG lDistanceToMove,
  _Inout_opt_  PLONG lpDistanceToMoveHigh,
  _In_         DWORD dwMoveMethod
);

Parameters

hFile [in]

A handle to the file.

The file handle must be created with the GENERIC_READ or GENERIC_WRITE access right.

lDistanceToMove [in]

The low order 32-bits of a signed value that specifies the number of bytes to move the file pointer.

If lpDistanceToMoveHigh is not NULL, lpDistanceToMoveHigh and lDistanceToMove form a single 64-bit signed value that specifies the distance to move.

If lpDistanceToMoveHigh is NULL, lDistanceToMove is a 32-bit signed value. A positive value for lDistanceToMove moves the file pointer forward in the file, and a negative value moves the file pointer back.

lpDistanceToMoveHigh [in, out, optional]

A pointer to the high order 32-bits of the signed 64-bit distance to move.

If you do not need the high order 32-bits, this pointer must be set to NULL.

When not NULL, this parameter also receives the high order DWORD of the new value of the file pointer.

dwMoveMethod [in]

The starting point for the file pointer move.

This parameter can be one of the following values.

Value	Meaning
FILE_BEGIN 0	The starting point is zero or the beginning of the file.
FILE_CURRENT 1	The starting point is the current value of the file pointer.
FILE_END 2	The starting point is the current end-of-file position.

Return value

If the function succeeds and lpDistanceToMoveHigh is NULL, the return value is the low-order DWORD of the new file pointer.

Note If the function returns a value other than INVALID_SET_FILE_POINTER, the call to SetFilePointer has succeeded. You do not need to call GetLastError.

If function succeeds and lpDistanceToMoveHigh is not NULL, the return value is the low-order DWORD of the new file pointer and lpDistanceToMoveHigh contains the high order DWORD of the new file pointer.

If the function fails, the return value is INVALID_SET_FILE_POINTER. To get extended error information, call GetLastError.

If a new file pointer is a negative value, the function fails, the file pointer is not moved, and the code returned by GetLastError is ERROR_NEGATIVE_SEEK.

If lpDistanceToMoveHigh is NULL and the new file position does not fit in a 32-bit value, the function fails and returns INVALID_SET_FILE_POINTER.

Note Because INVALID_SET_FILE_POINTER is a valid value for the low-order DWORD of the new file pointer, you must check both the return value of the function and the error code returned by GetLastError to determine whether or not an error has occurred. If an error has occurred, the return value of SetFilePointer is INVALID_SET_FILE_POINTER and GetLastError returns a value other than NO_ERROR.