ZwDuplicateObject function (ntifs.h)

The ZwDuplicateObject routine creates a handle that is a duplicate of the specified source handle.

Syntax

NTSYSAPI NTSTATUS ZwDuplicateObject(
  [in]            HANDLE      SourceProcessHandle,
  [in]            HANDLE      SourceHandle,
  [in, optional]  HANDLE      TargetProcessHandle,
  [out, optional] PHANDLE     TargetHandle,
  [in]            ACCESS_MASK DesiredAccess,
  [in]            ULONG       HandleAttributes,
  [in]            ULONG       Options
);

Parameters

[in] SourceProcessHandle

A handle to the source process for the handle being duplicated.

[in] SourceHandle

The handle to duplicate.

[in, optional] TargetProcessHandle

A handle to the target process that is to receive the new handle. This parameter is optional and can be specified as NULL if the DUPLICATE_CLOSE_SOURCE flag is set in Options.

[out, optional] TargetHandle

A pointer to a HANDLE variable into which the routine writes the new duplicated handle. The duplicated handle is valid in the specified target process. This parameter is optional and can be specified as NULL if no duplicate handle is to be created.

[in] DesiredAccess

An ACCESS_MASK value that specifies the desired access for the new handle.

[in] HandleAttributes

A ULONG that specifies the desired attributes for the new handle. For more information about attributes, see the description of the Attributes member in OBJECT_ATTRIBUTES.

[in] Options

A set of flags to control the behavior of the duplication operation. Set this parameter to zero or to the bitwise OR of one or more of the following flags.

Return value

ZwDuplicateObject returns STATUS_SUCCESS if the call is successful. Otherwise, it returns an appropriate error status code.

Remarks

The source handle is evaluated in the context of the specified source process. The calling process must have PROCESS_DUP_HANDLE access to the source process. The duplicate handle is created in the handle table of the specified target process. The calling process must have PROCESS_DUP_HANDLE access to the target process.

By default, the duplicate handle is created with the attributes specified by the HandleAttributes parameter, and with the access rights specified by the DesiredAccess parameter. If necessary, the caller can override one or both defaults by setting the DUPLICATE_SAME_ATTRIBUTES and DUPLICATE_SAME_ACCESS flags in the Options parameter.

If the call to this function occurs in user mode, you should use the name "NtDuplicateObject" instead of "ZwDuplicateObject".

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

See also

ACCESS_MASK

OBJECT_ATTRIBUTES

Using Nt and Zw Versions of the Native System Services Routines