IoAcquireRemoveLock macro (wdm.h)

The IoAcquireRemoveLock routine increments the count for a remove lock, indicating that the associated device object should not be detached from the device stack or deleted.


IoAcquireRemoveLock (
    _Inout_ PIO_REMOVE_LOCK RemoveLock,
    _In_opt_ PVOID          Tag


[in] RemoveLock

Pointer to an IO_REMOVE_LOCK structure that the caller initialized with a previous call to IoInitializeRemoveLock.

[in, optional] Tag

Optionally points to a caller-supplied tag that identifies this instance of acquiring the remove lock. For example, a driver Dispatch routine typically sets this parameter to a pointer to the IRP the routine is processing.

If a driver specifies a Tag on a call to IoAcquireRemoveLock, the driver must supply the same Tag in the corresponding call to IoReleaseRemoveLock.

The Tag does not have to be unique, but should be something meaningful during debugging.

Return value



The IoAcquireRemoveLock macro wraps and assumes the return value of IoAcquireRemoveLockEx, which returns NTSTATUS:

Return value Description
STATUS_SUCCESS Indicates the call was successful.
STATUS_DELETE_PENDING Error value indicating the driver has received an IRP_MN_REMOVE_DEVICE for the device and has called IoReleaseRemoveLockandWait. That routine is waiting for all remove locks to clear before returning control to the driver.

If the routine returns any value besides STATUS_SUCCESS, do not start any new operations on the device.

A driver must initialize a remove lock with a call to IoInitializeRemoveLock before using the lock.

A driver must call IoReleaseRemoveLock to release the lock when it is no longer needed.

For more information, see Using Remove Locks.


Requirement Value
Target Platform Desktop
Header wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Library NtosKrnl.lib
DLL NtosKrnl.exe
DDI compliance rules CompleteRequestStatusCheck(wdm), MarkDevicePower(wdm), MarkPower(wdm), MarkPowerDown(wdm), MarkQueryRelations(wdm), MarkStartDevice(wdm), MultRemoveLock(wdm), NsRemoveLockMnRemove(wdm), NsRemoveLockMnSurpriseRemove(wdm), NsRemoveLockQueryMnRemove(wdm), PowerDownAllocate(wdm), PowerDownFail(wdm), PowerUpFail(wdm), RemoveLock(wdm), RemoveLockCheck(wdm), RemoveLockForward(wdm), RemoveLockForward2(wdm), RemoveLockForwardDeviceControl(wdm), RemoveLockForwardDeviceControl2(wdm), RemoveLockForwardDeviceControlInternal(wdm), RemoveLockForwardDeviceControlInternal2(wdm), RemoveLockForwardRead(wdm), RemoveLockForwardRead2(wdm), RemoveLockForwardWrite(wdm), RemoveLockForwardWrite2(wdm), RemoveLockMnRemove(wdm), RemoveLockMnRemove2(wdm), RemoveLockMnSurpriseRemove(wdm), RemoveLockQueryMnRemove(wdm), RemoveLockRelease2(wdm), RemoveLockReleaseCleanup(wdm), RemoveLockReleaseClose(wdm), RemoveLockReleaseCreate(wdm), RemoveLockReleaseDeviceControl(wdm), RemoveLockReleaseInternalDeviceControl(wdm), RemoveLockReleasePnp(wdm), RemoveLockReleasePower(wdm), RemoveLockReleaseRead(wdm), RemoveLockReleaseShutdown(wdm), RemoveLockReleaseSystemControl(wdm), RemoveLockReleaseWrite(wdm), WmiForward(wdm)

See also