# OS_Alloc[From*]

## Syntax

      #include <nitro/os.h>

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

      void* OS_AllocFromMain( u32 size );
      void* OS_AllocFromSubPriv( u32 size );
      void* OS_AllocFromMainEx( u32 size );
      void* OS_AllocFromITCM( u32 size );
      void* OS_AllocFromDTCM( u32 size );
      void* OS_AllocFromShared( u32 size );
      void* OS_AllocFromWramMain( u32 size );
      void* OS_AllocFromWramSub( u32 size );
      void* OS_AllocFromSubPrivWram( u32 size );

      void* OS_Alloc( u32 size );

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

## 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 the arena ID (id). To read more about this value, 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.

The secure memory domain is aligned at 32 bytes.

`OS_AllocFromMain` is the inline function for `OS_AllocFromHeap( OS_ARENA_MAIN, OS_CURRENT_HEAP_HANDLE, ...` .

`OS_AllocFromSubPriv` is the inline function for `OS_AllocFromHeap( OS_ARENA_MAIN_SUBPRIV, OS_CURRENT_HEAP_HANDLE, ... )`.

`OS_AllocFromMainEx` is the inline function for `OS_AllocFromHeap( OS_ARENA_MAINEX, 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_AllocFromWramMain` is the inline function for `OS_AllocFromHeap( OS_ARENA_WRAM_MAIN, OS_CURRENT_HEAP_HANDLE, ... )`.

`OS_AllocFromWramSub` is the inline function for `OS_AllocFromHeap( OS_ARENA_WRAM_SUB, OS_CURRENT_HEAP_HANDLE, ... )`.

`OS_AllocFromSubPrivWram` is the inline function for `OS_AllocFromHeap( OS_ARENA_WRAM_SUBPRIV, OS_CURRENT_HEAP_HANDLE, ... )`.

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

Caution: When trying to allocate a 0–byte region, DEBUG builds stop at `ASSERT`. In other builds, the operation is undefined.

In the case of a DEBUG build, build stops on an assert if an attempt is made to allocate memory for a heap destroyed using the `OS_DestroyHeap` function. Returns `NULL` in the case of RELEASE and FINALROM builds.

## See Also

`OS_InitArena`
`OS_InitAlloc`
`OS_CreateHeap`
`OS_FreeToHeap`
`OS_FreeAllToHeap`

## Revision History

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

CONFIDENTIAL