SetFilePointer

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This function moves the file pointer of an open file. A RAPI version of this function exists called CeSetFilePointer (RAPI).

Syntax

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

Parameters

• hFile
  [in] Handle to 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
  Low-order 32 bits of a signed value that specifies the number of bytes to move the file pointer. A positive value for this parameter ** moves the file pointer forward in the file, and a negative value moves the file pointer backward. You cannot use a negative value to move back past beyond the beginning of a file.

  If the lpDistanceToMoveHigh ** parameter is not set to NULL, lpDistanceToMoveHigh ** and ** this parameter ** form a single 64-bit signed value that specifies the distance to move.

• lpDistanceToMoveHigh
  Pointer to the high-order 32 bits of the signed distance to move.

  If you do not need the high-order 32 bits, this pointer must be set to NULL.

  When not set to NULL, this parameter also receives the high-order DWORD of the new value of the file pointer.

• dwMoveMethod
  [in] Starting point for the file pointer move. The following table shows possible values.

  Value	Description
  FILE_BEGIN	Indicates that the starting point is zero or the beginning of the file.
  FILE_CURRENT	Indicates that the starting point is the current value of the file pointer.
  FILE_END	Indicates that the starting point is the current end-of-file position.

Return Value

The new file pointer indicates success. A value of 0xFFFFFFFF indicates failure. To get extended error information, call GetLastError. However, because 0xFFFFFFFF is a valid value for the new file pointer, you must check GetLastError to determine whether an error occurred. If an error occurred, GetLastError returns a value other than NO_ERROR.

If the new file pointer would be a negative value, the function fails, the file pointer is not moved, and the code returned by GetLastError is ERROR_NEGATIVE_SEEK.

Remarks

You cannot use this function with a handle to a nonseeking device, such as a communications device.

You can use this function to query the current file pointer position. To do this, specify a move method of FILE_CURRENT and a distance of zero.

Be careful 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. For more information on these objects, see Processes and Threads.

It is not an error to set the file pointer to a position beyond the end of the file. The size of the file does not increase until you call the SetEndOfFile or the WriteFile function. A write operation increases the size of the file to the file pointer position plus the size of the buffer written, leaving the intervening bytes uninitialized.

If the return value is 0xFFFFFFFF, call GetLastError to determine whether the function has succeeded or failed. The following code example shows how to do this:

// Try to move the hFile file pointer some distance.
dwPtr = SetFilePointer (hFile, lDistance, NULL, FILE_BEGIN);
if (dwPtr == 0xFFFFFFFF) // Test for failure.
{
   // Obtain the error code.
   dwError = GetLastError();
   // Resolve the failure.
} // End of error handler.

Requirements

Header	winbase.h
Library	coredll.lib
Windows Embedded CE	Windows CE 1.0 and later
Windows Mobile	Windows Mobile Version 5.0 and later

See Also

Reference

File I/O Functions
GetFileSize
ReadFile
SetEndOfFile
WriteFile