setFilePointerEx 函式 (fileapi.h)

移動指定檔案的檔案指標。

語法

BOOL SetFilePointerEx(
  [in]            HANDLE         hFile,
  [in]            LARGE_INTEGER  liDistanceToMove,
  [out, optional] PLARGE_INTEGER lpNewFilePointer,
  [in]            DWORD          dwMoveMethod
);

參數

[in] hFile

檔案的句柄。 必須使用 GENERIC_READ 或 GENERIC_WRITE 訪問許可權來建立檔句柄。 如需詳細資訊，請參閱 檔案安全性和訪問許可權。

[in] liDistanceToMove

要移動檔案指標的位元元組數目。 正值會將檔案中的指標往前移動，負值會將檔案指標往後移動。

[out, optional] lpNewFilePointer

要接收新檔案指標之變數的指標。 如果此參數為 NULL，則不會傳回新的檔案指標。

[in] dwMoveMethod

檔案指標移動的起點。 此參數可以是下列其中一個值。

傳回值

如果函式成功，則傳回非零的值。

如果此函式失敗，則傳回值為零。 若要取得擴充的錯誤資訊，請呼叫 GetLastError。

備註

此函式所傳回的檔案指標不會用於重疊的讀取和寫入作業。 若要指定重迭作業的位移，請使用 OVERLAPPED 結構的 Offset 和 OffsetHigh 成員。

您無法將 SetFilePointerEx 函式與非看得見的裝置句柄搭配使用，例如管道或通訊裝置。 若要判斷 hFile 的檔案類型，請使用 GetFileType 函式。

在多線程應用程式中設定檔案指標時，請小心。 您必須同步存取共享資源。 例如，線程共用檔句柄、更新檔案指標並從檔案讀取的應用程式必須使用重要區段物件或 Mutex 物件來保護此序列。 如需這些對象的詳細資訊，請參閱 Critical Section Objects 和 Mutex Objects。

如果 hFile 句柄是以 設定FILE_FLAG_NO_BUFFERING 旗標開啟，則應用程式只能將檔案指標移至扇區對齊的位置。 扇區對齊位置是磁碟區扇區大小的整數倍數的位置。 應用程式可以藉由呼叫 GetDiskFreeSpace 函式來取得磁碟區的扇區大小。 如果應用程式使用距離到移動值呼叫 SetFilePointerEx ，導致位置未扇區對齊，且已以 FILE_FLAG_NO_BUFFERING開啟的句柄，則函式會失敗，而 GetLastError 會傳回 ERROR_INVALID_PARAMETER。 如需詳細資訊，請參閱 檔案緩衝。

請注意，將檔案指標設定為檔案結尾以外的位置不是錯誤。 在您呼叫 SetEndOfFile、WriteFile 或 WriteFileEx 函式之前，檔案的大小不會增加。 寫入作業會將檔案的大小增加至檔案指標位置加上寫入的緩衝區大小，這會導致插入的位元組初始化為零。

您可以使用 SetFilePointerEx 來判斷檔案的長度。 若要這樣做，請使用 dwMoveMethod的FILE_END，並搜尋至位置零。 傳回的檔案位移是檔案的長度。 不過，此做法可能會有非預期的副作用，例如無法儲存目前的檔案指標，讓程式可以返回該位置。 改用 GetFileSizeEx 函 式會比較簡單且更安全。

您也可以使用 SetFilePointerEx 查詢目前的檔案指標位置。 若要這樣做，請指定 FILE_CURRENT 的移動方法，以及零的距離。

在 Windows 8 和 Windows Server 2012 中，下列技術支援此函式。

規格需求

另請參閱

檔案管理功能

GetDiskFreeSpaceEx

GetFileSizeEx

GetFileType

SetEndOfFile

WriteFile

WriteFileEx