Manual page for brk(2)
brk, sbrk - change the amount of space allocated for the calling process's data segment
SYNOPSIS
#include <unistd.h>
int brk(void *endds);
void *sbrk(int incr);
DESCRIPTION
The
brk()
and
sbrk()
functions are used to change dynamically the amount of space allocated
for the calling process's data segment (see
exec.2
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.
The
getrlimit.2
function may be used to determine
the maximum permissible size of the
data
segment; it is not possible to set the break beyond the
rlim_max
value returned from a call to
getrlimit(),
that is to say, ``end + rlim.rlim_max.''
See
end.3c
The
brk()
function sets the break value to
endds
and changes the allocated space accordingly.
The
sbrk()
function adds
incr
function bytes to the break value and changes the allocated space accordingly.
The
incr
function can be negative, in which case the amount of allocated space
is decreased.
RETURN VALUES
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 and no additional memory will be allocated if
one of the following occurs:
- ENOMEM
-
The data segment size limit, as set by
setrlimit()
(see
getrlimit.2
would be exceeded.
- ENOMEM
-
The maximum possible size of a data segment (compiled into the
system) would be exceeded.
- ENOMEM
-
Insufficient space exists in the swap area
to support the expansion.
- ENOMEM
-
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.2
- EAGAIN
-
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 (see
ulimit.2
USAGE
The behavior of
brk()
and
sbrk()
is unspecified if an application also uses any other memory functions (such as
malloc.3c
mmap.2
free.3c
The
brk()
and
sbrk()
functions have been used in specialized cases where no other memory allocation
function provided the same capability. The use of
mmap.2
is now preferred because it can be used portably with all other memory
allocation functions and with any function that uses other allocation
functions.
It is unspecified whether the pointer returned by
sbrk()
is aligned suitably for any purpose.
ATTRIBUTES
See
attributes.5
for descriptions of the following attributes:
+---------------+-----------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+-----------------+
|MT-Level | MT-Safe |
+---------------+-----------------+
SEE ALSO
exec.2
getrlimit.2
mmap.2
shmop.2
ulimit.2
end.3c
free.3c
malloc.3c
NOTES
The value of
incr
may be adjusted by the system before setting the new break
value. Upon successful completion, the implementation
guarantees a minimum of
incr
bytes will be added to the data segment if
incr
is a positive value. If
incr
is a negative value, a maximum of
incr
bytes will be removed from the data segment. This adjustment
may not be necessary for all machine architectures.
The value of the arguments to both
brk()
and
sbrk()
are rounded up for alignment with eight-byte boundaries.
BUGS
Setting the break may fail due to a temporary lack of
swap space.
It is not possible to distinguish this
from a failure caused by exceeding the maximum size of
the data segment without consulting
getrlimit().
Created by unroff & hp-tools.
© by Hans-Peter Bischof. All Rights Reserved (1997).
Last modified 07/October/97
