NtQueryInformationByName function (ntifs.h)

Article
02/22/2024

NtQueryInformationByName returns the requested information about a file specified by file name.

Syntax

__kernel_entry NTSYSCALLAPI NTSTATUS NtQueryInformationByName(
  [in]  POBJECT_ATTRIBUTES     ObjectAttributes,
  [out] PIO_STATUS_BLOCK       IoStatusBlock,
  [out] PVOID                  FileInformation,
  [in]  ULONG                  Length,
  [in]  FILE_INFORMATION_CLASS FileInformationClass
);

Parameters

[in] ObjectAttributes

Pointer to an OBJECT_ATTRIBUTES structure that contains the file's attributes, including file name.

[out] IoStatusBlock

Pointer an IO_STATUS_BLOCK structure containing the caller's I/O status.

[out] FileInformation

Pointer to the caller-supplied buffer in which to return the requested information about the file. The structure of the buffer is determined by the FileInformationClass parameter.

[in] Length

Length, in bytes, of the buffer that FileInformation points to.

[in] FileInformationClass

A FILE_INFORMATION_CLASS value that identifies the type of file information to return in the buffer that FileInformation points to. FileInformationClass can be one of the following values.

FILE_INFORMATION_CLASS Value	Type of Information to Return
FileStatInformation (68)	FILE_STAT_INFORMATION. Available starting with Windows 10, version 1709.
FileStatLxInformation (70)	FILE_STAT_LX_INFORMATION. Available starting with Windows 10 April 2018 Update.
FileCaseSensitiveInformation (71)	FILE_CASE_SENSITIVE_INFORMATION. Available starting with Windows 10 April 2018 Update.
FileStatBasicInformation (77)	FILE_STAT_BASIC_INFORMATION. Available starting with Windows 11, build 26048.

Return value

NtQueryInformationByName returns STATUS_SUCCESS upon successful completion; otherwise it returns an error code, such as one of the following.

Error Code	Meaning
STATUS_INVALID_PARAMETER	The FileInformationClass parameter contains an invalid value.
STATUS_INFO_LENGTH_MISMATCH	The buffer size specified by Length is not large enough to contain the requested information.

Remarks

NtQueryInformationByName queries and returns the requested information about the file. It does so without opening the actual file, making it more efficient than NtQueryInformationFile, which requires a file open (and subsequent file close).

Callers of NtQueryInformationByName must be running at IRQL = PASSIVE_LEVEL and with special kernel APCs enabled.

Requirements

Requirement	Value
Minimum supported client	Windows 10, version 1703
Header	ntifs.h
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (see Remarks section)