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

Статья
11/20/2024

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

Функция 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.

Замечания

Свойства ресурса безопасности (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. Дополнительные сведения см. в получении и изменении атрибутов файла.

Эта функция завершается ошибкой 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 (TFO)	Да
SMB 3.0 с масштабируемыми общими папками (SO)	Да
Файловая система общего тома кластера (CSVFS)	Да
Отказоустойчивая файловая система (ReFS)	Да

Примеры

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

Заметка

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

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows XP [классические приложения \| Приложения UWP]
минимальный поддерживаемый сервер	Windows Server 2003 [классические приложения \| Приложения UWP]
целевая платформа	Виндоус
заголовка	winbase.h (включая Windows.h)
библиотеки	Kernel32.lib
DLL	Kernel32.dll