ReplaceFileA 函式 (winbase.h)

發行項
06/02/2023

使用建立源檔案備份複本的選項，將一個檔案取代為另一個檔案。取代檔案假設取代的檔案名及其身分識別。

語法

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 應用程式]
目標平台	Windows
標頭	winbase.h (包含 Windows.h)
程式庫	Kernel32.lib
DLL	Kernel32.dll