Função DeleteFileA (fileapi.h)

Artigo
01/05/2024

Exclui um arquivo existente.

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

Sintaxe

BOOL DeleteFileA(
  [in] LPCSTR lpFileName
);

Parâmetros

[in] lpFileName

O nome do arquivo a ser excluído.

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.

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á 0 (zero). Para obter informações de erro estendidas, chame GetLastError.

Comentários

Se um aplicativo tentar excluir um arquivo que não existe, a função DeleteFile falhará com ERROR_FILE_NOT_FOUND. Se o arquivo for somente leitura, a função falhará com ERROR_ACCESS_DENIED.

A lista a seguir identifica algumas dicas para excluir, remover ou fechar arquivos:

Para excluir um arquivo somente leitura, primeiro você deve remover o atributo somente leitura.
Para excluir ou renomear um arquivo, você deve ter permissão de exclusão no arquivo ou excluir a permissão filho no diretório pai.
Para excluir recursivamente os arquivos em um diretório, use a função SHFileOperation .
Para remover um diretório vazio, use a função RemoveDirectory .
Para fechar um arquivo aberto, use a função CloseHandle .

Se você configurar um diretório com todo o acesso, exceto excluir filho, e as ACL (listas de controle de acesso) de novos arquivos forem herdadas, você poderá criar um arquivo sem poder excluí-lo. No entanto, você pode criar um arquivo e, em seguida, obter todo o acesso solicitado no identificador que é retornado a você no momento em que você criar o arquivo.

Se você solicitar permissão de exclusão no momento em que criar um arquivo, poderá excluir ou renomear o arquivo com esse identificador, mas não com qualquer outro identificador. Para obter mais informações, consulte Segurança de arquivos e Direitos de Acesso.

A função DeleteFile falhará se um aplicativo tentar excluir um arquivo que tenha outros identificadores abertos para E/S normal ou como um arquivo mapeado na memória (FILE_SHARE_DELETE deve ter sido especificado quando outros identificadores foram abertos).

A função DeleteFile marca um arquivo para exclusão no fechamento. Portanto, a exclusão de arquivo não ocorre até que o último identificador para o arquivo seja fechado. Chamadas subsequentes para CreateFile para abrir o arquivo falham com ERROR_ACCESS_DENIED.

O uso da exclusão POSIX faz com que o arquivo seja excluído enquanto os identificadores permanecem abertos. Chamadas subsequentes para CreateFile para abrir o arquivo falham com ERROR_FILE_NOT_FOUND.

Comportamento simbólico do link:

Se o caminho apontar para um link simbólico, o link simbólico será excluído, não o destino. Para excluir um destino, você deve chamar CreateFile e especificar FILE_FLAG_DELETE_ON_CLOSE.

Em Windows 8 e Windows Server 2012, essa função é compatível com as seguintes tecnologias:

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 Bloqueio e desbloqueio de intervalos de bytes em arquivos.

Observação

O cabeçalho fileapi.h define DeleteFile como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

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	fileapi.h (inclua Windows.h)
Biblioteca	Kernel32.lib
DLL	Kernel32.dll