brk()

Change the amount of space allocated for the calling process's data segment

Synopsis:

#include <unistd.h>

int brk( void* endds );

Arguments:

endds

A pointer to the new end of the data segment.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

---

This function is in libc.a, but not in libc.so (in order to save space).

---

Description:

The brk() function is used to change dynamically the amount of space allocated for the calling process's data segment (see the exec* functions).

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 set to zero. If, however, the same memory space is reallocated to the same process, its contents are undefined.

When a program begins execution using execve(), the break is set at the highest location defined by the program and data storage areas.

You can call getrlimit() to determine the maximum permissible size of the data segment; it isn't possible to set the break beyond the rlim_max value returned from getrlimit(), i.e:

end + rlim.rlim_max

Returns:

0

Success.

-1

An error occurred (errno is set).

Errors:

ENOMEM

This could mean:

• The data segment size limit, as set by setrlimit(), would be exceeded.
• The maximum possible size of a data segment (compiled into the system) would be exceeded.
• Insufficient space exists in the swap area to support the expansion.
• Out of address space; the new break value would extend into an area of the address space defined by some previously established mapping (see mmap()).

EAGAIN

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

Classification:

Legacy Unix

Caveats:

The behavior of brk() is unspecified if an application also uses any other memory functions (such as malloc(), mmap(), and free()). The brk() function has been used in specialized cases where no other memory allocation function provided the same capability. Use mmap() instead because it can be used portably with all other memory allocation functions and with any function that uses other allocation functions.

The value of the argument to brk() is rounded up for alignment with eight-byte boundaries.

Setting the break may fail due to a temporary lack of swap space. It isn't possible to distinguish this from a failure caused by exceeding the maximum size of the data segment without consulting getrlimit().

See also:

_btext, _edata, _end, _etext, execl(), execle(), execlp(), execlpe(), execv(), execve(), execvp(), execvpe(), free(), getrlimit(), malloc(), mmap(), sbrk()