Export (0) Print
Expand All
Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

SetFilePointer

Windows Mobile 6.5
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).


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

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.

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.

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.

Headerwinbase.h
Librarycoredll.lib
Windows Embedded CEWindows CE 1.0 and later
Windows MobileWindows Mobile Version 5.0 and later

Community Additions

Show:
© 2014 Microsoft