The SetFilePointer function (in conjunction with the SetFilePointerEx function) manipulates the pointer of a file. The file pointer is the position in a file at which the next read or write operation begins.
Syntax
DWORD SetFilePointer( HANDLE hFile, LONG lDistanceToMove, PLONG lpDistanceToMoveHigh, DWORD dwMoveMethod );
Parameters
| Parameter | Description |
|---|---|
hFile |
A handle to the file. The handle must have been created with the GENERIC_READ or GENERIC_WRITE access right. |
lDistanceToMove |
The number of bytes to move the file pointer. This parameter can be positive or negative. |
lpDistanceToMoveHigh |
A pointer to a LONG value that receives the high-order DWORD of the file pointer. This parameter can be NULL. If this parameter is not NULL, then lDistanceToMove and lpDistanceToMoveHigh form a 64-bit value that is used to set the file pointer. |
dwMoveMethod |
The starting point for the move. This parameter can be one of the following values:
|
Return Value
If the function succeeds, the return value is the low-order DWORD of the new file pointer. If the function fails, the return value is INVALID_SET_FILE_POINTER and to get extended error information, call GetLastError.
If lpDistanceToMoveHigh is not NULL, the function returns the low-order DWORD of the new file pointer and sets the high-order DWORD in the location pointed to by lpDistanceToMoveHigh. In this case, if the function fails, the return value is INVALID_SET_FILE_POINTER and the contents of the location pointed to by lpDistanceToMoveHigh are undefined.
Remarks
To set a file pointer for a file that is larger than 4 gigabytes (GB), use the SetFilePointerEx function.
If the hFile parameter specifies a file that is being accessed across a network, SetFilePointer may fail if the dwMoveMethod parameter is FILE_CURRENT and the lDistanceToMove parameter is not zero. This is because other network operations might occur between the time the file pointer is retrieved and the time it is reset.
When you open a file for appending, the file pointer is moved to the end of the file. You can then write data to the end of the file.
For more information about moving file pointers, see File Pointers.