Manual Pages for UNIX Operating System command usage for man brk

System Calls                                               brk(2)



NAME
     brk, sbrk - change the amount of  space  allocated  for  the
     calling process's data segment

SYNOPSIS
     #include 

     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.





SunOS 5.11          Last change: 14 Jan 1997                    1






System Calls                                               brk(2)



     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:













SunOS 5.11          Last change: 14 Jan 1997                    2






System Calls                                               brk(2)



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


























SunOS 5.11          Last change: 14 Jan 1997                    3