|
|
|
The ZwClose routine closes object handles.
NTSTATUS
ZwClose(
IN HANDLE Handle
);
ZwClose returns STATUS_SUCCESS on success, or the appropriate error code on failure. In particular, it returns STATUS_INVALID_HANDLE if Handle is not a valid handle and STATUS_HANDLE_NOT_CLOSABLE if the calling thread has insufficient privilege to close the handle.
Declared in wdm.h and ntddk.h. Include wdm.h or ntddk.h.
ZwClose is a generic routine that operates on any type of object.
Closing an open handle for an object causes that handle to become invalid. The reference count for the object handle is decremented and object retention checks are performed.
A named object is not actually deleted until all of its valid handles are closed and no referenced pointers remain.
Drivers must close every handle they open once the handle is no longer required. Kernel handles, which are handles opened from a system thread or with the OBJ_KERNEL_HANDLE flag specified, can only be closed when the previous processor mode is KernelMode (see ExGetPreviousMode). This is true for a system thread, or while inside a dispatch routine for an IRP issued from kernel-mode.
For example, a handle returned by ZwCreateKey to a DriverEntry routine, which executes in a system process, cannot be subsequently used by the same driver's dispatch routines, which usually execute either in the context of the thread issuing the current I/O request or, for lower-level drivers, in an arbitrary thread context.
A nonkernel handle can only be closed when either the previous processor mode is KernelMode or from any thread that has sufficient permission to close it, such as the thread that created it.
If the caller is not permitted to close the handle, ZwClose returns STATUS_HANDLE_NOT_CLOSABLE.
Callers of ZwClose must be running at IRQL = PASSIVE_LEVEL.
ZwCreateDirectoryObject, ZwCreateFile, ZwCreateKey, ZwOpenKey, ZwOpenSection