CopyFile 函式 (winbase.h)

發行項
03/03/2024

複製現有的檔案到新的檔案。

CopyFileEx 函式提供兩個額外的功能。 CopyFileEx 可以在每次複製作業完成時呼叫指定的回呼函式，而 CopyFileEx 可以在複製作業期間取消。

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

語法

BOOL CopyFile(
  [in] LPCTSTR lpExistingFileName,
  [in] LPCTSTR lpNewFileName,
  [in] BOOL    bFailIfExists
);

參數

[in] lpExistingFileName

現有檔案的名稱。

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

提示

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

如果 lpExistingFileName 不存在， CopyFile 會失敗，而且 GetLastError 會傳回 ERROR_FILE_NOT_FOUND。

[in] lpNewFileName

新檔案的名稱。

提示

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

[in] bFailIfExists

如果此參數為 TRUE ，且 lpNewFileName 指定的新檔案已經存在，則函式會失敗。如果此參數為 FALSE 且新檔案已經存在，則函式會覆寫現有的檔案並成功。

傳回值

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

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

備註

將現有檔案的安全性資源屬性 (ATTRIBUTE_SECURITY_INFORMATION) 複製到新檔案。

Windows 7、Windows Server 2008 R2、Windows Server 2008、Windows Vista、Windows Server 2003 和 Windows XP： 在 Windows 8 和 Windows Server 2012 之前，現有檔案的安全性資源屬性不會複製到新檔案。

現有檔案的檔案屬性會複製到新檔案。例如，如果現有的檔案具有 FILE_ATTRIBUTE_READONLY 檔案屬性，透過呼叫 CopyFile 所建立的複本也會有 FILE_ATTRIBUTE_READONLY 檔案屬性。如需詳細資訊，請參閱擷取和變更檔案屬性。

如果目的地檔案已經存在，且已設定FILE_ATTRIBUTE_HIDDEN或FILE_ATTRIBUTE_READONLY屬性，此函式會失敗並ERROR_ACCESS_DENIED。

當 CopyFile 用來複製加密的檔案時，它會嘗試使用來源檔案加密中使用的金鑰來加密目的地檔案。如果無法這麼做，此函式會嘗試使用預設密鑰來加密目的地檔案。如果這兩種方法都無法完成， CopyFile 會失敗，並 出現ERROR_ENCRYPTION_FAILED 錯誤碼。

符號連結行為：如果來源檔案是符號連結，則複製的實際檔案是符號鏈接的目標。

如果目的地檔案已經存在，而且是符號連結，則來源檔案會覆寫符號鏈接的目標。

在 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