| DWORD SetFilePointer(hFile, lDistanceToMove, plDistanceToMoveHigh, dwMoveMethod) | |||||
| HANDLE hFile; | /* handle to file | */ | |||
| LONG lDistanceToMove; | /* # of bytes to move file pointer | */ | |||
| PLONG plDistanceToMoveHigh; | /* high 32 bits of distance to move | */ | |||
| DWORD dwMoveMethod; | /* how to move | */ | |||
The SetFilePointer function moves an open file's file pointer.
hFile
Identifies the file whose file pointer is to be moved. The file handle must have been created with GENERIC_READ or GENERIC_WRITE access to the file.
lDistanceToMove
Specifies the number of bytes to move the file pointer. A positive value moves the pointer forward in the file and a negative value moves backwards in the file.
plDistanceToMoveHigh
An optional parameter that, if specified, supplies the high-order 32 bits of the 64-bit distance to move. If the value of this parameter is NULL, this function can only operate on files whose maximum size is (2**32)-2. If this parameter is specified, then the maximum file size is (2**64)-2. This value also returns the high-order 32 bits of the new value of the file pointer. If this value and the return value is -1 (0xFFFFFFFF), then an error occurred.
dwMoveMethod
Specifies the starting point for the file pointer move.
| Value | Meaning |
| FILE_BEGIN | ||
| The starting point is zero or the beginning of the file. If FILE_BEGIN is specified, then DistanceToMove is interpreted as an unsigned location for the new file pointer. | ||
| FILE_CURRENT | ||
| The current value of the file pointer is used as the starting point. | ||
| FILE_END | ||
| The current end-of-file position is used as the starting point. | ||
If the function is successful, the return value is the low-order 32 bits of the new file pointer, and lpDistanceToMoveHigh is the high-order 32 bits of the new file pointer.
If the function fails, the return value is -1 (0xFFFFFFFF) and lpDistanceToMoveHigh is NULL. Use the GetLastError function to obtain extended error information.
Using this function with a handle to a non-seeking device (such as a pipe or a communications device) has no meaning. Use the GetFileType function to determine the file type for hFile.
A multi-threaded application must use extreme caution when setting the file pointer. For example, an application whose threads share a file handle, update the file pointer, and read from the file must protect the this sequence by using a critical section object or mutex object.