Функция CopyFileA (winbase.h)

Статья
06/02/2023

Копирует существующий файл в новый файл.

Функция CopyFileEx предоставляет две дополнительные возможности. CopyFileEx может вызывать указанную функцию обратного вызова каждый раз, когда выполняется часть операции копирования, и CopyFileEx можно отменить во время операции копирования.

Чтобы выполнить эту операцию как транзакцию, используйте функцию CopyFileTransacted .

Синтаксис

BOOL CopyFileA(
  [in] LPCSTR lpExistingFileName,
  [in] LPCSTR lpNewFileName,
  [in] BOOL   bFailIfExists
);

Параметры

[in] lpExistingFileName

Имя существующего файла.

По умолчанию имя ограничено MAX_PATH символами. Чтобы расширить это ограничение до 32 767 символов в ширину, добавьте к пути "\\?\". Дополнительные сведения см. в статье Именование файлов, путей и пространств имен.

Совет

Начиная с Windows 10 версии 1607, вы можете согласиться на удаление ограничения MAX_PATH без добавления в начало "\\?\". Дополнительные сведения см. в разделе "Ограничение максимальной длины пути" статьи Именование файлов, путей и пространств имен .

Если lpExistingFileName не существует, copyFile завершается ошибкой, а GetLastError возвращает ERROR_FILE_NOT_FOUND.

[in] lpNewFileName

Имя нового файла.

Совет

[in] bFailIfExists

Если этот параметр имеет значение TRUE и новый файл, указанный в параметре lpNewFileName , уже существует, функция завершается ошибкой. Если этот параметр имеет значение FALSE и новый файл уже существует, функция перезаписывает существующий файл и выполняется успешно.

Возвращаемое значение

Если функция выполняется успешно, возвращается ненулевое значение.

Если функция выполняется неудачно, возвращается нулевое значение. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista, Windows Server 2003 и Windows XP: Свойства ресурса безопасности для существующего файла не копируются в новый файл, пока не Windows 8 и Windows Server 2012.

Атрибуты файла для существующего файла копируются в новый файл. Например, если существующий файл имеет атрибут FILE_ATTRIBUTE_READONLY file, копия, созданная с помощью вызова CopyFile , также будет иметь атрибут FILE_ATTRIBUTE_READONLY file. Дополнительные сведения см. в разделе Извлечение и изменение атрибутов файла.

Эта функция завершается сбоем с ERROR_ACCESS_DENIED , если целевой файл уже существует и имеет атрибут FILE_ATTRIBUTE_HIDDEN или FILE_ATTRIBUTE_READONLY .

Если copyFile используется для копирования зашифрованного файла, он пытается зашифровать целевой файл с помощью ключей, используемых при шифровании исходного файла. Если это не удается сделать, эта функция пытается зашифровать целевой файл с помощью ключей по умолчанию. Если ни из этих методов не удается выполнить, copyFile завершается сбоем с кодом ошибки ERROR_ENCRYPTION_FAILED .

Поведение символьной ссылки. Если исходный файл является символьной ссылкой, то фактически скопированный файл является целевым объектом символьной ссылки.

Если целевой файл уже существует и является символьной ссылкой, целевой объект символьной ссылки перезаписывается исходным файлом.

В Windows 8 и Windows Server 2012 эта функция поддерживается следующими технологиями.

Технология	Поддерживается
Протокол SMB 3.0	Да
SMB 3.0 Transparent Failover (TFO)	Да
SMB 3.0 с масштабируемыми общими папками (SO)	Да
Файловая система общего тома кластера (CSVFS)	Да
Восстанавливаемая файловая система (ReFS)	Да

Примеры

Пример см. в разделе Извлечение и изменение атрибутов файла.

Примечание

Заголовок winbase.h определяет CopyFile как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Использование псевдонима, не зависящий от кодирования, с кодом, который не является нейтральным для кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или времени выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

Требование	Значение
Минимальная версия клиента	Windows XP [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2003 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	winbase.h (включая Windows.h)
Библиотека	Kernel32.lib
DLL	Kernel32.dll