moveFileExA 函式 (winbase.h)

發行項
03/13/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 無法存取登錄，則 MoveFileEx 會失敗。函式會將要在重新啟動時重新命名的檔案位置儲存在下列登錄值中： HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\PendingFileRenameOperations

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

szDstFile\0\0
szSrcFile\0szDstFile\0

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

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

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

MoveFileEx(szDstFile, 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 通訊協定	Yes
SMB 3.0 透明故障轉移 (TFO)	Yes
具有向外延展檔案共用的SMB 3.0 (SO)	Yes
叢集共用磁碟區文件系統 (CsvFS)	Yes
彈性檔案系統 (ReFS)	是

範例

如需範例，請參閱建立和使用臨時檔。

規格需求

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