SetFilePointer

The SetFilePointer function moves the file pointer of the specified file to a location relative to the beginning of the file, from the current file pointer, or from the end of the file.

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

Parameters

hFile: A handle to the file.

This handle must have been created by the CreateFile function with the appropriate access rights.

lDistanceToMove: A 32-bit integer that specifies the number of bytes to move the file pointer.

This parameter can be positive or negative.

lpDistanceToMoveHigh: A pointer to a 32-bit integer that receives the high-order 32 bits of the new file pointer.

This parameter can be NULL. For files larger than 2 GB, this parameter is required. For files smaller than 2 GB, this parameter should be NULL. If lpDistanceToMoveHigh is NULL, the function returns the low-order 32 bits of the new file pointer. If lpDistanceToMoveHigh is not NULL, the function returns the low-order 32 bits of the new file pointer and stores the high-order 32 bits in the variable pointed to by lpDistanceToMoveHigh.

dwMoveMethod: A value that specifies the method used to move the file pointer. This parameter can be one of the following values:
FILE_BEGIN: The file pointer is moved from the beginning of the file.
FILE_CURRENT: The file pointer is moved from the current position.
FILE_END: The file pointer is moved from the end of the file.

Return Value

If the function succeeds, the return value is the low-order 32 bits of the new file pointer. If lpDistanceToMoveHigh is not NULL, the function stores the high-order 32 bits of the new file pointer in the variable pointed to by lpDistanceToMoveHigh. If the function fails, the return value is INVALID_SET_FILE_POINTER and the value pointed to by lpDistanceToMoveHigh is not valid. To get extended error information, call GetLastError.

Remarks

To move a file pointer in a file larger than 2 GB, you must use a 64-bit file pointer. To do this, call the SetFilePointerEx function.

If the file was opened with the CREATE_NEW mode, the file handle is invalid.

Example

#include <windows.h>
#include <stdio.h>

int main() {
   HANDLE hFile;
   LONG lNewPosition, lNewPositionHigh;
   DWORD dwBytesRead;

   // Open a file for reading and writing
   hFile = CreateFile(
        "MyFile.txt", // file name
        GENERIC_READ | GENERIC_WRITE, // desired access
        0, // share mode
        NULL, // security attributes
        OPEN_ALWAYS, // creation disposition
        FILE_ATTRIBUTE_NORMAL, // file attributes
        NULL); // template file

   if (hFile == INVALID_HANDLE_VALUE) {
       printf("Could not open file. Error %lu\n", GetLastError());
       return 1;
   }

   // Move the file pointer to the end of the file
   lNewPosition = SetFilePointer(hFile, 0, NULL, FILE_END);

   if (lNewPosition == INVALID_SET_FILE_POINTER && GetLastError() != NO_ERROR) {
       printf("Failed to move file pointer. Error %lu\n", GetLastError());
       CloseHandle(hFile);
       return 1;
   }

   printf("File pointer moved to end of file. New position: %ld\n", lNewPosition);

   // Move the file pointer 100 bytes from the beginning
   lNewPosition = SetFilePointer(hFile, 100, NULL, FILE_BEGIN);

   if (lNewPosition == INVALID_SET_FILE_POINTER && GetLastError() != NO_ERROR) {
       printf("Failed to move file pointer. Error %lu\n", GetLastError());
       CloseHandle(hFile);
       return 1;
   }

   printf("File pointer moved 100 bytes from beginning. New position: %ld\n", lNewPosition);

   CloseHandle(hFile);
   return 0;
}

See Also

CreateFile
SetFilePointerEx
GetFileSize