# OS_FreeToHeap

## C Specification

      #include <nitro/os.h>

      void OS_FreeToHeap( OSArenaId id, OSHeapHandle heap, void* ptr );

      void OS_FreeToMain( void* ptr );
      void OS_FreeToSubPriv( void* ptr );
      void OS_FreeToMainEx( void* ptr );
      void OS_FreeToITCM( void* ptr );
      void OS_FreeToDTCM( void* ptr );
      void OS_FreeToShared( void* ptr );
      void OS_FreeToWramMain( void* ptr );
      void OS_FreeToWramSub( void* ptr );
      void OS_FreeToSubPrivWram( void* ptr );

      void OS_Free( void* ptr );

## Arguments

id | Arena ID of the arena that is associated with the heap for which a memory block is to be freed
heap | Handle of the heap for which a memory block is to be freed
ptr | Pointer to the memory block that is to be freed

## Return Values

None.

## Description

This function frees a memory block `ptr` and returns the memory block `ptr` to the heap.

You must specify an arena that has a heap. The arena is specified with the arena ID (id). To read more about this value, see `OS_InitArena()`.

Specifying OS_CURRENT_HEAP_HANDLE for heap is treated the same as if the arena's current heap had been specified.

`OS_FreeToMain` is the inline function for `OS_FreeToHeap( OS_ARENA_MAIN, OS_CURRENT_HEAP_HANDLE, ...``OS_FreeToSubPriv` is the inline function for `OS_FreeToHeap( OS_ARENA_MAIN_SUBPRIV, OS_CURRENT_HEAP_HANDLE, ...``OS_FreeToMainEx` is the inline function for `OS_FreeToHeap( OS_ARENA_MAINEX, OS_CURRENT_HEAP_HANDLE, ...``OS_FreeToICTM` is the inline function for `OS_FreeToHeap( OS_ARENA_ITCM, OS_CURRENT_HEAP_HANDLE, ...``OS_FreeToDTCM` is the inline function for `OS_FreeToHeap( OS_ARENA_DTCM, OS_CURRENT_HEAP_HANDLE, ...``OS_FreeToShared` is the inline function for `OS_FreeToHeap( OS_ARENA_SHARED, OS_CURRENT_HEAP_HANDLE, ...``OS_FreeToWramMain` is the inline function for `OS_FreeToHeap( OS_ARENA_WRAM, OS_CURRENT_HEAP_HANDLE, ...``OS_FreeToWramSub` is the inline function for `OS_ARENA_WRAM_SUB, OS_CURRENT_HEAP_HANDLE, ...``OS_FreeToSubPrivWram` is the inline function for `OS_FreeToHeap( OS_ARENA_WRAM_SUBPRIV, OS_CURRENT_HEAP_HANDLE, ...`

For ARM9, `OS_Free` is the inline for `OS_FreeToHeap( OS_ARENA_MAIN, OS_CURRENT_HEAP_HANDLE, ...` .
For ARM7, `OS_Free` is the inline version of `OS_FreeToHeap( OS_ARENA_MAIN_SUBPRIV, OS_CURRENT_HEA_HANDLE, ...`

Caution: When a value of NULL is specified for
ptr, the `DEBUG` build stops at `ASSERT`. In other builds, the behavior is uncertain and unpredictable.
However, in most cases a data abort exception will occur.

## See Also

`OS_InitArena`, `OS_AllocFromHeap`, `OS_FreeAllToHeap`

## Revision History

07/07/2004 Added caution when ptr is set to NULL
03/08/2004 Take into consideration the differences between ARM7 and ARM9
02/25/2004 Changed the number of arena from 6 to 9
01/06/2004 Initial version

CONFIDENTIAL