NtQueryInformationByName - NtDoc

Native API online documentation, based on the System Informer (formerly Process Hacker) phnt headers
#ifndef _NTIOAPI_H
#if (PHNT_VERSION >= PHNT_WINDOWS_10_RS2)

/**
 * The NtQueryInformationByName routine returns various kinds of information about a file object by file name.
 *
 * \param ObjectAttributes Pointer to an OBJECT_ATTRIBUTES structure that contains the file's attributes, including file name.
 * \param IoStatusBlock A pointer to an IO_STATUS_BLOCK structure that receives the final completion status, and the number of bytes written to the buffer pointed to by FileInformation.
 * \param FileInformation Pointer to a caller-allocated buffer into which the routine writes the requested information about the file object.
 * \param Length The size, in bytes, of the buffer pointed to by FileInformation.
 * \param FileInformationClass Specifies the type of information to be returned about the file, in the buffer that FileInformation points to.
 * \return NTSTATUS Successful or errant status.
 * \sa https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/ntifs/nf-ntifs-ntqueryinformationbyname
 * \remarks NtQueryInformationByName queries and returns the requested information without opening the actual file,
 * making it more efficient than NtQueryInformationFile, which requires a file open and subsequent file close.
 */
NTSYSCALLAPI
NTSTATUS
NTAPI
NtQueryInformationByName(
    _In_ PCOBJECT_ATTRIBUTES ObjectAttributes,
    _Out_ PIO_STATUS_BLOCK IoStatusBlock,
    _Out_writes_bytes_(Length) PVOID FileInformation,
    _In_ ULONG Length,
    _In_ FILE_INFORMATION_CLASS FileInformationClass
    );

#endif
#endif

View code on GitHub
#ifndef _NTZWAPI_H

NTSYSCALLAPI
NTSTATUS
NTAPI
ZwQueryInformationByName(
    _In_ PCOBJECT_ATTRIBUTES ObjectAttributes,
    _Out_ PIO_STATUS_BLOCK IoStatusBlock,
    _Out_writes_bytes_(Length) PVOID FileInformation,
    _In_ ULONG Length,
    _In_ FILE_INFORMATION_CLASS FileInformationClass
    );

#endif

View code on GitHub
// ntifs.h

__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
);
View the official Windows Driver Kit DDI reference
// wdm.h

NTSYSAPI NTSTATUS ZwQueryInformationByName(
  [in]  POBJECT_ATTRIBUTES     ObjectAttributes,
  [out] PIO_STATUS_BLOCK       IoStatusBlock,
  [out] PVOID                  FileInformation,
  [in]  ULONG                  Length,
  [in]  FILE_INFORMATION_CLASS FileInformationClass
);
View the official Windows Driver Kit DDI reference

NtDoc

This function is documented in Windows Driver Kit here and here.

Windows Driver Kit DDI reference (nf-ntifs-ntqueryinformationbyname)

NtQueryInformationByName function

Description

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

Parameters

ObjectAttributes [in]

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

IoStatusBlock [out]

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

FileInformation [out]

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.

Length [in]

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

FileInformationClass [in]

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.

See also

FILE_CASE_SENSITIVE_INFORMATION

FILE_INFORMATION_CLASS

FILE_STAT_INFORMATION

FILE_STAT_LX_INFORMATION

IO_STATUS_BLOCK

NtQueryInformationFile

OBJECT_ATTRIBUTES


Windows Driver Kit DDI reference (nf-wdm-zwqueryinformationbyname)

Description

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

Parameters

ObjectAttributes [in]

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

IoStatusBlock [out]

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

FileInformation [out]

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.

Length [in]

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

FileInformationClass [in]

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.

Return value

ZwQueryInformationByName 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

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

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

See also

FILE_CASE_SENSITIVE_INFORMATION

FILE_INFORMATION_CLASS

FILE_STAT_INFORMATION

FILE_STAT_LX_INFORMATION

IO_STATUS_BLOCK

OBJECT_ATTRIBUTES

ZwQueryInformationFile