共用方式為


CopyFile 函式 (winbase.h)

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

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

新檔案的名稱。

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

提示

從 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_HIDDENFILE_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

另請參閱

CopyFileEx

CopyFileTransacted

CreateFile

檔案屬性常數

檔案管理功能

MoveFile

符號連結