Função CopyFile (winbase.h)

Artigo
03/03/2024

Copia um arquivo existente para um novo arquivo.

A função CopyFileEx fornece dois recursos adicionais. CopyFileEx pode chamar uma função de retorno de chamada especificada sempre que uma parte da operação de cópia é concluída e CopyFileEx pode ser cancelada durante a operação de cópia.

Para executar essa operação como uma operação transacionada, use a função CopyFileTransacted .

Sintaxe

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

Parâmetros

[in] lpExistingFileName

O nome de um arquivo existente.

Por padrão, o nome é limitado a caracteres MAX_PATH. Para estender esse limite para 32.767 caracteres largos, preencha "\\?\" para o caminho. Para obter mais informações, confira Nomear arquivos, caminhos e namespaces.

Dica

A partir do Windows 10, versão 1607, você pode optar por remover a limitação de MAX_PATH sem acrescentar "\\?\". Consulte a seção "Limitação máxima de comprimento do caminho" de Arquivos de Nomenclatura, Caminhos e Namespaces para obter detalhes.

Se lpExistingFileName não existir, CopyFile falhará e GetLastErrorretornará ERROR_FILE_NOT_FOUND.

[in] lpNewFileName

O nome do novo arquivo.

Dica

[in] bFailIfExists

Se esse parâmetro for TRUE e o novo arquivo especificado por lpNewFileName já existir, a função falhará. Se esse parâmetro for FALSE e o novo arquivo já existir, a função substituirá o arquivo existente e terá êxito.

Valor retornado

Se a função for bem-sucedida, o valor retornado será diferente de zero.

Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError.

Comentários

As propriedades do recurso de segurança (ATTRIBUTE_SECURITY_INFORMATION) para o arquivo existente são copiadas para o novo arquivo.

Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP: As propriedades de recurso de segurança do arquivo existente não são copiadas para o novo arquivo até Windows 8 e Windows Server 2012.

Os atributos de arquivo para o arquivo existente são copiados para o novo arquivo. Por exemplo, se um arquivo existente tiver o atributo de arquivo FILE_ATTRIBUTE_READONLY , uma cópia criada por meio de uma chamada para CopyFile também terá o atributo de arquivo FILE_ATTRIBUTE_READONLY . Para obter mais informações, consulte Recuperando e alterando atributos de arquivo.

Essa função falhará com ERROR_ACCESS_DENIED se o arquivo de destino já existir e tiver o atributo FILE_ATTRIBUTE_HIDDEN ou FILE_ATTRIBUTE_READONLY definido.

Quando CopyFile é usado para copiar um arquivo criptografado, ele tenta criptografar o arquivo de destino com as chaves usadas na criptografia do arquivo de origem. Se isso não puder ser feito, essa função tentará criptografar o arquivo de destino com chaves padrão. Se nenhum desses métodos puder ser feito, o CopyFile falhará com um código de erro ERROR_ENCRYPTION_FAILED .

Comportamento simbólico do link – se o arquivo de origem for um link simbólico, o arquivo real copiado será o destino do link simbólico.

Se o arquivo de destino já existir e for um link simbólico, o destino do link simbólico será substituído pelo arquivo de origem.

No Windows 8 e Windows Server 2012, essa função é compatível com as tecnologias a seguir.

Tecnologia	Com suporte
Protocolo SMB (SMB) 3.0	Sim
TFO (Failover transparente) do SMB 3.0	Sim
SMB 3.0 com compartilhamentos de arquivos de expansão (SO)	Sim
Sistema de arquivos de Volume Compartilhado Clusterizado (CsvFS)	Sim
ReFS (Sistema de Arquivos Resiliente)	Sim

Exemplos

Para obter um exemplo, consulte Recuperando e alterando atributos de arquivo.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows XP [aplicativos da área de trabalho \| aplicativos UWP]
Servidor mínimo com suporte	Windows Server 2003 [aplicativos da área de trabalho \| Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	winbase.h (inclua Windows.h)
Biblioteca	Kernel32.lib
DLL	Kernel32.dll