1 files changed, 87 insertions, 55 deletions
diff --git a/lib/libc/sys/brk.2 b/lib/libc/sys/brk.2
index 72e3c47..c215be9 100644
--- a/lib/libc/sys/brk.2
+++ b/lib/libc/sys/brk.2
@@ -32,7 +32,7 @@
 .\"     @(#)brk.2	8.4 (Berkeley) 5/1/95
 .\" $FreeBSD$
 .\"
-.Dd May 1, 1995
+.Dd July 12, 1999
 .Dt BRK 2
 .Os
 .Sh NAME
@@ -49,96 +49,128 @@
 .Fn sbrk "int incr"
 .Sh DESCRIPTION
 .Bf -symbolic
-The brk and sbrk functions are historical curiosities
-left over from earlier days before the advent of virtual memory management.
+The
+.Fn brk
+and
+.Fn sbrk
+functions are legacy interfaces from before the
+advent of modern virtual memory management.
 .Ef
+.Pp
+The
+.Fn brk
+and
+.Fn sbrk
+functions are used to change the amount of memory allocated in a
+process's data segment.
+They do this by moving the location of the
+.Dq break .
+The break is the first address after the end of the process's
+uninitialized data segment (also known as the
+.Dq BSS ) .
+.Pp
 The
 .Fn brk
 function
-sets the break or lowest address
-of a process's data segment (uninitialized data) to
-.Fa addr
-(immediately above bss).
-Data addressing is restricted between
-.Fa addr
-and the lowest stack pointer to the stack segment.
-Memory is allocated by
-.Fa brk
-in page size pieces;
-if
-.Fa addr
-is not evenly divisible by the system page size, it is
-increased to the next page boundary.
+sets the break to
+.Fa addr .
+.Pp
+The
+.Fn sbrk
+function raises the break by
+.Fa incr
+bytes, thus allocating at least
+.Fa incr
+bytes of new memory in the data segment.
+If
+.Fa incr
+is negative,
+the break is lowered by
+.Fa incr
+bytes.
+.Sh NOTES
+While the actual process data segment size maintained by the kernel will only
+grow or shrink in page sizes, these functions allow setting the break
+to unaligned values (i.e., it may point to any address inside the last
+page of the data segment).
+.Pp
+The current value of the program break may be determined by calling
+.Fn sbrk 0 .
+See also
+.Xr end 3 .
 .Pp
-.\" The
-.\" .Nm sbrk
-.\" function
-.\" allocates chunks of
-.\" .Fa incr
-.\" bytes
-.\" to the process's data space
-.\" and returns an address pointer.
-.\" The
-.\" .Xr malloc 3
-.\" function utilizes
-.\" .Nm sbrk .
-.\" .Pp
-The current value of the program break is reliably returned by
-.Dq Li sbrk(0)
-(see also
-.Xr end 3 ) .
 The
 .Xr getrlimit 2
 system call may be used to determine
 the maximum permissible size of the
-.Em data
-segment;
-it will not be possible to set the break
-beyond the
-.Em rlim_max
-value returned from a call to
-.Xr getrlimit 2 ,
-e.g.\&
-.Dq Va etext No + Va rlp\->rlim_max .
+data segment.
+It will not be possible to set the break
+beyond
+.Dq Va etext No + Va rlim.rlim_max
+where the
+.Va rlim.rlim_max
+value is returned from a call to
+.Fn getrlimit RLIMIT_DATA &rlim .
 (See
 .Xr end 3
 for the definition of
 .Va etext ) .
 .Sh RETURN VALUES
-.Rv -std brk
+The
+.Fn brk
+function returns
+.Po Vt "char *" Pc Ns 0
+if successful;
+otherwise the value
+.Po Vt "char *" Pc Ns \-1
+is returned and the global variable
+.Va errno
+is set to indicate the error.
 .Pp
 The
 .Fn sbrk
-function returns a pointer to the base of the new storage if successful;
-otherwise the value \-1 is returned and the global variable
+function returns the prior break value if successful;
+otherwise the value
+.Po Vt "char *" Pc Ns \-1
+is returned and the global variable
 .Va errno
 is set to indicate the error.
 .Sh ERRORS
-.Fn Brk
+.Fn brk
 or
 .Fn sbrk
-will fail and no additional memory will be allocated if
-one of the following are true:
+will fail if:
 .Bl -tag -width Er
+.It Bq Er EINVAL
+The requested break value was beyond the beginning of the data segment.
 .It Bq Er ENOMEM
-The limit, as set by
+The data segment size limit, as set by
 .Xr setrlimit 2 ,
 was exceeded.
 .It Bq Er ENOMEM
-The maximum possible size of a data segment (compiled into the
-system) was exceeded.
-.It Bq Er ENOMEM
 Insufficient space existed in the swap area
-to support the expansion.
+to support the expansion of the data segment.
 .El
 .Sh SEE ALSO
 .Xr execve 2 ,
 .Xr getrlimit 2 ,
+.Xr mmap 2 ,
 .Xr end 3 ,
+.Xr free 3 ,
 .Xr malloc 3
 .Sh BUGS
+Mixing
+.Fn brk
+or
+.Fn sbrk
+with
+.Xr malloc 3 ,
+.Xr free 3 ,
+or similar functions will result in non-portable program behavior.
+.Pp
 Setting the break may fail due to a temporary lack of
-swap space.  It is not possible to distinguish this
+swap space.
+It is not possible to distinguish this
 from a failure caused by exceeding the maximum size of
 the data segment without consulting
 .Xr getrlimit 2 .