Função DeleteFile (winbase.h)
Exclui um arquivo existente.
Para executar essa operação como uma operação transacionada, use a função DeleteFileTransacted .
Sintaxe
BOOL DeleteFile(
[in] LPCTSTR lpFileName
);
Parâmetros
[in] lpFileName
O nome do arquivo a ser excluído.
Por padrão, o nome é limitado a MAX_PATH caracteres. Para estender esse limite para 32.767 caracteres largos, acrescente "\\?\" ao 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 do 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ê 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 arquivo 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 do arquivo não ocorre até que o último identificador do arquivo seja fechado. As chamadas subsequentes para CreateFile para abrir o arquivo falham com ERROR_ACCESS_DENIED.
Comportamento de link simbólico—
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.
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 Bloqueio e desbloqueio de intervalos de bytes em arquivos.
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 (incluir Windows.h) |
| Biblioteca | Kernel32.lib |
| DLL | Kernel32.dll |