Função DeleteFileA (fileapi.h)
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 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.
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 (0). Para obter informações de erro estendidas, chame GetLastError.
Observações
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 um arquivo 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 e 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 de 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 por 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 do 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 de vínculo:
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 no Windows Server 2012, essa função é compatível com as seguintes tecnologias:
| 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 bloqueio e desbloqueio de intervalos de bytes em arquivos.
Nota
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 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 | fileapi.h (inclua Windows.h) |
| biblioteca | Kernel32.lib |
| de DLL |
Kernel32.dll |