4.3BSD - /usr/man/cat2/sbrk.0

BRK(2)                                                                  BRK(2)


NAME
       brk, sbrk - change data segment size

SYNOPSIS
       #include <sys/types.h>

       char *brk(addr)
       char *addr;

       char *sbrk(incr)
       int incr;

DESCRIPTION
       Brk sets the system’s idea of the lowest data segment location not used
       by the program (called the break) to addr (rounded up to the next  mul‐
       tiple  of  the  system’s  page  size).  Locations greater than addr and
       below the stack pointer are not in the  address  space  and  will  thus
       cause a memory violation if accessed.

       In  the  alternate function sbrk, incr more bytes are added to the pro‐
       gram’s data space and a pointer  to  the  start  of  the  new  area  is
       returned.

       When  a  program  begins  execution  via execve the break is set at the
       highest location defined by the program and data storage areas.   Ordi‐
       narily,  therefore,  only  programs with growing data areas need to use
       sbrk.

       The getrlimit(2) system call may be used to determine the maximum  per‐
       missible  size  of the data segment; it will not be possible to set the
       break beyond the rlim_max value returned from a call to getrlimit, e.g.
       “etext + rlp→rlim_max.”  (see end(3) for the definition of etext).

RETURN VALUE
       Zero  is  returned  if the brk could be set; -1 if the program requests
       more memory than the system limit.  Sbrk returns -1 if the break  could
       not be set.

ERRORS
       Sbrk will fail and no additional memory will be allocated if one of the
       following are true:

       [ENOMEM]       The limit, as set by setrlimit(2), was exceeded.

       [ENOMEM]       The maximum possible size of a  data  segment  (compiled
                      into the system) was exceeded.

       [ENOMEM]       Insufficient  space  existed in the swap area to support
                      the expansion.

SEE ALSO
       execve(2), getrlimit(2), malloc(3), end(3)

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.


4th Berkeley Distribution        May 22, 1986                           BRK(2)