#ifndef _NTPSAPI_H
//
// Processes
//
#if (PHNT_MODE != PHNT_MODE_KERNEL)
//#define NtCurrentLogonId() (NtCurrentPeb()->LogonId)
/**
* Retrieves information about the specified process.
*
* \param ProcessHandle A handle to the process.
* \param ProcessInformationClass The type of process information to be retrieved.
* \param ProcessInformation A pointer to a buffer that receives the process information.
* \param ProcessInformationLength The size of the buffer pointed to by the ProcessInformation parameter.
* \param ReturnLength An optional pointer to a variable that receives the size of the data returned.
* \return NTSTATUS Successful or errant status.
*/
NTSYSCALLAPI
NTSTATUS
NTAPI
NtQueryInformationProcess(
_In_ HANDLE ProcessHandle,
_In_ PROCESSINFOCLASS ProcessInformationClass,
_Out_writes_bytes_(ProcessInformationLength) PVOID ProcessInformation,
_In_ ULONG ProcessInformationLength,
_Out_opt_ PULONG ReturnLength
);
View code on GitHub
#ifndef _NTZWAPI_H
NTSYSCALLAPI
NTSTATUS
NTAPI
ZwQueryInformationProcess(
_In_ HANDLE ProcessHandle,
_In_ PROCESSINFOCLASS ProcessInformationClass,
_Out_writes_bytes_(ProcessInformationLength) PVOID ProcessInformation,
_In_ ULONG ProcessInformationLength,
_Out_opt_ PULONG ReturnLength
);
View code on GitHub
// winternl.h
__kernel_entry NTSTATUS NtQueryInformationProcess(
[in] HANDLE ProcessHandle,
[in] PROCESSINFOCLASS ProcessInformationClass,
[out] PVOID ProcessInformation,
[in] ULONG ProcessInformationLength,
[out, optional] PULONG ReturnLength
);
View the official Win32 API reference
NTSTATUS WINAPI ZwQueryInformationProcess(
_In_ HANDLE ProcessHandle,
_In_ PROCESSINFOCLASS ProcessInformationClass,
_Out_ PVOID ProcessInformation,
_In_ ULONG ProcessInformationLength,
_Out_opt_ PULONG ReturnLength
);
View the official Win32 development documentation
Queries various information about the specified process. This function is partially documented in Windows SDK.
ProcessHandle
- a handle to the process or the NtCurrentProcess
pseudo-handle. For most information classes, the handle must grant either PROCESS_QUERY_INFORMATION
or PROCESS_QUERY_LIMITED_INFORMATION
access.ProcessInformationClass
- the type of information to retrieve.ProcessInformation
- a pointer to a user-allocated buffer that receives the requested information.ProcessInformationLength
- the size of the provided buffer in bytes.ReturnLength
- an optional pointer to a variable that receives the number of bytes written when the function succeeds or the number of bytes requires when the buffer is too small.For the list of supported info classes and required process access, see PROCESSINFOCLASS
.
STATUS_BUFFER_TOO_SMALL
and STATUS_INFO_LENGTH_MISMATCH
indicate that the requested information does not fit into the provided buffer.GetExitCodeProcess
GetProcessId
GetProcessInformation
GetProcessMitigationPolicy
IsWow64Process
IsProcessCritical
ProcessIdToSessionId
QueryProcessCycleTime
QueryProcessAffinityUpdateMode
GetProcessWorkingSetSizeEx
GetProcessTimes
GetErrorMode
GetProcessHandleCount
GetProcessPriorityBoost
GetProcessVersion
GetProcessGroupAffinity
GetPriorityClass
GetLogicalDrives
[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.
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.
Value | Meaning |
---|---|
ProcessBasicInformation 0 |
Retrieves a pointer to a PEB structure that can be used to determine whether the specified process is being debugged, and a unique value used by the system to identify the specified process. Use the CheckRemoteDebuggerPresent and GetProcessId functions to obtain this information. |
ProcessDebugPort 7 |
Retrieves a DWORD_PTR value that is the port number of the debugger for the process. A nonzero value indicates that the process is being run under the control of a ring 3 debugger. Use the CheckRemoteDebuggerPresent or IsDebuggerPresent function. |
ProcessWow64Information 26 |
Determines whether the process is running in the WOW64 environment (WOW64 is the x86 emulator that allows Win32-based applications to run on 64-bit Windows). Use the IsWow64Process2 function to obtain this information. |
ProcessImageFileName 27 |
Retrieves a UNICODE_STRING value containing the name of the image file for the process. Use the QueryFullProcessImageName or GetProcessImageFileName function to obtain this information. |
ProcessBreakOnTermination 29 |
Retrieves a ULONG value indicating whether the process is considered critical. Note This value can be used starting in Windows XP with SP3. Starting in Windows 8.1, IsProcessCritical should be used instead. |
ProcessTelemetryIdInformation 64 |
Retrieves a PROCESS_TELEMETRY_ID_INFORMATION_TYPE value that contains metadata about a process. |
ProcessSubsystemInformation 75 |
Retrieves a SUBSYSTEM_INFORMATION_TYPE value indicating the subsystem type of the process. The buffer pointed to by the ProcessInformation parameter should be large enough to hold a single SUBSYSTEM_INFORMATION_TYPE 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:
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;
Field | Meaning |
---|---|
ExitStatus | Contains the same value that GetExitCodeProcess returns. However the use of GetExitCodeProcess is preferable for clarity and safety. |
PebBaseAddress | Points to a PEB structure. |
AffinityMask | Can be cast to a DWORD and contains the same value that GetProcessAffinityMask returns for the lpProcessAffinityMask parameter. |
BasePriority | Contains the process priority as described in Scheduling Priorities. |
UniqueProcessId | Can be cast to a DWORD and contains a unique identifier for this process. We recommend using the GetProcessId function to retrieve this information. |
InheritedFromUniqueProcessId | Can be cast to a DWORD and contains a unique identifier for the parent process. |
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.
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).
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.
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.
[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.
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.
Value | Meaning |
---|---|
ProcessBasicInformation 0 |
Retrieves a pointer to a PEB structure that can be used to determine whether the specified process is being debugged, and a unique value used by the system to identify the specified process. It is best to use the CheckRemoteDebuggerPresent and GetProcessId functions to obtain this information. |
ProcessDebugPort 7 |
Retrieves a DWORD_PTR value that is the port number of the debugger for the process. A nonzero value indicates that the process is being run under the control of a ring 3 debugger. It is best to use the CheckRemoteDebuggerPresent or IsDebuggerPresent function. |
ProcessWow64Information 26 |
Determines whether the process is running in the WOW64 environment (WOW64 is the x86 emulator that allows Win32-based applications to run on 64-bit Windows). It is best to use the IsWow64Process function to obtain this information. |
ProcessImageFileName 27 |
Retrieves a UNICODE_STRING value containing the name of the image file for the process. |
ProcessBreakOnTermination 29 |
Retrieves a ULONG value indicating whether the process is considered critical. Note: This value can be used starting in Windows XP with SP3. Starting in Windows 8.1, IsProcessCritical should be used instead. |
ProcessProtectionInformation 61 |
Retrieves a BYTE value indicating the type of protected process and the protected process signer. |
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:
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;
Field | Meaning |
---|---|
ExitStatus | Contains the same value that GetExitCodeProcess would return. However the use of GetExitCodeProcess is preferable for clarity and safety. |
PebBaseAddress | Points to a PEB structure. |
AffinityMask | Can be cast to a DWORD and contains the same value that GetProcessAffinityMask would return for the lpProcessAffinityMask parameter. |
BasePriority | Contains the process priority as described in Scheduling Priorities. |
UniqueProcessId | Can be cast to a DWORD and contains a unique identifier for this process. It is best to use the GetProcessId function to retrieve this information. |
InheritedFromUniqueProcessId | Can be cast to a DWORD and contains a unique identifier for the parent process. |
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.
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.
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.
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.
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.
Requirement | Value |
---|---|
Minimum supported client |
Windows XP [desktop apps only] |
Minimum supported server |
Windows Server 2003 [desktop apps only] |
DLL |
Ntdll.dll |
This function is documented in Windows SDK.
Handle to process opened with PROCESS_QUERY_INFORMATION
access.
See PROCESS_INFORMATION_CLASS
.
Buffer for results.
Length of buffer. See PROCESS_INFORMATION_CLASS
for additional information.
Number of bytes needed, if ProcessInformationLength
was too small.
NtCreateProcess
NtOpenProcess
NtSetInformationProcess
PROCESS_INFORMATION_CLASS