NtClose - NtDoc
Native API online documentation, based on the System Informer
(formerly Process Hacker) phnt
headers
#ifndef _NTOBAPI_H
//
// Objects, handles
//
#if (PHNT_MODE != PHNT_MODE_KERNEL)
/**
* The NtClose routine closes the specified handle.
*
* @param Handle The handle being closed.
* @return NTSTATUS Successful or errant status.
* @sa https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/wdm/nf-wdm-zwclose
*/
NTSYSCALLAPI
NTSTATUS
NTAPI
NtClose(
_In_ _Post_ptr_invalid_ HANDLE Handle
);
View code on GitHub#ifndef _NTZWAPI_H
NTSYSCALLAPI
NTSTATUS
NTAPI
ZwClose(
_In_ _Post_ptr_invalid_ HANDLE Handle
);
View code on GitHub// ntifs.h
__kernel_entry NTSYSCALLAPI NTSTATUS NtClose(
[in] HANDLE Handle
);
View the official Windows Driver Kit DDI reference// wdm.h
NTSYSAPI NTSTATUS ZwClose(
[in] HANDLE Handle
);
View the official Windows Driver Kit DDI reference// winternl.h
__kernel_entry NTSTATUS NtClose(
[in] HANDLE Handle
);
View the official Win32 API referenceCloses the specified kernel handle. This function is documented in Windows Driver Kit here and here.
Handle - a handle to a kernel object.STATUS_INVALID_HANDLE - an invalid handle value was specified.STATUS_HANDLE_NOT_CLOSABLE - the provided handle is marked as protected from closing. See OBJ_PROTECT_CLOSE for more details.NtClose is one the few Native API functions that can raise exceptions instead of returning an error status code. See the exploit protection reference for a description of the mitigation that causes this behavior.
The NtClose routine closes an object handle.
Handle [in]Handle to an object of any type.
NtClose returns STATUS_SUCCESS on success, or the appropriate NTSTATUS error code such as the following.
| Return code | Meaning |
|---|---|
| STATUS_INVALID_HANDLE | Handle is not a valid handle. |
| STATUS_HANDLE_NOT_CLOSABLE | The calling thread doesn't have permission to close the handle; that is, the specified object handle is protected from closing from any instance attempts of NtClose. |
An example where the latter NTSTATUS code occurs is when a call of ZwDuplicateObject has been invoked with OBJ_PROTECT_CLOSE passed to the handle attributes parameter argument. The kernel ensures that the handle cannot be closed in that case.
NtClose is a generic routine that operates on any type of object.
Closing an open object handle causes that handle to become invalid. The system also decrements the handle count for the object and checks whether the object can be deleted. The system does not actually delete the object until all of the object's handles are closed and no referenced pointers remain.
A driver must close every handle that it opens as soon as the handle is no longer required. Kernel handles, which are those that are opened by a system thread or by specifying the OBJ_KERNEL_HANDLE flag, can be closed only when the previous processor mode is KernelMode. This requirement applies both to system threads and to dispatch routines for IRPs that were issued from kernel mode. (For more information about the previous processor mode, see ExGetPreviousMode.) For example, a handle that NtCreateKey returns to a DriverEntry routine cannot subsequently be closed by the same driver's dispatch routines. A DriverEntry routine runs in a system process, whereas dispatch routines usually run 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 be closed only if one of two conditions is met: The previous processor mode is KernelMode, or the calling thread has sufficient permission to close the handle. An example of the latter occurs when the calling thread is the one that created the handle.
Callers of NtClose should not assume that this routine automatically waits for all I/O to complete prior to returning.
If the call to this function occurs in user mode, you should use the name "NtClose" instead of "ZwClose".
For calls from kernel-mode drivers, the Nt*Xxx* and Zw*Xxx* 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 Nt*Xxx* and Zw*Xxx* versions of a routine, see Using Nt and Zw Versions of the Native System Services Routines.
The ZwClose routine closes an object handle.
Handle [in]Handle to an object of any type.
ZwClose returns STATUS_SUCCESS on success, or the appropriate NTSTATUS error code on failure. In particular, it returns STATUS_INVALID_HANDLE if Handle is not a valid handle, or STATUS_HANDLE_NOT_CLOSABLE if the calling thread does not have permission to close the handle.
ZwClose is a generic routine that operates on any type of object.
Closing an open object handle causes that handle to become invalid. The system also decrements the handle count for the object and checks whether the object can be deleted. The system does not actually delete the object until all of the object's handles are closed and no referenced pointers remain.
A driver must close every handle that it opens as soon as the handle is no longer required. Kernel handles, which are those that are opened by a system thread or by specifying the OBJ_KERNEL_HANDLE flag, can be closed only when the previous processor mode is KernelMode. This requirement applies both to system threads and to dispatch routines for IRPs that were issued from kernel mode. (For more information about the previous processor mode, see ExGetPreviousMode.) For example, a handle that ZwCreateKey returns to a DriverEntry routine cannot subsequently be closed by the same driver's dispatch routines. A DriverEntry routine runs in a system process, whereas dispatch routines usually run either in the context of the thread issuing the current I/O request, or, for lower-level drivers, in an arbitrary thread context.
A non-kernel handle can be closed only if one of two conditions is met: The previous processor mode is KernelMode, or the calling thread has sufficient permission to close the handle. An example of the latter occurs when the calling thread is the one that created the handle.
Callers of ZwClose should not assume that this routine automatically waits for all I/O to complete prior to returning.
If the call to this function occurs in user mode, you should use the name "NtClose" instead of "ZwClose".
For calls from kernel-mode drivers, the Nt*Xxx* and Zw*Xxx* 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 Nt*Xxx* and Zw*Xxx* versions of a routine, see Using Nt and Zw Versions of the Native System Services Routines.
Using Nt and Zw Versions of the Native System Services Routines
Deprecated. Closes the specified handle. NtClose is superseded by CloseHandle.
Handle [in]The handle being closed.
The various NTSTATUS values are defined in NTSTATUS.H, which is distributed with the Windows DDK.
| Return code | Description |
|---|---|
| STATUS_SUCCESS | The handle was closed. |
The NtClose function closes handles to the following objects.
Because there is no import library for this function, you must use GetProcAddress.