7.3 brk Function

Set the end of the process’s data space.

Attention: This interface function is not implemented by MPLAB XC8 C compilers.

Attention: This interface function is deprecated when using MPLAB XC32.

Include

None

Prototype

int brk(void * endds);

Argument

endds: pointer to the end of the data segment

Return Value

Returns 0 if successful; otherwise, returns -1.

Remarks

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

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

The brk() function 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 runtime environments where the stack grows downward and the heap grows upward.

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

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

When using MPLAB XC16 or XC-DSC, 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