WindowsApi:SetFilePointer

lastmod 2018-08-17created 2016-03-303 edits

Moves the file pointer of the specified file (lets you move or check the position (Position) from which the file can be read).

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
);

Use the SetFilePointerEx()

• You should use SetFilePointerEx rather than SetFilePointer

When a file is opened, the file pointer is set to 0. After that, when you do I/O on the file through functions such as ReadFile() or WriteFile(), the file pointer increases automatically. Of course, Windows also provides an interface that lets the user adjust the offset directly, and the SetFilePointer function is exactly that interface for moving the file pointer. The file pointer is managed separately for each handle. That is, even for the same file, if you open it twice and hold two handles, the file pointer attached to each handle moves independently. This SetFilePointer is an overly complicated function. To support 32-bit and 64-bit at the same time, SetFilePointer was designed so that offset information totaling 64 bits, 4 bytes each, can be passed through the second and third arguments.

The first common mistake is always passing NULL for lpDistanceToMoveHigh even when the offset can exceed 32 bits. This fails to properly support files larger than 4 GB, and is commonly seen in code written long ago.

Second. The return value of SetFilePointer is the changed offset value, and if the function fails it returns INVALID_SET_FILE_POINTER. INVALID_SET_FILE_POINTER is defined as -1, and since this value is received as a DWORD, it becomes 0xFFFFFFFF. But what if the position I wanted to move to was 0xFFFFFFFF (4 GB)? The user asked to move the offset to position 0xFFFFFFFF, and the function correctly performed what the user wanted and returned 0xFFFFFFFF. Now how do you tell whether this value is an error or a valid offset? To check, the user must call GetLastError(). If the function succeeded and the offset is valid, Last Error will be set to ERROR_SUCCESS. Last time I said that the Windows Last Error value is set only when a function fails, but some special functions such as SetFilePointer set the value to 0 even on success. Of course, the reason is that, as above, the return value alone cannot convey all the information.

Therefore, wherever SetFilePointer is used, the return value must be checked as shown in the following table. (The MSDN example also uses it as below.)

See also

• Windows Api
• CreateFile()
• ReadFile()
• WriteFile()

Favorite site

• [http://msdn.microsoft.com/en-us/library/windows/desktop/aa365541(v=vs.85.aspx MSDN Description of SetFilePointer()]
• How to use SetFilePointer() (in Korean)