Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
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 DWORDof 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 GetLastErrorto determine whether an error occurred. If an error occurred, GetLastErrorreturns 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 GetLastErroris 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 SetEndOfFileor the WriteFilefunction. 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 GetLastErrorto determine whether the function has succeeded or failed. The following code example shows how to do this:

Copy Code 
// 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