ObDereferenceObjectWithTag macro (wdm.h)

Article
03/16/2023

The ObDereferenceObjectWithTag routine decrements the reference count of the specified object, and writes a four-byte tag value to the object to support object reference tracing.

Syntax

void ObDereferenceObjectWithTag(
  [in]  a,
  [in]  t
);

Parameters

[in] a

A pointer to the object. The caller obtains this pointer either when it creates the object, or from a previous call to the ObReferenceObjectByHandleWithTag routine after it opens the object.

[in] t

Specifies a four-byte, custom tag value. For more information, see the following Remarks section.

Return value

None

Remarks

ObDereferenceObjectWithTag returns a value that is reserved for system use. Drivers must treat this value as VOID.

A kernel-mode driver calls this routine to decrement the reference count of an object by one. If the object was created as temporary (that is, the OBJ_PERMANENT flag was not specified when the object was created), and the reference count reaches zero, the object manager deletes the object.

When the reference count for an object reaches zero, a kernel-mode component can delete the object. However, a driver can delete only those objects that it created, and a driver should never attempt to delete any object that it did not create.

An object is permanent if it was created with the OBJ_PERMANENT object attribute flag specified. (For more information about object attributes, see InitializeObjectAttributes.) A permanent object is created with an initial reference count of one, so the object is not deleted when the driver removes its last reference to the object.

To prepare a permanent object to be deleted, a driver can call the ZwMakeTemporaryObject routine to make the object temporary. A driver should only delete a permanent object that it created. Use the following steps to delete a permanent object:

Call ObDereferenceObjectWithTag.
Get the handle to the object. If necessary, call the appropriate ZwOpenXxx or ZwCreateXxx routine to get the object handle.
Call ZwMakeTemporaryObject with the handle obtained in step 2.
Call ZwClose with the handle obtained in step 2.

If the immediate deletion of an object by the current thread might cause a deadlock, do not call ObDereferenceObjectWithTag to dereference the object. Instead, call the ObDereferenceObjectDeferDeleteWithTag routine to dereference the object.

For example, such a deadlock can occur if ObDereferenceObjectWithTag is used to dereference a Kernel Transaction Manager (KTM) object when a higher-level driver on the driver stack is holding a lock.

For more information about object references, see Life Cycle of an Object.

The ObDereferenceObject routine is similar to ObDereferenceObjectWithTag, except that it does not enable the caller to write a custom tag to an object. In Windows 7 and later versions of Windows, ObDereferenceObject always writes a default tag value ('tlfD') to the object. A call to ObDereferenceObject has the same effect as a call to ObDereferenceObjectWithTag that specifies Tag = 'tlfD'.

To view an object reference trace in the Windows debugging tools, use the !obtrace kernel-mode debugger extension. In Windows 7, the !obtrace extension is enhanced to display object reference tags, if object reference tracing is enabled. By default, object reference tracing is turned off. Use the Global Flags Editor (Gflags) to enable object reference tracing. For more information, see Object Reference Tracing with Tags.

Requirements

Requirement	Value
Minimum supported client	Available in Windows 7 and later versions of the Windows operating system.
Target Platform	Desktop
Header	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h, Fltkernel.h)
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL
DDI compliance rules	HwStorPortProhibitedDDIs(storport)