brk Function

Set the end of the process’s data space.

Include

None

Prototype

int brk(void * endds);

Argument

Return Value

Returns 0 if successful; otherwise, returns -1.

Remarks

This function is implemented as a stub that must be completed to suite the application.

This helper function is used by the Standard C Library function malloc().

brk() is used to dynamically change the amount of space allocated for the calling process’s data segment. The change is made by resetting the process’s break value and allocating the appropriate amount of space. The break value is the address of the first location beyond the end of the data segment. The amount of allocated space increases as the break value increases.

Newly allocated space is uninitialized.

Default Behavior

A static variable is used to point to the first free heap location. If the argument endds is zero, the function sets the variable to the address of the start of the heap and returns zero. If the argument endds is non-zero and has a value less than _eheap, the function sets the variable to the value of endds and returns zero. Otherwise, the variable is unchanged and the function returns -1.

The argument endds must be within the heap range (see data space memory map below).

Since the stack is located immediately above the heap, using brk() or sbrk() has little effect on the size of the dynamic memory pool. The brk() and sbrk() functions are primarily intended for use in run-time environments where the stack grows downward and the heap grows upward.

Copyextern uint8_t _heap;              // heap start
extern uint8_t _eheap;             // heap end

For MPLAB XC16, using the linker’s heap size option is the standard way of controlling heap size, rather than relying on brk() and sbrk().

Source File

brk.c