Export (0) Print
Expand All
Expand Minimize

SetFilePointerEx function

Moves the file pointer of the specified file.

Syntax


BOOL WINAPI SetFilePointerEx(
  _In_       HANDLE hFile,
  _In_       LARGE_INTEGER liDistanceToMove,
  _Out_opt_  PLARGE_INTEGER lpNewFilePointer,
  _In_       DWORD dwMoveMethod
);

Parameters

hFile [in]

A handle to the file. The file handle must have been created with the GENERIC_READ or GENERIC_WRITE access right. For more information, see File Security and Access Rights.

liDistanceToMove [in]

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

lpNewFilePointer [out, optional]

A pointer to a variable to receive the new file pointer. If this parameter is NULL, the new file pointer is not returned.

dwMoveMethod [in]

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

ValueMeaning
FILE_BEGIN
0

The starting point is zero or the beginning of the file. If this flag is specified, then the liDistanceToMove parameter is interpreted as an unsigned value.

FILE_CURRENT
1

The start point is the current value of the file pointer.

FILE_END
2

The starting point is the current end-of-file position.

 

Return value

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The file pointer returned by this function is not used for overlapped read and write operations. To specify the offset for overlapped operations, use the Offset and OffsetHigh members of the OVERLAPPED structure.

You cannot use the SetFilePointerEx function with a handle to a nonseeking device such as a pipe or a communications device. To determine the file type for hFile, use the GetFileType function.

Use caution when setting the file pointer in a multithreaded application. You must synchronize access to shared resources. 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 a mutex object. For more information about these objects, see Critical Section Objects and Mutex Objects.

If the hFile 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. An application can obtain a volume's sector size by calling the GetDiskFreeSpace function. If an application calls SetFilePointerEx 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. For additional information, see File Buffering.

Note that 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, WriteFile, or WriteFileEx 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.

You can use SetFilePointerEx to determine the length of a file. To do this, use FILE_END for dwMoveMethod and seek to location zero. The file offset returned is the length of the file. However, this practice can have unintended side effects, such as failure to save the current file pointer so that the program can return to that location. It is simpler and safer to use the GetFileSizeEx function instead.

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

Windows Phone 8: This API is supported.

Windows Phone 8.1: This API is supported.

In Windows 8 and Windows Server 2012, this function is supported by the following technologies.

TechnologySupported

Server Message Block (SMB) 3.0 protocol

Yes

SMB 3.0 Transparent Failover (TFO)

Yes

SMB 3.0 with Scale-out File Shares (SO)

Yes

Cluster Shared Volume File System (CsvFS)

Yes

Resilient File System (ReFS)

Yes

 

Requirements

Minimum supported client

Windows XP [desktop apps | Windows Store apps]

Minimum supported server

Windows Server 2003 [desktop apps | Windows Store apps]

Header

FileAPI.h (include Windows.h);
WinBase.h on Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003, and Windows XP (include Windows.h)

Library

Kernel32.lib

DLL

Kernel32.dll

See also

File Management Functions
GetDiskFreeSpaceEx
GetFileSizeEx
GetFileType
SetEndOfFile
WriteFile
WriteFileEx

 

 

Community Additions

ADD
Show:
© 2014 Microsoft