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

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

值 意義
FILE_BEGIN
0
 起點為零或檔案的開頭。 如果指定這個旗標， liDistanceToMove 參數會解譯為不帶正負號的值。
FILE_CURRENT
1
 起點是檔案指標的目前值。
FILE_END
2
 起點是目前的檔案結束位置。

傳回值

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

如果此函式失敗，則傳回值為零。 若要取得擴充的錯誤資訊，請呼叫 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 中，下列技術支援此函式。

技術 支援
伺服器消息塊 (SMB) 3.0 通訊協定 Yes
SMB 3.0 透明故障轉移 (TFO) Yes
具有向外延展檔案共用的SMB 3.0 (SO) Yes
叢集共用磁碟區文件系統 (CsvFS) Yes
彈性檔案系統 (ReFS) Yes

規格需求

   
最低支援的用戶端 Windows XP [傳統型應用程式 |UWP 應用程式]
最低支援的伺服器 Windows Server 2003 [傳統型應用程式 |UWP 應用程式]
目標平台 Windows
標頭 fileapi.h (包含 Windows.h)
程式庫 Kernel32.lib
DLL Kernel32.dll

另請參閱

檔案管理功能

GetDiskFreeSpaceEx

GetFileSizeEx

GetFileType

SetEndOfFile

WriteFile

WriteFileEx