Função DeleteFile2A (fileapi.h)

Exclui um arquivo existente. Essa função falhará se qualquer parte do lpFileName for redirecionada por meio de um ponto de nova análise ou link simbólico.

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

Sintaxe

BOOL DeleteFile2A(
  LPCSTR lpFileName,
  DWORD  Flags
);

Parâmetros

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, veja Naming Files, Paths, and Namespaces (Nomenclatura de Ficheiros, Caminhos e Espaços de Nomes).

Dica

Você pode aceitar para 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.

Flags

Sinalizadores para especificar como tratar o arquivo que está sendo excluído. Esse parâmetro pode ser uma combinação dos seguintes valores:

Valor	Significado
FILE_FLAG_DISALLOW_PATH_REDIRECTS 0x00010000	Impedir que lpFileName seja redirecionado por pontos de nova análise ou links simbólicos.

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. Os possíveis erros incluem o seguinte:

Código de retorno	Descrição
ERROR_PATH_REDIRECTED	lpFileName foi redirecionado por pontos de nova análise e/ou links simbólicos.

Observações

Se um aplicativo tentar excluir um arquivo que não existe, a função DeleteFile2 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 DeleteFile2 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 DeleteFile2 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, CreateFile2 ou CreateFile3 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. As 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.

Essa função é compatível com as seguintes tecnologias:

Tecnologia	Suportado
Protocolo SMB (Bloco de Mensagens do Servidor) 3.0	Yes
TFO (Failover Transparente) do SMB 3.0	Yes
SMB 3.0 com Compartilhamentos de Arquivos de Expansão (SO)	Yes
Sistema de Arquivos de Volume Compartilhado de Cluster (CsvFS)	Yes
ReFS (Sistema de Arquivos Resiliente)	Yes

Observação

O fileapi.h cabeçalho define DeleteFile2 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.

Exemplos

Para obter um exemplo, consulte Bloqueio e desbloqueio de intervalos de bytes em arquivos.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows 11 24H2 [aplicativos da área de trabalho | Aplicativos UWP]
servidor com suporte mínimo	Windows Server 2025 [aplicativos da área de trabalho | Aplicativos UWP]
cabeçalho	fileapi.h (inclua Windows.h)
Biblioteca	Kernel32.lib
de DLL	Kernel32.dll

Consulte também

CreateDirectory2

CreateFile3

RemoveDirectory2