MoveFileExA 函式（winbase.h）

發行項
06/27/2024

使用各種行動選項行動現有的檔案或目錄，包括其子系。

MoveFileWithProgress 函式相當於 moveFileEx 函式，不同之處在於 moveFileWithProgress 可讓您提供接收進度通知的回呼函式。

若要以交易作業的形式執行此作業，請使用 MoveFileTransacted 函式。

語法

BOOL MoveFileExA(
  [in]           LPCSTR lpExistingFileName,
  [in, optional] LPCSTR lpNewFileName,
  [in]           DWORD  dwFlags
);

參數

[in] lpExistingFileName

本機電腦上的檔案或目錄目前名稱。

如果 dwFlags 指定 MOVEFILE_DELAY_UNTIL_REBOOT，則檔案無法存在於遠端共用上，因為延遲的作業會在網路可用之前執行。

根據預設，名稱限製為MAX_PATH個字元。若要將此限制延伸至 32,767 寬字元，請在路徑前面加上 “\\？\”。如需詳細資訊，請參閱命名檔案、路徑和命名空間。

提示

從 Windows 10 版本 1607 開始，您可以選擇移除MAX_PATH限制，而不需預先加上 “\\？\”。如需詳細資訊，請參閱命名檔案、路徑和命名空間的一節。

[in, optional] lpNewFileName

本機計算機上檔案或目錄的新名稱。

移動檔案時，目的地可以位於不同的文件系統或磁碟區上。如果目的地位於另一個磁碟驅動器上，您必須在 dwFlags中設定 MOVEFILE_COPY_ALLOWED 旗標。

移動目錄時，目的地必須位於相同的磁碟驅動器上。

如果 dwFlags 指定 MOVEFILE_DELAY_UNTIL_REBOOT，lpNewFileName 為 NULL，MoveFileEx 會在系統重新啟動時註冊要刪除的 lpExistingFileName 檔案。如果 lpExistingFileName 參照目錄，則只有在目錄是空的時，系統才會在重新啟動時移除目錄。

提示

從 Windows 10 版本 1607 開始，您可以選擇移除MAX_PATH限制，而不需預先加上 “\\？\”。如需詳細資訊，請參閱命名檔案、路徑和命名空間的一節。

[in] dwFlags

此參數可以是下列其中一或多個值。

價值	意義
MOVEFILE_COPY_ALLOWED 2 （0x2）	如果要將檔案移至不同的磁碟區，函式會使用 CopyFile 和 DeleteFile 函式來模擬移動。如果已成功將檔案複製到不同的磁碟區，且無法刪除源檔，函式會成功讓原始程序檔保持不變。這個值不能與 MOVEFILE_DELAY_UNTIL_REBOOT搭配使用。
MOVEFILE_CREATE_HARDLINK 16 （0x10）	保留供日後使用。
MOVEFILE_DELAY_UNTIL_REBOOT 4 （0x4）	在作業系統重新啟動之前，系統不會移動檔案。系統會在執行 AUTOCHK 之後立即移動檔案，但在建立任何分頁檔案之前。因此，此參數可讓函式從先前的啟動中刪除分頁檔案。只有在進程位於屬於系統管理員群組或 LocalSystem 帳戶的使用者內容中時，才能使用此值。這個值不能與 MOVEFILE_COPY_ALLOWED搭配使用。
MOVEFILE_FAIL_IF_NOT_TRACKABLE 32 （0x20）	如果來源檔案是連結來源，但移動之後無法追蹤檔案，則函式會失敗。如果目的地是使用 FAT 檔案系統格式化的磁碟區，就可能發生這種情況。
MOVEFILE_REPLACE_EXISTING 1 （0x1）	如果存在名為 lpNewFileName 的檔案，函式會將其內容取代為 lpExistingFileName 檔案的內容，前提是符合訪問控制清單（ACL）的安全性需求。如需詳細資訊，請參閱本主題的一節。如果 lpNewFileName 為現有目錄命名，則會報告錯誤。
MOVEFILE_WRITE_THROUGH 8 （0x8）	函式不會傳回，直到檔案實際移至磁碟上為止。設定此值可確保當做複製和刪除作業執行的移動會在函式傳回之前排清到磁碟。排清會在複製作業的結尾發生。如果已設定 MOVEFILE_DELAY_UNTIL_REBOOT，這個值就沒有作用。

傳回值

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

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

言論

如果 dwFlags 參數指定 MOVEFILE_DELAY_UNTIL_REBOOT，MoveFileEx 如果無法存取登錄，就會失敗。函式會在下列登錄值中儲存要重新啟動時重新命名的檔案位置：HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\PendingFileRenameOperations

此登入值的類型為 REG_MULTI_SZ。每個重新命名作業都會儲存下列其中一個 NULL 終止字串，視重新命名是否為刪除而定：

szSrcFile\0\0
szSrcFile\0szDstFile\0

字串 szSrcFile\0\0 表示在重新啟動時刪除 szSrcFile 檔案。字串 szSrcFile\0szDstFile\0 表示 szSrcFile 將在重新啟動時 szDstFile 重新命名。

注意雖然在技術上不允許 \0\0 在 REG_MULTI_SZ 節點中，但由於檔案會被視為重新命名為 Null 名稱，所以它可以。

系統會使用這些登錄專案，以與其發出的相同順序，在重新啟動時完成作業。例如，下列代碼段會建立登錄專案，以刪除 szSrcFile ，並在重新啟動時將 szSrcFile 重新命名為 szDstFi le：

MoveFileEx(szSrcFile, NULL, MOVEFILE_DELAY_UNTIL_REBOOT);
MoveFileEx(szSrcFile, szDstFile, MOVEFILE_DELAY_UNTIL_REBOOT);

由於呼叫應用程式停止執行之後，會執行以 MOVEFILE_DELAY_UNTIL_REBOOT 旗標指定的實際移動和刪除作業，所以傳回值無法反映移動或刪除檔案的成功或失敗。相反地，它會反映將適當專案放入登錄中的成功或失敗。

只有當目錄是空的時，系統才會刪除標記為刪除的目錄，並加上 MOVEFILE_DELAY_UNTIL_REBOOT 旗標。若要確保刪除目錄，請在嘗試刪除目錄之前，先移動或刪除目錄中的所有檔案。檔案可能會在開機時位於目錄中，但必須先刪除或移動檔案，系統才能刪除目錄。

移動和刪除作業會在開機時執行，順序與呼叫應用程式中指定的順序相同。若要在開機時刪除具有檔案的目錄，請先刪除檔案。

如果檔案在磁碟區之間移動，MoveFileEx 不會移動檔案的安全性描述元。檔案會指派目的地目錄中的預設安全性描述元。

MoveFileEx 函式會與連結追蹤服務協調其作業，因此可以在行動連結來源時加以追蹤。

若要刪除或重新命名檔案，您必須擁有檔案的刪除許可權，或刪除父目錄中的子許可權。如果您設定具有刪除和刪除子系和新檔案 ACL 以外的所有存取權的目錄，則您應該能夠建立檔案，而無法刪除它。不過，您可以接著建立檔案，並取得您在建立檔案時傳回之句柄上要求的所有存取權。如果您在建立檔案時要求刪除許可權，您可以使用該句柄刪除或重新命名檔案，但不能使用任何其他句柄來重新命名檔案。如需詳細資訊，請參閱檔案安全性和存取權限。

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

科技	支援
伺服器消息塊（SMB） 3.0 通訊協定	是的
SMB 3.0 透明故障轉移（TFO）	是的
具有向外延展檔案共用的SMB 3.0（SO）	是的
叢集共用磁碟區檔案系統（CsvFS）	是的
復原檔案系統（ReFS）	是的

例子

如需範例，請參閱建立和使用暫存盤。

要求

要求	價值
最低支援的用戶端	Windows XP [傳統型應用程式 \|UWP 應用程式]
支援的最低伺服器	Windows Server 2003 [傳統型應用程式 \|UWP 應用程式]
目標平臺	窗戶
標頭	winbase.h （包括 Windows.h）
連結庫	Kernel32.lib
DLL	Kernel32.dll