Função NtSetInformationFile (ntifs.h)

Artigo
02/07/2025

A rotina NtSetInformationFile altera vários tipos de informações sobre um objeto de arquivo.

Sintaxe

__kernel_entry NTSYSCALLAPI NTSTATUS NtSetInformationFile(
  [in]  HANDLE                 FileHandle,
  [out] PIO_STATUS_BLOCK       IoStatusBlock,
  [in]  PVOID                  FileInformation,
  [in]  ULONG                  Length,
  [in]  FILE_INFORMATION_CLASS FileInformationClass
);

Parâmetros

[in] FileHandle

Manipule para o objeto de arquivo. Esse identificador é criado por uma chamada bem-sucedida para NtCreateFile ou NtOpenFile.

[out] IoStatusBlock

Ponteiro para uma estrutura IO_STATUS_BLOCK que recebe o status de conclusão final e informações sobre a operação solicitada. O membro Information recebe o número de bytes definidos no arquivo.

[in] FileInformation

Ponteiro para um buffer que contém as informações a serem definidas para o arquivo. A estrutura específica nesse buffer é determinada pelo parâmetro FileInformationClass. Por exemplo, se o parâmetro FileInformationClass for definido como a constante FileDispositionInformationEx, esse parâmetro deverá ser um ponteiro para uma estrutura FILE_DISPOSITION_INFORMATION_EX.

[in] Length

O tamanho, em bytes, do buffer de FileInformation.

[in] FileInformationClass

O tipo de informação, fornecido no buffer apontado por FileInformation, a ser definido para o arquivo. Os drivers intermediários e de dispositivo podem especificar qualquer um dos seguintes valores de FILE_INFORMATION_CLASS.

FILE_INFORMATION_CLASS valor	Tipo de informação retornada
FileBasicInformation (4)	Altere as informações fornecidas em uma estrutura de FILE_BASIC_INFORMATION. O chamador deve ter aberto o arquivo com o sinalizador FILE_WRITE_ATTRIBUTES definido no parâmetro DesiredAccess.
FileRenameInformation (10)	Altere o nome do arquivo atual, que é fornecido em uma estrutura FILE_RENAME_INFORMATION. O chamador deve ter acesso DELETE ao arquivo.
FileDispositionInformation (13)	Solicite a exclusão do arquivo quando ele for fechado ou cancelar uma exclusão solicitada anteriormente. A escolha de excluir ou cancelar é fornecida em uma estrutura de FILE_DISPOSITION_INFORMATION. O chamador deve ter aberto o arquivo com o sinalizador DELETE definido no parâmetro DesiredAccess.
FilePositionInformation (14)	Altere as informações de arquivo atuais, que são armazenadas em uma estrutura FILE_POSITION_INFORMATION.
FileEndOfFileInformation (20)	Altere as informações de fim de arquivo atuais, fornecidas em uma estrutura de FILE_END_OF_FILE_INFORMATION. A operação pode truncar ou estender o arquivo. O chamador deve ter aberto o arquivo com o sinalizador de FILE_WRITE_DATA definido no parâmetro desiredAccess.
FileValidDataLengthInformation (39)	Altere o comprimento de dados válido atual para o arquivo, que é fornecido em uma estrutura de FILE_VALID_DATA_LENGTH_INFORMATION. O arquivo deve estar em um volume NTFS e o chamador deve ter aberto o arquivo com o sinalizador FILE_WRITE_DATA definido no parâmetro DesiredAccess. Não administradores e usuários remotos devem ter o privilégio SeManageVolumePrivilege.
FileShortNameInformation (40)	Altere o nome do arquivo curto atual, que é fornecido em uma estrutura FILE_NAME_INFORMATION. O arquivo deve estar em um volume NTFS e o chamador deve ter aberto o arquivo com o sinalizador DesiredAccess DELETE definido no parâmetro DesiredAccess.
FileIoPriorityHintInformation (43)	Altere a dica de prioridade de IRP padrão atual para o identificador de arquivo. O novo valor é fornecido em uma estrutura FILE_IO_PRIORITY_HINT_INFORMATION. Essa estrutura deve estar alinhada a 8 bytes.
FileReplaceCompletionInformation (61)	Altere ou remova a porta de conclusão de E/S do identificador de arquivo especificado. O chamador fornece um ponteiro para uma estrutura de FILE_COMPLETION_INFORMATION que especifica um identificador de porta e uma chave de conclusão. Se o identificador de porta não for NULL, esse identificador especificará uma nova porta de conclusão de E/S a ser associada ao identificador de arquivo. Para remover a porta de conclusão de E/S associada ao identificador de arquivo, defina o identificador de porta na estrutura como NULL. Para obter um identificador de porta, um chamador no modo de usuário pode chamar a funçãoCreateIoCompletionPort.
FileDispositionInformationEx (64)	Solicite a exclusão do arquivo ou cancele uma exclusão solicitada anteriormente. A escolha de excluir ou cancelar, bem como as configurações de quando e como a exclusão deve ser executada, são fornecidas em uma estrutura FILE_DISPOSITION_INFORMATION_EX. O chamador deve ter aberto o arquivo com o sinalizador DELETE definido no parâmetro DesiredAccess.
FileCaseSensitiveInformation (71)	Altere as informações fornecidas em uma estrutura FILE_CASE_SENSITIVE_INFORMATION. O chamador deve ter aberto o arquivo com o sinalizador FILE_WRITE_ATTRIBUTES definido no parâmetro DesiredAccess. Esse valor está disponível a partir do Windows 10, versão 1803.
FileLinkInformation (72)	Crie um link rígido para um arquivo existente, que é especificado em uma estrutura de FILE_LINK_INFORMATION. Nem todos os sistemas de arquivos dão suporte a links rígidos; por exemplo, o NTFS faz enquanto FAT não.
FileCaseSensitiveInformationForceAccessCheck (75)	Altere as informações fornecidas em uma estrutura FILE_CASE_SENSITIVE_INFORMATION. O chamador deve ter aberto o arquivo com o sinalizador FILE_WRITE_ATTRIBUTES definido no parâmetro DesiredAccess. Esta é uma versão especial da operação FileCaseSensitiveInformation que é usada para forçar o IOManager a executar verificações de acesso para o driver do modo kernel, semelhante às verificações que se aplicam a um chamador no modo de usuário. Essa operação é reconhecida apenas pelo IOManager e um sistema de arquivos nunca deve recebê-la. Esse valor está disponível a partir do Windows 10, versão 1803.
FileKnownFolderInformation (76)	Uma estrutura FILE_KNOWN_FOLDER_INFORMATION. Disponível a partir do Windows Server 2022.

Valor de retorno

NtSetInformationFile retorna STATUS_SUCCESS ou um status de erro apropriado.

Observações

NtSetInformationFile altera informações sobre um arquivo. Ele ignora qualquer membro de uma estrutura de_INFORMATION XXX FILE_que não tem suporte por um dispositivo ou sistema de arquivos específico.

Se você definir FileInformationClass como FileDispositionInformation, você poderá passar FileHandle para NtClose, mas não para nenhuma outra rotina de arquivo xxx. Como FileDispositionInformation faz com que o arquivo seja marcado para exclusão, é um erro de programação tentar qualquer operação subsequente no identificador que não seja fechá-lo.

Se você definir FileInformationClass como FilePositionInformation e a chamada anterior para NtCreateFile incluir o sinalizador FILE_NO_INTERMEDIATE_BUFFERING no parâmetro CreateOptions, determinadas restrições no currentByteOffset membro da estrutura FILE_POSITION_INFORMATION serão impostas. Para obter mais informações, consulte NtCreateFile.

Se você definir FileInformationClass como FileEndOfFileInformation e o membro EndOfFile do FILE_END_OF_FILE_INFORMATION especificará um deslocamento além da marca de fim de arquivo atual, NtSetInformationFile estenderá o arquivo e adicionará a extensão com zeros.

Para obter mais informações sobre como trabalhar com arquivos, consulte Usando arquivos em um driver.

Os chamadores de NtSetInformationFile devem estar em execução em IRQL = PASSIVE_LEVEL e com APCs de kernel especiais habilitadas.

Nota

Se a chamada para essa função ocorrer no modo de usuário, use o nome "NtSetInformationFile" em vez de "ZwSetInformationFile".

Para chamadas de drivers no modo kernel, as versões NtXxx e Zwxxx versões de uma rotina dos Serviços de Sistema Nativo do Windows podem se comportar de forma diferente na maneira como lidam e interpretam parâmetros de entrada. Para obter mais informações sobre a relação entre as versões NtXxx**** e ZwXxx**** de uma rotina, consulte Usando versões Nt e Zw das rotinas de serviços do sistema nativo.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows 2000.
da Plataforma de Destino	Universal
cabeçalho	ntifs.h (incluem Wdm.h, Ntddk.h, Ntifs.h)
biblioteca	NtosKrnl.lib
de DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (consulte a seção Comentários)
regras de conformidade de DDI	HwStorPortProhibitedDIs, PowerIrpDDis