sbrk(2)

NAME

     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(intptr_t incr);

DESCRIPTION

     The brk() and sbrk() functions are used  to  change  dynami-
     cally   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, how-
     ever, the same memory space  is reallocated to the same pro-
     cess 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  max-
     imum  permissible size of the data segment; it is not possi-
     ble 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  allo-
     cated 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:
     ENOMEM
           The data segment size limit as set by setrlimit() (see
           getrlimit(2))  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; or 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 appli-
     cation  also  uses  any  other  memory  functions  (such  as
     malloc(3C), mmap(2), free(3C)). The brk() and  sbrk()  func-
     tions  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  attri-
     butes:

     ____________________________________________________________
    |       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  set-
     ting  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().