# OS_CreateHeap

## Syntax

      #include <nitro/os.h>

      OSHeapHandle OS_CreateHeap( OSArenaId id, void* start, void* end );

## Arguments

`id` | Arena ID of an arena in which you are going to create a heap
`start` | Starting address of heap region
`end` | Ending address of address of heap region (+1)

## Return Values

In the case that it was possible to create a heap, the handle to the heap will be returned. In the case that it was not possible to create a heap, -1 is returned.

## Description

Creates a heap in the specified arena.

The arena is specified with the arena ID (`id`). To read more about this value, see the `OS_InitArena` function. The arena must have memory allocated with the `OS_InitAlloc` function and then be initialized in advance. The region for the heap is from `start` to `end`. The `end` address is +1 from the actual end position.

> `OS_CreateHeap( OS_ARENA_MAIN, (void*)0x2030000, (void*)0x2040000 );`

In this example, the `0x10000` bytes from `0x2030000` to `0x203FFFF` are used as the heap region.

Call the `OS_DestroyHeap` function to destroy created heaps.

Call the `OS_ClearHeap` function to reinitialize a heap.

## See Also

`OS_InitArena`
`OS_InitAlloc`
`OS_DestroyHeap`
`OS_ClearHeap`

## Revision History

2004/01/06 Initial version.

CONFIDENTIAL