summaryrefslogtreecommitdiff
path: root/lib/libc/sys
diff options
context:
space:
mode:
authorperry <perry@NetBSD.org>1999-07-06 16:36:15 +0000
committerperry <perry@NetBSD.org>1999-07-06 16:36:15 +0000
commiteeebdec53eadddf91374f34b32350f7ffe4d07a1 (patch)
tree3740809be475239ea62efd41c7b6194527a6a9ea /lib/libc/sys
parent76875808ab41e090195353a3feb2d02133f49bd5 (diff)
Clean up this mess a lot. I believe we still have the following
issues (at least): 1) sbrk is defined as returning char *, which violates XPG 2) I'm not clear on what happens if you try to sbrk() on a negative incr that is less than the page size. I'm guessing "nothing", but we should document this behavior. 3) XPG says some interesting things about whether new pages are guaranteed zeroed. We say nothing about this. We should document our behavior. 4) It isn't clear if *we* guarantee that malloc and sbrk can be mixed in our API (I've documented that it isn't universally portable.) We really should clean these up, too.
Diffstat (limited to 'lib/libc/sys')
-rw-r--r--lib/libc/sys/brk.296
1 files changed, 60 insertions, 36 deletions
diff --git a/lib/libc/sys/brk.2 b/lib/libc/sys/brk.2
index ce10cff3f5c..33d2845ff91 100644
--- a/lib/libc/sys/brk.2
+++ b/lib/libc/sys/brk.2
@@ -1,4 +1,4 @@
-.\" $NetBSD: brk.2,v 1.15 1999/03/22 19:45:00 garbled Exp $
+.\" $NetBSD: brk.2,v 1.16 1999/07/06 16:36:15 perry Exp $
.\"
.\" Copyright (c) 1980, 1991, 1993
.\" The Regents of the University of California. All rights reserved.
@@ -33,7 +33,7 @@
.\"
.\" @(#)brk.2 8.4 (Berkeley) 5/1/95
.\"
-.Dd May 1, 1995
+.Dd July 6, 1999
.Dt BRK 2
.Os
.Sh NAME
@@ -44,48 +44,60 @@
.Fd #include <unistd.h>
.Ft int
.Fn brk "void *addr"
+.\" Note: XPG says sbrk should take an intptr_t and should return a
+.\" void. Our usage conflicts with that.
.Ft char *
.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 brk and sbrk functions are legacy interfaces from before the
+advent of virtual memory management.
.Ef
.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
+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 break must always lie on an even page boundary. If
+.Fn brk
+or
+.Fn sbrk
+are asked for a non-integral number of pages, the address of the break
+will be rounded up to the next highest page boundary.
+.Pp
+The
.Fn 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.
+function sets the break to
+.Fa addr .
+.Pp
+The
+.Fn sbrk
+function raises the break by at least
+.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.
.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
-.Fn sbrk 0
-(see also
+.Fn sbrk
+returns the prior address of the break.
+The current value of the program break may be determined by calling
+.Fn sbrk 0 .
+(See also
.Xr end 3 ) .
+.Pp
The
.Xr getrlimit 2
system call may be used to determine
@@ -110,6 +122,7 @@ returns 0 if successful;
otherwise -1 with
.Va errno
set to indicate why the allocation failed.
+.Pp
The
.Fn sbrk
function returns the prior break value if successful;
@@ -138,13 +151,24 @@ to support the expansion.
.Xr execve 2 ,
.Xr getrlimit 2 ,
.Xr mmap 2 ,
-.Xr malloc 3 ,
-.Xr end 3
+.Xr end 3 ,
+.Xr free 3 ,
+.Xr malloc 3
.Sh BUGS
+Note that
+mixing
+.Fn brk
+and
+.Fn sbrk
+with
+.Xr malloc 3 ,
+.Xr free 3 ,
+and similar functions may result in non-portable program
+behavior. Caution is advised.
+.Pp
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
-.Xr getrlimit 2 .
.Sh HISTORY
A
.Fn brk