Função CopyFileA (winbase.h)
Copia um arquivo existente para um novo arquivo.
A função
Para executar essa operação como uma operação transacionada, use a função CopyFileTransacted.
Sintaxe
BOOL CopyFileA(
[in] LPCSTR lpExistingFileName,
[in] LPCSTR lpNewFileName,
[in] BOOL bFailIfExists
);
Parâmetros
[in] lpExistingFileName
O nome de um arquivo existente.
Por padrão, o nome é limitado a MAX_PATH caracteres. Para estender esse limite para 32.767 caracteres de largura, acrescente "\\?\" ao caminho. Para obter mais informações, consulte Arquivos de Nomenclatura, Caminhos e Namespaces.
Ponta
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 do comprimento do caminho" de arquivos de nomenclatura, caminhos e namespaces para obter detalhes.
Se lpExistingFileName não existir, CopyFile falhará e GetLastError retornará ERROR_FILE_NOT_FOUND.
[in] lpNewFileName
O nome do novo arquivo.
Por padrão, o nome é limitado a MAX_PATH caracteres. Para estender esse limite para 32.767 caracteres de largura, acrescente "\\?\" ao caminho. Para obter mais informações, consulte Arquivos de Nomenclatura, Caminhos e Namespaces.
Ponta
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 do comprimento do caminho" de arquivos de nomenclatura, caminhos e namespaces para obter detalhes.
[in] bFailIfExists
Se esse parâmetro for verdadeiro 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 de retorno
Se a função for bem-sucedida, o valor retornado não será zero.
Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError.
Observações
As propriedades do recurso de segurança (ATTRIBUTE_SECURITY_INFORMATION) do 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 serão copiadas para o novo arquivo até o Windows 8 e o 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 Recuperação e alteração de atributos de arquivo.
Essa função falhará com ERROR_ACCESS_DENIED se o arquivo de destino já existir e tiver o FILE_ATTRIBUTE_HIDDEN ou FILE_ATTRIBUTE_READONLY conjunto de atributos.
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, 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 no Windows Server 2012, essa função é compatível com as tecnologias a seguir.
| Tecnologia | Suportado |
|---|---|
| Protocolo SMB (Bloco de Mensagens do Servidor) 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 de Cluster (CsvFS) | Sim |
| ReFS (Sistema de Arquivos Resiliente) | Sim |
Exemplos
Para obter um exemplo, consulte Recuperar e alterar atributos de arquivo.
Nota
O cabeçalho winbase.h define CopyFile como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.
Requisitos
| Requisito | Valor |
|---|---|
| de cliente com suporte mínimo | Windows XP [aplicativos da área de trabalho | Aplicativos UWP] |
| servidor com suporte mínimo | Windows Server 2003 [aplicativos da área de trabalho | Aplicativos UWP] |
| da Plataforma de Destino |
Windows |
| cabeçalho | winbase.h (inclua Windows.h) |
| biblioteca | Kernel32.lib |
| de DLL |
Kernel32.dll |
Consulte também
constantes de atributo de arquivo
Funções de gerenciamento de arquivos
movefile