NtFreeVirtualMemory - NtDoc
Native API online documentation, based on the System Informer
(formerly Process Hacker) phnt
headers
#ifndef _NTMMAPI_H
//
// Virtual memory
//
#if (PHNT_MODE != PHNT_MODE_KERNEL)
/**
* The NtFreeVirtualMemory routine frees virtual memory allocated for a process.
*
* \param ProcessHandle A handle to the process whose virtual memory is to be freed.
* \param BaseAddress A pointer to the base address of the region of pages to be freed.
* \param RegionSize A pointer to a variable that specifies the size of the region of memory to be freed.
* \param FreeType The type of free operation. This parameter can be MEM_DECOMMIT or MEM_RELEASE.
* \return NTSTATUS Successful or errant status.
*/
NTSYSCALLAPI
NTSTATUS
NTAPI
NtFreeVirtualMemory(
_In_ HANDLE ProcessHandle,
_Inout_ __drv_freesMem(Mem) PVOID *BaseAddress,
_Inout_ PSIZE_T RegionSize,
_In_ ULONG FreeType
);
View code on GitHub#ifndef _NTZWAPI_H
NTSYSCALLAPI
NTSTATUS
NTAPI
ZwFreeVirtualMemory(
_In_ HANDLE ProcessHandle,
_Inout_ __drv_freesMem(Mem) PVOID *BaseAddress,
_Inout_ PSIZE_T RegionSize,
_In_ ULONG FreeType
);
View code on GitHub// ntifs.h
__kernel_entry NTSYSCALLAPI NTSTATUS NtFreeVirtualMemory(
[in] HANDLE ProcessHandle,
[in, out] PVOID *BaseAddress,
[in, out] PSIZE_T RegionSize,
[in] ULONG FreeType
);
View the official Windows Driver Kit DDI reference// ntifs.h
NTSYSAPI NTSTATUS ZwFreeVirtualMemory(
[in] HANDLE ProcessHandle,
[in, out] PVOID *BaseAddress,
[in, out] PSIZE_T RegionSize,
[in] ULONG FreeType
);
View the official Windows Driver Kit DDI referenceNo description available.
The NtFreeVirtualMemory routine releases, decommits, or both releases and decommits, a region of pages within the virtual address space of a specified process.
ProcessHandle [in]A handle for the process in whose context the pages to be freed reside. Use the NtCurrentProcess macro, defined in Ntddk.h, to specify the current process.
BaseAddress [in, out]A pointer to a variable that will receive the base virtual address of the freed region of pages.
If the MEM_RELEASE flag is set in the FreeType parameter, *BaseAddress must be the base address returned by NtAllocateVirtualMemory when the region was reserved.
RegionSize [in, out]A pointer to a variable that will receive the actual size, in bytes, of the freed region of pages. The routine rounds the initial value of this variable up to the next host page size boundary and writes the rounded value back to this variable.
If the MEM_RELEASE flag is set in *FreeType, *RegionSize must be zero. NtFreeVirtualMemory frees the entire region that was reserved in the initial allocation call to NtAllocateVirtualMemory.
If the MEM_DECOMMIT flag is set in *FreeType, NtFreeVirtualMemory decommits all memory pages that contain one or more bytes in the range from *BaseAddress to (*BaseAddress + *RegionSize). This means, for example, that if a two-byte region of memory straddles a page boundary, both pages are decommitted.
NtFreeVirtualMemory decommits the entire region that was reserved by NtAllocateVirtualMemory. If the following three conditions are met, the entire region enters the reserved state:
FreeType [in]A bitmask containing flags that describe the type of free operation that NtFreeVirtualMemory will perform for the specified region of pages. The possible values are listed in the following table.
| Flag | Meaning |
|---|---|
| MEM_DECOMMIT | NtFreeVirtualMemory will decommit the specified region of pages. The pages enter the reserved state. NtFreeVirtualMemory doesn't fail if you attempt to decommit an uncommitted page. This means that you can decommit a range of pages without first determining their current commitment state. |
| MEM_RELEASE | NtFreeVirtualMemory will release the specified region of pages. The pages enter the free state. If you specify this flag, RegionSize must be zero, and BaseAddress must point to the base address returned by NtAllocateVirtualMemory when the region was reserved. NtFreeVirtualMemory fails if either of these conditions is not met. If any pages in the region are currently committed, NtFreeVirtualMemory first decommits and then releases them. NtFreeVirtualMemory doesn't fail if you attempt to release pages that are in different states, some reserved and some committed. This means that you can release a range of pages without first determining their current commitment state. |
NtFreeVirtualMemory returns either STATUS_SUCCESS or an error status code. Possible error status codes include the following.
| Return code | Description |
|---|---|
| STATUS_ACCESS_DENIED | A process has requested access to an object, but has not been granted those access rights. |
| STATUS_INVALID_HANDLE | An invalid ProcessHandle value was specified. |
| STATUS_OBJECT_TYPE_MISMATCH | There is a mismatch between the type of object required by the requested operation and the type of object that is specified in the request. |
Each page in the process's virtual address space is in one of the three states described in the following table.
| State | Meaning |
|---|---|
| FREE | The page is neither committed nor reserved. The page is not accessible to the process. Attempting to read from or write to a free page results in an access violation exception. You can use NtFreeVirtualMemory to put reserved or committed pages into the free state. |
| RESERVED | The page is reserved. The range of addresses cannot be used by other allocation functions. The page is not accessible to the process and has no physical storage associated with it. Attempting to read from or write to a reserved page results in an access violation exception. You can use NtFreeVirtualMemory to put committed memory pages into the reserved state, and to put reserved memory pages into the free state. |
| COMMITTED | The page is committed. Physical storage in memory or in the paging file on disk is allocated for the page, and access is controlled by a protection code. The system initializes and loads each committed page into physical memory only at the first attempt to read from or write to that page. When a process terminates, the system releases all storage for committed pages. You can use NtAllocateVirtualMemory to put committed memory pages into either the reserved or free state. |
NtFreeVirtualMemory can perform the following operations:
NtFreeVirtualMemory can decommit a range of pages that are in different states, some committed and some uncommitted. This means that you can decommit a range of pages without first determining the current commitment state of each page. Decommitting a page releases its physical storage, either in memory or in the paging file on disk.
If a page is decommitted but not released, its state changes to reserved. You can subsequently call NtAllocateVirtualMemory to commit it, or NtFreeVirtualMemory to release it. Attempting to read from or write to a reserved page results in an access violation exception.
NtFreeVirtualMemory can release a range of pages that are in different states, some reserved and some committed. This means that you can release a range of pages without first determining the current commitment state of each page. The entire range of pages originally reserved by NtAllocateVirtualMemory must be released at the same time.
If a page is released, its state changes to free, and it is available for subsequent allocation operations. After memory has been released or decommitted, you can never refer to the memory again. Any information that may have been in that memory is gone forever. Attempting to read from or write to a free page results in an access violation exception. If you require information, do not decommit or free memory that contains that information.
For more information about memory management support for kernel-mode drivers, see Memory Management for Windows Drivers.
[!NOTE] If the call to the NtFreeVirtualMemory function occurs in user mode, you should use the name "NtFreeVirtualMemory" instead of "ZwFreeVirtualMemory".
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 ZwFreeVirtualMemory routine releases, decommits, or both, a region of pages within the virtual address space of a specified process.
ProcessHandle [in]A handle for the process in whose context the pages to be freed reside. Use the NtCurrentProcess macro, defined in Ntddk.h, to specify the current process.
BaseAddress [in, out]A pointer to a variable that will receive the virtual address of the freed region of pages.
If the MEM_RELEASE flag is set in the FreeType parameter, BaseAddress must be the base address returned by ZwAllocateVirtualMemory when the region was reserved.
RegionSize [in, out]A pointer to a variable that will receive the actual size, in bytes, of the freed region of pages. The routine rounds the initial value of this variable up to the next host page size boundary and writes the rounded value back to this variable.
If the MEM_RELEASE flag is set in the FreeType parameter, the variable pointed to by RegionSize must be zero. ZwFreeVirtualMemory frees the entire region that was reserved in the initial allocation call to ZwAllocateVirtualMemory.
If the MEM_DECOMMIT flag is set in the FreeType parameter, ZwFreeVirtualMemory decommits all memory pages that contain one or more bytes in the range from the BaseAddress parameter to (BaseAddress + RegionSize). This means, for example, that if a two-byte region of memory straddles a page boundary, both pages are decommitted.
ZwFreeVirtualMemory decommits the entire region that was reserved by ZwAllocateVirtualMemory. If the following three conditions are met, the entire region enters the reserved state:
FreeType [in]A bitmask that contains flags that describe the type of free operation that ZwFreeVirtualMemory will perform for the specified region of pages. Possible values are the following:
ZwFreeVirtualMemory will decommit the specified region of pages. The pages enter the reserved state.
ZwFreeVirtualMemory does not fail if you attempt to decommit an uncommitted page. This means that you can decommit a range of pages without first determining their current commitment state.
ZwFreeVirtualMemory will release the specified region of pages. The pages enter the free state.
If you specify this flag, The variable that RegionSize points to must be zero, and BaseAddress must point to the base address returned by ZwAllocateVirtualMemory when the region was reserved. ZwFreeVirtualMemory fails if either of these conditions is not met.
If any pages in the region are currently committed, ZwFreeVirtualMemory first decommits and then releases them.
ZwFreeVirtualMemory does not fail if you attempt to release pages that are in different states, some reserved and some committed. This means that you can release a range of pages without first determining their current commitment state.
ZwFreeVirtualMemory returns either STATUS_SUCCESS or an error status code. Possible error status codes include the following.
| Return code | Description |
|---|---|
| STATUS_ACCESS_DENIED | A process has requested access to an object, but has not been granted those access rights. |
| STATUS_INVALID_HANDLE | An invalid ProcessHandle value was specified. |
| STATUS_OBJECT_TYPE_MISMATCH | There is a mismatch between the type of object required by the requested operation and the type of object that is specified in the request. |
Each page in the process's virtual address space is in one of the three states described as follows.
State is FREE
The page is neither committed nor reserved. The page is not accessible to the process. Attempting to read from or write to a free page results in an access violation exception.
You can use ZwFreeVirtualMemory to put reserved or committed pages into the free state.
State is RESERVED
The page is reserved. The range of addresses cannot be used by other allocation functions. The page is not accessible to the process and has no physical storage associated with it. Attempting to read from or write to a reserved page results in an access violation exception.
You can use ZwFreeVirtualMemory to put committed memory pages into the reserved state, and to put reserved memory pages into the free state.
State is COMMITTED
The page is committed. Physical storage in memory or in the paging file on disk is allocated for the page, and access is controlled by a protection code.
The system initializes and loads each committed page into physical memory only at the first attempt to read from or write to that page.
When a process terminates, the system releases all storage for committed pages.
You can use ZwAllocateVirtualMemory to put committed memory pages into either the reserved or free state.
ZwFreeVirtualMemory can perform the following operations:
ZwFreeVirtualMemory can decommit a range of pages that are in different states, some committed and some uncommitted. This means that you can decommit a range of pages without first determining the current commitment state of each page. Decommitting a page releases its physical storage, either in memory or in the paging file on disk.
If a page is decommitted but not released, its state changes to reserved. You can subsequently call ZwFreeVirtualMemory to commit it, or ZwFreeVirtualMemory to release it. Attempting to read from or write to a reserved page results in an access violation exception.
ZwFreeVirtualMemory can release a range of pages that are in different states, some reserved and some committed. This means that you can release a range of pages without first determining the current commitment state of each page. The entire range of pages originally reserved by ZwAllocateVirtualMemory must be released at the same time.
If a page is released, its state changes to free, and it is available for subsequent allocation operations. After memory has been released or decommitted, you can never refer to the memory again. Any information that may have been in that memory is gone forever. Attempting to read from or write to a free page results in an access violation exception. If you require information, do not decommit or free memory that contains that information.
For more information about memory management support for kernel-mode drivers, see Memory Management for Windows Drivers.
[!NOTE] If the call to the ZwFreeVirtualMemory function occurs in user mode, you should use the name "NtFreeVirtualMemory" instead of "ZwFreeVirtualMemory".
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.
This function is documented in Windows Driver Kit here and here.
If you put pointer to NULL value as RegionSize, system will free all region, and put size of it in result.
Can be one of the values: MEM_DECOMMIT, or MEM_RELEASE.