Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
brk(2)				 System	Calls				brk(2)

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

       #include	<unistd.h>

       int brk(void *endds);

       void *sbrk(intptr_t incr);

       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 ad-
       dress 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  permis-
       sible size of the data segment; it is not possible to set the break be-
       yond 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 allo-
       cated space accordingly.

       The sbrk() function adds	 incr function bytes to	the  break  value  and
       changes the allocated space accordingly.	The incr function can be nega-
       tive, in	which case the amount of allocated space is decreased.

       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.  Oth-
       erwise, it returns (void	*)-1 and sets errno to indicate	the error.

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

       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 capa-
       bility.	The use	of mmap(2) is now preferred because  it	 can  be  used
       portably	 with all other	memory allocation functions and	with any func-
       tion that uses other allocation functions.

       It is unspecified whether the pointer returned  by  sbrk()  is  aligned
       suitably	for any	purpose.

       See attributes(5) for descriptions of the following attributes:

       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       |MT-Level		     |MT-Safe			   |

       exec(2),	getrlimit(2), mmap(2), shmop(2), ulimit(2), end(3C), free(3C),

       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 nec-
       essary for all machine architectures.

       The  value of the arguments to both brk() and sbrk() are	rounded	up for
       alignment with eight-byte boundaries.

       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.10			  14 Jan 1997				brk(2)


Want to link to this manual page? Use this URL:

home | help