NtOpenProcess function

04/30/2018
2 minutes to read

The ZwOpenProcess routine opens a handle to a process object and sets the access rights to this object.

Syntax

__kernel_entry NTSYSCALLAPI NTSTATUS NtOpenProcess(
  PHANDLE            ProcessHandle,
  ACCESS_MASK        DesiredAccess,
  POBJECT_ATTRIBUTES ObjectAttributes,
  PCLIENT_ID         ClientId
);

Parameters

ProcessHandle

A pointer to a variable of type HANDLE. The ZwOpenProcess routine writes the process handle to the variable that this parameter points to.

DesiredAccess

An ACCESS_MASK value that contains the access rights that the caller has requested to the process object.

ObjectAttributes

A pointer to an OBJECT_ATTRIBUTES structure that specifies the attributes to apply to the process object handle. In Windows Vista and later versions of Windows, the ObjectName field of this structure must be set to NULL. In Windows Server 2003, Windows XP, and Windows 2000, this field can, as an option, point to an object name. For more information, see the following Remarks section.

ClientId

A pointer to a client ID that identifies the thread whose process is to be opened. In Windows Vista and later versions of Windows, this parameter must be a non-NULL pointer to a valid client ID. In Windows Server 2003, Windows XP, and Windows 2000, this parameter is optional and can be set to NULL if the OBJECT_ATTRIBUTES structure that ObjectAttributes points to specifies an object name. For more information, see the following Remarks section.

Return value

ZwOpenProcess returns STATUS_SUCCESS if the call is successful. Possible return values include the following error status codes.

Return code	Description
STATUS_INVALID_PARAMETER_MIX	In Windows Vista and later versions of Windows, the caller either supplied an object name or failed to supply a client ID. In Windows Server 2003, Windows XP, and Windows 2000, the caller supplied both an object name and a client ID.
STATUS_INVALID_CID	The specified client ID is not valid.
STATUS_INVALID_PARAMETER	The requested access rights are not valid for a process object.
STATUS_ACCESS_DENIED	The requested access rights cannot be granted.

Remarks

In Windows Vista and later versions of Windows, the ClientId parameter must point to a client ID that identifies the thread whose process is to be opened. In addition, the ObjectName field of the structure pointed to by ObjectAttributes must be set to NULL.

In Windows Server 2003, Windows XP, and Windows 2000, the caller has the option of supplying either a client ID or an object name (but not both). If the ObjectName field of the structure pointed to by ObjectAttributes contains a non-NULL pointer to an object name, ClientId must be NULL.

Note If the call to this function occurs in user mode, you should use the name "NtOpenProcess" instead of "ZwOpenProcess".

For calls from kernel-mode drivers, the NtXxx and ZwXxx 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 NtXxx and ZwXxx versions of a routine, see Using Nt and Zw Versions of the Native System Services Routines.

Requirements


Minimum supported client	Available in Windows 2000 and later versions of Windows.
Target Platform	Universal
Header	ntddk.h (include Ntddk.h, Ntifs.h)
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI compliance rules	PowerIrpDDis, HwStorPortProhibitedDDIs