unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



brk(2)								       brk(2)



NAME

  brk, sbrk - Change space allocation

LIBRARY

  Standard C Library (libc.so, libc.a)

SYNOPSIS

  #include <&lt;unistd.h>&gt;

  int brk(
	  void *addr );

  void *sbrk(
	  intptr_t incr	);

  The following	function definitions do	not conform to current standards and
  are supported	only for backward compatibility:

  int brk(
	  char *addr );

  void *sbrk(
	  ssize_t incr );

  void *sbrk(
	  long incr );

STANDARDS

  Interfaces documented	on this	reference page conform to industry standards
  as follows:

  brk(), sbrk():  XPG4-UNIX

  Refer	to the standards(5) reference page for more information	about indus-
  try standards	and associated tags.

PARAMETERS

  addr
      Points to	the effective address of the maximum available data.

  incr
      Specifies	the number of bytes to be added	to the current break.  The
      value of incr may	be positive or negative.

DESCRIPTION

  The brk() function sets the lowest data segment location not used by the
  program (called the break) to	addr.

  In the alternate function sbrk(), incr more bytes are	added to the
  program's data space,	and a pointer to the start of the new area is
  returned.


  When a program begins	execution with the execve() function, the break	is
  set at the highest location defined by the program and data storage areas.
  Therefore, only programs with	growing	data areas should need to use sbrk().

  The current value of the program break is reliably returned by ``sbrk(0)''.
  The getrlimit() function may be used to determine the	maximum	permissible
  size of the data segment. It is not possible to set the break	beyond the
  value	returned from a	call to	the getrlimit()	function.

  If the data segment was locked at the	time of	the brk() function, addi-
  tional memory	allocated to the data segment by brk() will also be locked.

NOTES

  Programmers should be	aware that the concept of a current break is a his-
  torical remnant of earlier UNIX systems.  Many existing UNIX programs	were
  designed using this memory model, and	these programs typically use the
  brk()	or sbrk() functions to increase	or decrease their available memory.

  The use of the mmap()	function is now	preferred because it can be used
  portably with	all other memory allocation functions and with any function
  that uses other allocation functions.

RETURN VALUES

  Upon successful completion, the brk()	function returns a value of 0 (zero),
  and the sbrk function	returns	the prior break	value.	If either call fails,
  a value of -1	is returned and	errno is set to	indicate the error.

ERRORS

  If the brk() or sbrk() function fails, no additional memory is allocated
  and errno may	be set to the following	value:

  [EINVAL]  Indicates an attempt to set	a break	value to less than the ini-
	    tial value at program startup.

  [ENOMEM]  The	requested change would allocate	more space than	allowed	by
	    the	limit as returned by the getrlimit() function.

RELATED	INFORMATION

  Functions: exec(2), getrlimit(2), malloc(3), mmap(2),	plock(2).

  Standards: standards(5)