# 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 );

## Description

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

The arena that is associated with the heap must be specified. The arena is specified by an arena ID, `id`. For information on this value see `OS_InitArena`.

When you specify `OS_CURRENT_HEAP_HANDLE` as the heap handle, the function assumes that the current heap that is associated with that arena has 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 for `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`. When `ptr` is set any value other than `NULL`. In other builds, the behavior is uncertain and unpredictable.
However, in most cases a data abort exception will occur.

## 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

## 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