ReplaceFileA 函式（winbase.h）

發行項
11/20/2024

以另一個檔案取代一個檔案，以及建立源文件備份複本的選項。取代檔案會假設已取代檔案的名稱及其身分識別。

語法

BOOL ReplaceFileA(
  [in]           LPCSTR lpReplacedFileName,
  [in]           LPCSTR lpReplacementFileName,
  [in, optional] LPCSTR lpBackupFileName,
  [in]           DWORD  dwReplaceFlags,
                 LPVOID lpExclude,
                 LPVOID lpReserved
);

參數

[in] lpReplacedFileName

要取代的檔名。

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

提示

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

此檔案會以 GENERIC_READ、DELETE和 SYNCHRONIZE 訪問許可權開啟。共用模式 FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE。

呼叫端必須具有要取代之檔案的寫入許可權。如需詳細資訊，請參閱檔案安全性和存取權限。

[in] lpReplacementFileName

將取代 lpReplacedFileName 檔案的檔名。

提示

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

函式會嘗試使用 SYNCHRONIZE、GENERIC_READ、GENERIC_WRITE、DELETE和 WRITE_DAC 訪問許可權來開啟此檔案，以便保留所有屬性和 ACL。如果失敗，函式會嘗試使用 SYNCHRONIZE、GENERIC_READ、DELETE和 WRITE_DAC 訪問許可權來開啟檔案。未指定共用模式。

[in, optional] lpBackupFileName

將做為 lpReplacedFileName 檔案備份副本的檔名。如果此參數 NULL，則不會建立任何備份檔。如需備份文件的實作詳細數據，請參閱一節。

提示

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

[in] dwReplaceFlags

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

價值	意義
REPLACEFILE_WRITE_THROUGH 0x00000001	不支援此值。
REPLACEFILE_IGNORE_MERGE_ERRORS 0x00000002	忽略將取代檔案中的資訊（例如屬性和 ACL）合併至取代檔案時所發生的錯誤。因此，如果您指定此旗標且沒有 WRITE_DAC 存取權，則函式會成功，但不會保留 ACL。
REPLACEFILE_IGNORE_ACL_ERRORS 0x00000004	忽略將 ACL 資訊從取代的檔案合併至取代檔案時所發生的錯誤。因此，如果您指定此旗標且沒有 WRITE_DAC 存取權，則函式會成功，但不會保留 ACL。若要編譯使用此值的應用程式，請將 _WIN32_WINNT 巨集定義為0x0600或更新版本。 Windows Server 2003 和 Windows XP：不支援此值。

lpExclude

保留供日後使用。

lpReserved

保留供日後使用。

傳回值

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

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

傳回碼/值	描述
ERROR_UNABLE_TO_MOVE_REPLACEMENT 1176 （0x498）	無法重新命名取代檔案。如果指定 lpBackupFileName，則已取代和取代的檔案會保留其源檔名稱。否則，已取代的檔案已不存在，且取代檔案會以其原始名稱存在。
ERROR_UNABLE_TO_MOVE_REPLACEMENT_2 1177 （0x499）	無法移動取代檔案。取代檔案仍以其原始名稱存在;不過，它已從它所取代的檔案繼承檔案數據流和屬性。要取代的檔案仍以不同的名稱存在。如果指定 lpBackupFileName，它將會是已取代檔案的名稱。
ERROR_UNABLE_TO_REMOVE_REPLACED 1175 （0x497）	無法刪除已取代的檔案。已取代和取代的檔案會保留其源檔名稱。

如果傳回任何其他錯誤，例如 ERROR_INVALID_PARAMETER，則已取代和取代的檔案會保留其源檔名稱。在此案例中，備份檔不存在，而且不保證取代檔案會繼承已取代檔案的所有屬性和數據流。

言論

提示從 Windows 10 版本 1607 開始，針對此函式的 unicode 版本（ReplaceFileW），您可以選擇移除 MAX_PATH 限制。如需詳細資訊，請參閱命名檔案、路徑和命名空間的一節。

ReplaceFile 函式會結合單一函式中的數個步驟。應用程式可以呼叫 ReplaceFile，而不是呼叫個別函式將數據儲存至新檔案、使用暫存名稱重新命名源檔、將新檔案重新命名為與源檔同名，以及刪除源檔。另一個優點是，ReplaceFile 不僅會複製新的檔案數據，也會保留源檔的下列屬性：

建立時間
簡短檔名
物件標識碼
DACL
安全性資源屬性
加密
壓縮
取代檔案中還沒有具名數據流

例如，如果取代檔案已加密，但已取代的檔案未加密，則產生的檔案不會加密。

Windows 7、Windows Server 2008 R2、Windows Server 2008、Windows Vista、Windows Server 2003 和 Windows XP ：在 Windows 8 和 Windows Server 2012 之前，不會保留源文件的安全性資源屬性（ATTRIBUTE_SECURITY_INFORMATION）。

附注

如果使用選擇性抹除來保護取代檔案，則取代的檔案將會受到取代檔案的企業標識符保護。

產生的檔案與取代檔案具有相同的檔案標識符。

備份檔、已取代的檔案和取代檔案必須全部位於相同的磁碟區上。

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

注意

winbase.h 標頭會將 ReplaceFile 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。如需詳細資訊，請參閱函式原型的慣例。

要求

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