sbrk Function

Extend the process’ data space by a given increment.

Attention: This interface function is implemented only by MPLAB XC32 C compilers.

Include

None

Prototype

void * sbrk(int incr);

Argument

incr number of characters to increment/decrement

Return Value

Return the start of the new space allocated or -1 for errors.

Remarks

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

sbrk() adds incr characters to the break value and changes the allocated space accordingly. incr can be negative, in which case the amount of allocated space is decreased.

sbrk() 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.

Default Behavior

A static variable is used to point to the first free heap location. If adding incr number of bytes will exceed _eheap, sbrk() will return -1. Otherwise, the function updates the first free location on heap and return a pointer to latest allocated memory.

The linker allocates a block of memory for the heap if the -Wl,--heap=n option is specified, where n is the desired heap size in characters. The starting and ending addresses of the heap are reported in variables: _heap and _eheap, respectively, and which are declared:

extern 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().