# OS_AllocFromHeap

## C Specification

      #include <nitro/os.h>

      void* OS_AllocFromHeap(
                      OSArenaId       id ,
                      OSHeapHandle    heap ,
                      u32             size );

      void* OS_AllocFromMain( u32 size );
      void* OS_AllocFromITCM( u32 size );
      void* OS_AllocFromDTCM( u32 size );
      void* OS_AllocFromShared( u32 size );
      void* OS_AllocFromWram( u32 size );
      void* OS_AllocFromMainEx( u32 size );

      void* OS_Alloc( u32 size );

## Description

Allocates a memory block from a heap

In `OS_AllocFromHeap`, you must specify the handle of the allocating heap and the arena ID of the arena that is associated with that heap. The arena is specified with an arena ID, `id`.
For more information, see `OS_InitArena`.

If `OS_CURRENT_HEAP_HANDLE` is specified as the heap handle, it will be assumed that the arena's current heap is being specified.

`OS_AllocFromMain` is the inline function for `OS_AllocFromHeap( OS_ARENA_MAIN, OS_CURRENT_HEAP_HANDLE, ... )`.
`OS_AllocFromICTM` is the inline function for `OS_AllocFromHeap( OS_ARENA_ITCM, OS_CURRENT_HEAP_HANDLE, ... )`.
`OS_AllocFromDTCM` is the inline function for `OS_AllocFromHeap( OS_ARENA_DTCM, OS_CURRENT_HEAP_HANDLE, ... )`.
`OS_AllocFromShared` is the inline function for `OS_AllocFromHeap( OS_ARENA_SHARED, OS_CURRENT_HEAP_HANDLE, ... )`.
`OS_AllocFromWram` is the inline function for `OS_AllocFromHeap( OS_ARENA_WRAM, OS_CURRENT_HEAP_HANDLE, ... )`.
`OS_AllocFromMainEx` is the inline function for `OS_AllocFromHeap( OS_ARENA_MAINEX, OS_CURRENT_HEAP_HANDLE, ... )`.

`OS_Alloc` is the inline of `OS_AllocFromHeap( OS_ARENA_MAIN, OS_CURRENT_HEAP_HANDLE, ... )`.

For ARM9, `OS_Alloc` is the inline of `OS_AllocFromHeap( OS_ARENA_MAIN, OS_CURRENT_HEAP_HANDLE, ... );`
For ARM7, `OS_Alloc` is the inline of `OS_AllocFromHeap( OS_ARENA_MAIN_SUBPRIV, OS_CURRENT_HEAP_HANDLE, ... )`.

## Caution

When try to allocate a `0`–byte region, `DEBUG` build stops at `ASSERT`. In other builds, the operation is indefinite.

## Arguments

`id` | Arena ID of the arena associated with the heap from which a region will be reserved
`heap` | Handle of the heap from which a region will be reserved
`size` | Size of the region you want to reserve (bytes)

## Return Values

If a region was allocated, the region's start address is returned.
If it was not possible to allocate a region, `NULL` is returned.

## See Also

`OS_InitArena, OS_InitAlloc, OS_CreateHeap, OS_FreeToHeap, OS_FreeAllToHeap`

## Revision History

07/07/2004 Added caution regarding 0&ndashbyte regions
03/08/2004 Added difference in behavior when called in ARM7 and ARM9
02/25/2004 Changed the number of arenas from 6 to 9
01/06/2004 Initial Version