Moves the file pointer of an open file.

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

Parameters

hFile

Handle to the file whose file pointer moves. The file handle must be created with GENERIC_READ or GENERIC_WRITE access to the file.

lDistanceToMove

Low-order 32 bits of a signed value that specifies the number of bytes to move the file pointer. A positive value for lpDistanceToMove moves the file pointer forward in the file; a negative value moves the file pointer backward. Note that you cannot use a negative value to move back past beyond the beginning of a file.

lpDistanceToMoveHigh

Set to NULL.

dwMoveMethod

Starting point for the file pointer move. Valid values include:

FILE_BEGIN	Zero, or the beginning of the file.
FILE_CURRENT	The file pointer's current value.
FILE_END	The current EOF position.

Remarks

You can use SetFilePointer to query the current file pointer position. To do this, specify a move method of FILE_CURRENT and a distance of zero.

It is not an error to set the file pointer to a position beyond the file's end. The file size does not increase until you call WriteFile. A write operation increases the file size to the file pointer position plus the size of the buffer written, leaving the intervening bytes uninitialized.

Note:   SetFilePointer cannot be used to move the file pointer beyond the maximum file size, which is 0xFFFFFFFF. If SetFilePointer is called to move the pointer beyond 0xFFFFFFFF, the pointer is set at 0xFFFFFFFF. In this case, the return value is 0xFFFFFFFF, but GetLastError returns NO_ERROR.

You can use SetFilePointer to determine the file length. To do this, use FILE_END for dwMoveMethod and seek to location zero. The returned file offset is the file's length. However, this practice can have unintended side effects, such as failing to save the current file pointer the application uses to return to that location.

Return Values

New file pointer

Success.

If the value is 0xFFFFFFFF (a valid file pointer but also the Failure code), you must check GetLastError to determine whether an error occurred. If an error occurred, a value other than NO_ERROR returns.

0xFFFFFFFF

Failure. For extended error information, see GetLastError.

If the new file pointer would be a negative value, the function fails, the file pointer does not move, and GetLastError returns ERROR_NEGATIVE_SEEK.

Requirements

Note

This function operates in the real-time portion of your application.

See Also

ReadFile, WriteFile, iwin32 API, iwin32 Overview