NAME

brk, sbrk - change space allocation (LEGACY)

 SYNOPSIS

#include <unistd.h>

int brk(void *addr);
void *sbrk(intptr_t incr);

 DESCRIPTION

The brk() and sbrk() functions are used to change the amount of space allocated for the calling process. The change is made by resetting the process' break value and allocating the appropriate amount of space. The amount of allocated space increases as the break value increases. The newly-allocated space is set to 0. However, if the application first decrements and then increments the break value, the contents of the reallocated space are unspecified.

The brk() function sets the break value to addr and changes the allocated space accordingly.

The sbrk() function adds incr bytes to the break value and changes the allocated space accordingly. If incr is negative, the amount of allocated space is decreased by incr bytes. The current value of the program break is returned by sbrk(0).

The behaviour of brk() and sbrk() is unspecified if an application also uses any other memory functions (such as malloc(), mmap(), free()). Other functions may use these other memory functions silently.

It is unspecified whether the pointer returned by sbrk() is aligned suitably for any purpose.

These interfaces need not be reentrant.

 RETURN VALUE

Upon successful completion, brk() returns 0. Otherwise, it returns -1 and sets errno to indicate the error.

Upon successful completion, sbrk() returns the prior break value. Otherwise, it returns (void *)-1 and sets errno to indicate the error.

 ERRORS

The brk() and sbrk() functions will fail if:

[ENOMEM]

The requested change would allocate more space than allowed.

The brk() and sbrk() functions may fail if:

[EAGAIN]

The total amount of system memory available for allocation to this process is temporarily insufficient. This may occur even though the space requested was less than the maximum data segment size.

[ENOMEM]

The requested change would be impossible as there is insufficient swap space available, or would cause a memory allocation conflict.

 EXAMPLES

None.

 APPLICATION USAGE

The brk() and sbrk() functions have been used in specialised cases where no other memory allocation function provided the same capability. The use of malloc() is now preferred because it can be used portably with all other memory allocation functions and with any function that uses other allocation functions.

 FUTURE DIRECTIONS

None.

 SEE ALSO

exec, malloc(), mmap(), <unistd.h>.