SetFilePointer

SetFilePointer moves the file pointer of an open file.

Syntax

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

Parameters

hFile

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

The number of bytes to move the file pointer. A positive value moves the pointer forward in the file and a negative value moves it backward.

lpDistanceToMoveHigh

A pointer to the high-order word of the 64-bit distance to move. If the value of this parameter is NULL, SetFilePointer can operate only on files whose maximum size is 232 - 2. If this parameter is specified, the maximum file size is 264 - 2. This parameter also receives the high-order word of the new value of the file pointer.

MoveMethod

The starting point for the file pointer move. This parameter can be one of the following values:

FILE_BEGIN — The starting point is zero or the beginning of the file. If FILE_BEGIN is specified, DistanceToMove is interpreted as an unsigned location for the new file pointer.
FILE_CURRENT — The current value of the file pointer is the starting point.
FILE_END — The current end-of-file position is the starting point.

Return Values

lpDistanceToMoveHigh is NULL

The low-order DWORD of the new file pointer if the function succeeds, 0xFFFFFFFF if the function fails

NOTE: If the function returns a value other than 0xFFFFFFFF, the call to SetFilePointer has succeeded. You do not need to call GetLastError.

lpDistanceToMoveHigh is not NULL

The low-order DWORD of the new file pointer if the function succeeds. The high-order DWORD of the new file pointer is contained in lpDistanceToMoveHigh.
0xFFFFFFFF if teh function fails

To get extended error information, call GetLastError.

NOTE: Because 0xFFFFFF is a valid value for the low-order DWORD of the new file pointer, you must check both the return value of the function and the error code returned by GetLastError to determine whether or not an error has occurred. If an error has occurred, the return value of SetFilePointer is 0xFFFFFFFF and GetLastError returns a value other than NO_ERROR.

Remarks

Do not use SetFilePointer with a handle to a non-seeking device, such as a pipe or a communications device.

Use caution when setting the file pointer in a multithreaded application. For example, an application whose threads share a file handle, update the file pointer, and read from the file must protect this sequence by using a critical section object or mutex object.

If the hFile file handle was opened with the FILE_FLAG_NO_BUFFERING flag set, an application can move the file pointer only to sector-aligned positions. A sector-aligned position is a position that is a whole number multiple of the volume's sector size. If an application calls SetFilePointer with distance-to-move values that result in a position that is not sector-aligned and a handle that was opened with FILE_FLAG_NO_BUFFERING, the function fails, and GetLastError returns ERROR_INVALID_PARAMETER.

If the return value is 0xFFFFFFFF and lpDistanceToMoveHigh is non-NULL, an application must call GetLastError to determine whether the function has succeeded or failed.

Requirements

Library

Rtx_Rtss.lib

Example

The following sample code illustrates this point.

//
// Case One: calling the function with
// lpDistanceToMoveHigh == NULL

// try to move hFile's file pointer some distance
dwPointer = SetFilePointer (hFile, lDistance,
  NULL, FILE_BEGIN) ;
// if we failed ...
if (dwPointer == 0xFFFFFFFF) {

  // obtain the error code
  dwError = GetLastError() ;

// deal with that failure

  } // end of error handler

//// Case Two: calling the function with
// lpDistanceToMoveHigh != NULL

// try to move hFile's file pointer some huge distance
dwPointerLow = SetFilePointer (hFile, lDistanceLow, & lDistanceHigh, FILE_BEGIN) ;

// if we failed ...
if (dwPointerLow == 0xFFFFFFFF
  &&
  (dwError = GetLastError()) != NO_ERROR ){

  // deal with that failure
  .
  .

 } // end of error handler