NtQueryInformationProcess function

Description

[NtQueryInformationProcess may be altered or unavailable in future versions of Windows. Applications should use the alternate functions listed in this topic.]

Retrieves information about the specified process.

Parameters

ProcessHandle [in]

A handle to the process for which information is to be retrieved.

ProcessInformationClass [in]

The type of process information to be retrieved. This parameter can be one of the following values from the PROCESSINFOCLASS enumeration.

ProcessInformation [out]

A pointer to a buffer supplied by the calling application into which the function writes the requested information. The size of the information written varies depending on the data type of the ProcessInformationClass parameter:

PROCESS_BASIC_INFORMATION

When the ProcessInformationClass parameter is ProcessBasicInformation, the buffer pointed to by the ProcessInformation parameter should be large enough to hold a single PROCESS_BASIC_INFORMATION structure having the following layout:

typedef struct _PROCESS_BASIC_INFORMATION {
    NTSTATUS ExitStatus;
    PPEB PebBaseAddress;
    ULONG_PTR AffinityMask;
    KPRIORITY BasePriority;
    ULONG_PTR UniqueProcessId;
    ULONG_PTR InheritedFromUniqueProcessId;
} PROCESS_BASIC_INFORMATION;

ULONG_PTR

When the ProcessInformationClass parameter is ProcessWow64Information, the buffer pointed to by the ProcessInformation parameter should be large enough to hold a ULONG_PTR. If this value is nonzero, the process is running in a WOW64 environment. Otherwise, the process is not running in a WOW64 environment.

Use the IsWow64Process2 function to determine whether a process is running in the WOW64 environment.

UNICODE_STRING

When the ProcessInformationClass parameter is ProcessImageFileName, the buffer pointed to by the ProcessInformation parameter should be large enough to hold a UNICODE_STRING structure as well as the string itself. The string stored in the Buffer member is the name of the image file.

If the buffer is too small, the function fails with the STATUS_INFO_LENGTH_MISMATCH error code and the ReturnLength parameter is set to the required buffer size.

ProcessInformationLength [in]

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

ReturnLength [out, optional]

A pointer to a variable in which the function returns the size of the requested information. If the function was successful, this is the size of the information written to the buffer pointed to by the ProcessInformation parameter (if the buffer was too small, this is the minimum size of buffer needed to receive the information successfully).

Return value

The function returns an NTSTATUS success or error code.

The forms and significance of NTSTATUS error codes are listed in the Ntstatus.h header file available in the DDK. See Logging Errors for more details.

Remarks

The NtQueryInformationProcess function and the structures that it returns are internal to the operating system and subject to change from one release of Windows to another. To maintain the compatibility of your application, it is better to use public functions mentioned in the description of the ProcessInformationClass parameter instead.

If you do use NtQueryInformationProcess, access the function through run-time dynamic linking. This gives your code an opportunity to respond gracefully if the function has been changed or removed from the operating system. Signature changes, however, may not be detectable.

This function has no associated import library. You must use the LoadLibrary and GetProcAddress functions to dynamically link to Ntdll.dll.

See also

CheckRemoteDebuggerPresent

GetProcessId

IsDebuggerPresent

IsWow64Process

IsWow64Process2

ZwQueryInformationProcess function

[ZwQueryInformationProcess may be altered or unavailable in future versions of Windows. Applications should use the alternate functions listed in this topic.]

Retrieves information about the specified process.

Parameters

ProcessHandle [in]

A handle to the process for which information is to be retrieved.

ProcessInformationClass [in]

The type of process information to be retrieved. This parameter can be one of the following values from the PROCESSINFOCLASS enumeration.

ProcessInformation [out]

A pointer to a buffer supplied by the calling application into which the function writes the requested information. The size of the information written varies depending on the value of the ProcessInformationClass parameter:

PROCESS_BASIC_INFORMATION

When the ProcessInformationClass parameter is ProcessBasicInformation, the buffer pointed to by the ProcessInformation parameter should be large enough to hold a single PROCESS_BASIC_INFORMATION structure having the following layout:

typedef struct _PROCESS_BASIC_INFORMATION {
    NTSTATUS ExitStatus;
    PPEB PebBaseAddress;
    ULONG_PTR AffinityMask;
    KPRIORITY BasePriority;
    ULONG_PTR UniqueProcessId;
    ULONG_PTR InheritedFromUniqueProcessId;
} PROCESS_BASIC_INFORMATION;

ULONG_PTR

When the ProcessInformationClass parameter is ProcessWow64Information, the buffer pointed to by the ProcessInformation parameter should be large enough to hold a ULONG_PTR. If this value is nonzero, the process is running in a WOW64 environment; otherwise, if the value is equal to zero, the process is not running in a WOW64 environment.

It is best to use the IsWow64Process function to determine whether a process is running in the WOW64 environment.

UNICODE_STRING

When the ProcessInformationClass parameter is ProcessImageFileName, the buffer pointed to by the ProcessInformation parameter should be large enough to hold a UNICODE_STRING structure as well as the string itself. The string stored in the Buffer member is the name of the image file.

If the buffer is too small, the function fails with the STATUS_INFO_LENGTH_MISMATCH error code and the ReturnLength parameter is set to the required buffer size.

PS_PROTECTION

When the ProcessInformationClass parameter is ProcessProtectionInformation, the buffer pointed to by the ProcessInformation parameter should be large enough to hold a single PS_PROTECTION structure having the following layout:

typedef struct _PS_PROTECTION {
    union {
        UCHAR Level;
        struct {
            UCHAR Type   : 3;
            UCHAR Audit  : 1;                  // Reserved
            UCHAR Signer : 4;
        };
    };
} PS_PROTECTION, *PPS_PROTECTION;

The first 3 bits contain the type of protected process:

typedef enum _PS_PROTECTED_TYPE {
    PsProtectedTypeNone = 0,
    PsProtectedTypeProtectedLight = 1,
    PsProtectedTypeProtected = 2
} PS_PROTECTED_TYPE, *PPS_PROTECTED_TYPE;

The top 4 bits contain the protected process signer:

typedef enum _PS_PROTECTED_SIGNER {
    PsProtectedSignerNone = 0,
    PsProtectedSignerAuthenticode,
    PsProtectedSignerCodeGen,
    PsProtectedSignerAntimalware,
    PsProtectedSignerLsa,
    PsProtectedSignerWindows,
    PsProtectedSignerWinTcb,
    PsProtectedSignerWinSystem,
    PsProtectedSignerApp,
    PsProtectedSignerMax
} PS_PROTECTED_SIGNER, *PPS_PROTECTED_SIGNER;

ProcessInformationLength [in]

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

ReturnLength [out, optional]

A pointer to a variable in which the function returns the size of the requested information. If the function was successful, this is the size of the information written to the buffer pointed to by the ProcessInformation parameter, but if the buffer was too small, this is the minimum size of buffer needed to receive the information successfully.

Return value

Returns an NTSTATUS success or error code.

The forms and significance of NTSTATUS error codes are listed in the Ntstatus.h header file available in the DDK, and are described in the DDK documentation under Kernel-Mode Driver Architecture / Design Guide / Driver Programming Techniques / Logging Errors.

Remarks

The ZwQueryInformationProcess function and the structures that it returns are internal to the operating system and subject to change from one release of Windows to another. To maintain the compatibility of your application, it is better to use public functions mentioned in the description of the ProcessInformationClass parameter instead.

If you do use ZwQueryInformationProcess, access the function through run-time dynamic linking. This gives your code an opportunity to respond gracefully if the function has been changed or removed from the operating system. Signature changes, however, may not be detectable.

This function has no associated import library. You must use the LoadLibrary and GetProcAddress functions to dynamically link to Ntdll.dll.

Requirements

See also

CheckRemoteDebuggerPresent

GetProcessId

IsDebuggerPresent

IsWow64Process

This function is documented in Windows SDK.

ProcessHandle

Handle to process opened with PROCESS_QUERY_INFORMATION access.

ProcessInformationClass

See PROCESS_INFORMATION_CLASS.

ProcessInformation

Buffer for results.

ProcessInformationLength

Length of buffer. See PROCESS_INFORMATION_CLASS for additional information.

ReturnLength

Number of bytes needed, if ProcessInformationLength was too small.

Documented by

• ReactOS
• Sven B. Schreiber
• Tomasz Nowak

See also

• NtCreateProcess
• NtOpenProcess
• NtSetInformationProcess
• PROCESS_INFORMATION_CLASS