NtQueryObject - NtDoc

Native API online documentation, based on the System Informer (formerly Process Hacker) phnt headers 
#ifndef _NTOBAPI_H
//
// Objects, handles
//
#if (PHNT_MODE != PHNT_MODE_KERNEL)

/**
 * The NtQueryObject routine retrieves various kinds of object information.
 *
 * @param Handle The handle of the object for which information is being queried.
 * @param ObjectInformationClass The information class indicating the kind of object information to be retrieved.
 * @param ObjectInformation An optional pointer to a buffer where the requested information is to be returned.
 * @param ObjectInformationLength The size of the buffer pointed to by the ObjectInformation parameter, in bytes.
 * @param ReturnLength An optional pointer to a location where the function writes the actual size of the information requested.
 * @return NTSTATUS Successful or errant status.
 * @sa https://learn.microsoft.com/en-us/windows/win32/api/winternl/nf-winternl-ntqueryobject
 */
NTSYSCALLAPI
NTSTATUS
NTAPI
NtQueryObject(
    _In_opt_ HANDLE Handle,
    _In_ OBJECT_INFORMATION_CLASS ObjectInformationClass,
    _Out_writes_bytes_opt_(ObjectInformationLength) PVOID ObjectInformation,
    _In_ ULONG ObjectInformationLength,
    _Out_opt_ PULONG ReturnLength
    );

#endif
#endif

View code on GitHub
#ifndef _NTZWAPI_H

NTSYSCALLAPI
NTSTATUS
NTAPI
ZwQueryObject(
    _In_opt_ HANDLE Handle,
    _In_ OBJECT_INFORMATION_CLASS ObjectInformationClass,
    _Out_writes_bytes_opt_(ObjectInformationLength) PVOID ObjectInformation,
    _In_ ULONG ObjectInformationLength,
    _Out_opt_ PULONG ReturnLength
    );

#endif

View code on GitHub
// ntifs.h

__kernel_entry NTSYSCALLAPI NTSTATUS NtQueryObject(
  [in, optional]  HANDLE                   Handle,
  [in]            OBJECT_INFORMATION_CLASS ObjectInformationClass,
  [out, optional] PVOID                    ObjectInformation,
  [in]            ULONG                    ObjectInformationLength,
  [out, optional] PULONG                   ReturnLength
);
View the official Windows Driver Kit DDI reference
// ntifs.h

NTSYSAPI NTSTATUS ZwQueryObject(
  [in, optional]  HANDLE                   Handle,
  [in]            OBJECT_INFORMATION_CLASS ObjectInformationClass,
  [out, optional] PVOID                    ObjectInformation,
  [in]            ULONG                    ObjectInformationLength,
  [out, optional] PULONG                   ReturnLength
);
View the official Windows Driver Kit DDI reference
// winternl.h

__kernel_entry NTSYSCALLAPI NTSTATUS NtQueryObject(
  [in, optional]  HANDLE                   Handle,
  [in]            OBJECT_INFORMATION_CLASS ObjectInformationClass,
  [out, optional] PVOID                    ObjectInformation,
  [in]            ULONG                    ObjectInformationLength,
  [out, optional] PULONG                   ReturnLength
);
View the official Win32 API reference

NtDoc

Retrieves various information about kernel handles and the objects they point to. This function is partially documented in Windows Driver Kit here and here.

Parameters

Information classes

For the list of supported information classes, see OBJECT_INFORMATION_CLASS.

Notable return values

Related Win32 API

See also

Edit description on GitHub

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

NtQueryObject function

Description

The NtQueryObject routine provides information about a supplied object.

Parameters

Handle [in, optional]

A handle to the object to obtain information about.

ObjectInformationClass [in]

Specifies an OBJECT_INFORMATION_CLASS value that determines the type of information returned in the ObjectInformation buffer.

ObjectInformation [out, optional]

A pointer to a caller-allocated buffer that receives the requested information.

ObjectInformationLength [in]

Specifies the size, in bytes, of the ObjectInformation buffer.

ReturnLength [out, optional]

A pointer to a variable that receives the size, in bytes, of the requested key information. If NtQueryObject returns STATUS_SUCCESS, the variable contains the amount of data returned. If NtQueryObject returns STATUS_BUFFER_OVERFLOW or STATUS_BUFFER_TOO_SMALL, you can use the value of the variable to determine the required buffer size.

Return value

NtQueryObject returns STATUS_SUCCESS or an appropriate error status. Possible error status codes include the following:

Return code Description
STATUS_ACCESS_DENIED There were insufficient permissions to perform this query.
STATUS_INVALID_HANDLE The supplied object handle is invalid.
STATUS_INFO_LENGTH_MISMATCH The info length is not sufficient to hold the data.

Remarks

If the call to the NtQueryObject function occurs in user mode, you should use the name "NtQueryObject" instead of "ZwQueryObject".

For calls from kernel-mode drivers, the Nt*Xxx* and Zw*Xxx* versions of a Windows Native System Services routine can behave differently in the way that they handle and interpret input parameters. For more information about the relationship between the Nt*Xxx* and Zw*Xxx* versions of a routine, see Using Nt and Zw Versions of the Native System Services Routines.

See also

OBJECT_INFORMATION_CLASS

PUBLIC_OBJECT_BASIC_INFORMATION

PUBLIC_OBJECT_TYPE_INFORMATION

View the official Windows Driver Kit DDI reference

Edit description on GitHub

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

ZwQueryObject function

Description

The ZwQueryObject routine provides information about a supplied object.

Parameters

Handle [in, optional]

A handle to the object to obtain information about.

ObjectInformationClass [in]

Specifies an OBJECT_INFORMATION_CLASS value that determines the type of information returned in the ObjectInformation buffer.

ObjectInformation [out, optional]

A pointer to a caller-allocated buffer that receives the requested information.

ObjectInformationLength [in]

Specifies the size, in bytes, of the ObjectInformation buffer.

ReturnLength [out, optional]

A pointer to a variable that receives the size, in bytes, of the requested key information. If ZwQueryObject returns STATUS_SUCCESS, the variable contains the amount of data returned. If ZwQueryObject returns STATUS_BUFFER_OVERFLOW or STATUS_BUFFER_TOO_SMALL, you can use the value of the variable to determine the required buffer size.

Return value

ZwQueryObject returns STATUS_SUCCESS or an appropriate error status. Possible error status codes include the following:

Return code Description
STATUS_ACCESS_DENIED There were insufficient permissions to perform this query.
STATUS_INVALID_HANDLE The supplied object handle is invalid.
STATUS_INFO_LENGTH_MISMATCH The info length is not sufficient to hold the data.

Remarks

If the call to the ZwQueryObject function occurs in user mode, you should use the name "NtQueryObject" instead of "ZwQueryObject".

For calls from kernel-mode drivers, the Nt*Xxx* and Zw*Xxx* versions of a Windows Native System Services routine can behave differently in the way that they handle and interpret input parameters. For more information about the relationship between the Nt*Xxx* and Zw*Xxx* versions of a routine, see Using Nt and Zw Versions of the Native System Services Routines.

See also

OBJECT_INFORMATION_CLASS

PUBLIC_OBJECT_BASIC_INFORMATION

PUBLIC_OBJECT_TYPE_INFORMATION

Using Nt and Zw Versions of the Native System Services Routines

View the official Windows Driver Kit DDI reference

Edit description on GitHub

Win32 API reference (nf-winternl-ntqueryobject)

NtQueryObject function

Description

[This function may be changed or removed from Windows without further notice.]

Retrieves various kinds of object information.

Parameters

Handle [in, optional]

The handle of the object for which information is being queried.

ObjectInformationClass [in]

One of the following values, as enumerated in OBJECT_INFORMATION_CLASS, indicating the kind of object information to be retrieved.

Term Description
ObjectBasicInformation Returns a PUBLIC_OBJECT_BASIC_INFORMATION structure as shown in the following Remarks section.
ObjectTypeInformation Returns a PUBLIC_OBJECT_TYPE_INFORMATION structure as shown in the following Remarks section.

ObjectInformation [out, optional]

An optional pointer to a buffer where the requested information is to be returned. The size and structure of this information varies depending on the value of the ObjectInformationClass parameter.

ObjectInformationLength [in]

The size of the buffer pointed to by the ObjectInformation parameter, in bytes.

ReturnLength [out, optional]

An optional pointer to a location where the function writes the actual size of the information requested. If that size is less than or equal to the ObjectInformationLength parameter, the function copies the information into the ObjectInformation buffer; otherwise, it returns an NTSTATUS error code and returns in ReturnLength the size of the buffer required to receive the requested information.

Return value

Returns an NTSTATUS or error code.

The forms and significance of NTSTATUS error codes are listed in the Ntstatus.h header file available in the WDK, and are described in the WDK documentation.

Remarks

This function has no associated header file or import library. You must use the LoadLibrary or GetProcAddress function to dynamically link to Ntdll.dll.

If the ObjectInformationClass parameter is ObjectBasicInformation, the information is contained in the following structure.

typedef struct _PUBLIC_OBJECT_BASIC_INFORMATION {
    ULONG Attributes;
    ACCESS_MASK GrantedAccess;
    ULONG HandleCount;
    ULONG PointerCount;
    ULONG Reserved[10];    // reserved for internal use
 } PUBLIC_OBJECT_BASIC_INFORMATION, *PPUBLIC_OBJECT_BASIC_INFORMATION;

Available members for this structure include object attributes for the handle (Attributes), the access granted for the handle (GrantedAccess), the number of open handles to the object (HandleCount), and the number of kernel references to the object (PointerCount).

If the ObjectInformationClass parameter is ObjectTypeInformation, the information is contained in the following structure.

typedef struct __PUBLIC_OBJECT_TYPE_INFORMATION {
    UNICODE_STRING TypeName;
    ULONG Reserved [22];    // reserved for internal use
} PUBLIC_OBJECT_TYPE_INFORMATION, *PPUBLIC_OBJECT_TYPE_INFORMATION;

The only available member of this structure is the object-type name string (TypeName).

View the official Win32 API reference

Edit description on GitHub

NTinternals.net (undocumented.ntinternals.net)

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

Function NtQueryObject retrieves some information about any or all objects opened by calling process. It can be used with any type of object.

ObjectHandle

HANDLE to object.

ObjectInformationClass

Kind of information to retrieve. See OBJECT_INFORMATION_CLASS for possible values list.

ObjectInformation

Output buffer allocated by caller.

Length

Length of ObjectInformation buffer, in bytes.

ResultLength

Pointer to ULONG value that contains required size of ObjectInformation buffer after function call.

Documented by

See also

Edit description on GitHub