RtlAllocateHeap - NtDoc
Native API online documentation, based on the System Informer
(formerly Process Hacker) phnt
headers
#ifndef _NTRTL_H
/**
* The RtlAllocateHeap routine allocates a block of memory from a heap.
*
* \param HeapHandle Handle for a private heap from which the memory will be allocated.
* \param Flags Controllable aspects of heap allocation. Specifying any flags will override the corresponding value specified when the heap was created with RtlCreateHeap.
* \param Size Number of bytes to be allocated. If the heap, specified by the HeapHandle parameter, is a nongrowable heap, Size must be less than or equal to the heap's virtual memory threshold.
* \return If the call to RtlAllocateHeap succeeds, the return value is a pointer to the newly-allocated block. The return value is NULL if the allocation failed.
* \remarks https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/ntifs/nf-ntifs-rtlallocateheap
*/
_Success_(return != 0)
_Must_inspect_result_
_Ret_maybenull_
_Post_writable_byte_size_(Size)
__drv_allocatesMem(Mem)
NTSYSAPI
DECLSPEC_ALLOCATOR
DECLSPEC_NOALIAS
DECLSPEC_RESTRICT
PVOID
NTAPI
RtlAllocateHeap(
_In_ HANDLE HeapHandle,
_In_opt_ ULONG Flags,
_In_ SIZE_T Size
);
View code on GitHub// ntifs.h
NTSYSAPI PVOID RtlAllocateHeap(
[in] PVOID HeapHandle,
[in, optional] ULONG Flags,
[in] SIZE_T Size
);
View the official Windows Driver Kit DDI referenceNo description available.
The RtlAllocateHeap routine allocates a block of memory from a heap.
HeapHandle [in]Handle for a private heap from which the memory will be allocated. This parameter is a handle returned from a successful call to RtlCreateHeap .
Flags [in, optional]Controllable aspects of heap allocation. Specifying any of these values will override the corresponding value specified when the heap was created with RtlCreateHeap. This parameter can be one or more of the following values.
| Flag | Meaning |
|---|---|
| HEAP_GENERATE_EXCEPTIONS | The system will raise an exception to indicate a function failure, such as an out-of-memory condition, instead of returning NULL. |
| HEAP_NO_SERIALIZE | Mutual exclusion will not be used while RtlAllocateHeap is accessing the heap. |
| HEAP_ZERO_MEMORY | The allocated memory will be initialized to zero. Otherwise, the memory is not initialized to zero. |
Size [in]Number of bytes to be allocated. If the heap, specified by the HeapHandle parameter, is a nongrowable heap, Size must be less than or equal to the heap's virtual memory threshold. (For more information, see the VirtualMemoryThreshold member of the Parameters parameter to RtlCreateHeap.)
If the call to RtlAllocateHeap succeeds, the return value is a pointer to the newly-allocated block. The return value is NULL if the allocation failed.
RtlAllocateHeap allocates a block of memory of the specified size from the specified heap.
To free a block of memory allocated by RtlAllocateHeap, call RtlFreeHeap.
Memory allocated by RtlAllocateHeap is not movable. Since the memory is not movable, it is possible for the heap to become fragmented.
Serialization ensures mutual exclusion when two or more threads attempt to simultaneously allocate or free blocks from the same heap. There is a small performance cost to serialization, but it must be used whenever multiple threads allocate and free memory from the same heap. Setting the HEAP_NO_SERIALIZE value eliminates mutual exclusion on the heap. Without serialization, two or more threads that use the same heap handle might attempt to allocate or free memory simultaneously, likely causing corruption in the heap. The HEAP_NO_SERIALIZE value can, therefore, be safely used only in the following situations:
The process has only one thread.
The process has multiple threads, but only one thread calls the heap functions for a specific heap.
The process has multiple threads, and the application provides its own mechanism for mutual exclusion to a specific heap.
[!NOTE] To guard against an access violation, use structured exception handling to protect any code that writes to or reads from a heap. For more information about structured exception handling with memory accesses, see Handling Exceptions.
This function is documented in Windows Driver Kit.
Function maps Win32 API HeapCreate, see Ms SDK.