# OS_CreateHeap

## C Specification

      #include <nitro/os.h>

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

## Description

This function creates a heap in the specified arena. The arena must have memory allocated with the `OS_InitAlloc` function and then be initialized in advance.

The arena is specified by an arena ID `id`. For information about this value see `OS_InitArena`. The region for the heap is from `start` to `end`. The `end` address is +1 from the actual end position.

For example, in the case of `OS_CreateHeap( OS_ARENA_MAIN, (void*)0x2030000, (void*)0x2040000 )`, the `0x10000` bytes of the `0x2030000 – 0x203FFFF` will be used as the heap region.

## Arguments

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

## Return Values

In the case that it was possible to create a heap, a value of 0 or greater will be returned, which is the handle to the heap.

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

## See Also

`OS_InitArena`, `OS_InitAlloc`

## Revision History

01/06/2004 Initial version