1 files changed, 113 insertions, 12 deletions
diff --git a/lib/libc/stdlib/malloc.3 b/lib/libc/stdlib/malloc.3
index 98ebadc..58d0ae4 100644
--- a/lib/libc/stdlib/malloc.3
+++ b/lib/libc/stdlib/malloc.3
@@ -41,10 +41,20 @@
 .Sh NAME
 .Nm malloc ,
 .Nd general memory allocation function
+.Pp
+.Nm free
+.Nd free up memory allocated with malloc, calloc or realloc
+.Pp
+.Nm realloc
+.Nd reallocation of memory function
 .Sh SYNOPSIS
 .Fd #include <stdlib.h>
 .Ft void *
 .Fn malloc "size_t size"
+.Ft void
+.Fn free "void *ptr"
+.Ft void *
+.Fn realloc "void *ptr" "size_t size"
 .Sh DESCRIPTION
 The
 .Fn malloc
@@ -61,30 +71,121 @@ suitably aligned (after possible pointer
 coercion) for storage of any type of object. If the space is of
 .Em pagesize
 or larger, the memory returned will be page-aligned.
+.Pp
+The
+.Fn free
+function causes the space pointed to by
+.Fa ptr
+to be deallocated, that is, at least made available for further allocation,
+but if possible, it will passed back to the kernel with
+.Xr sbrk 2 .
+If
+.Fa ptr
+is a null pointer, no action occurs.
+.Pp
+The
+.Fn realloc
+function changes the size of the object pointed to by
+.Fa ptr
+to the size specified by
+.Fa size .
+The contents of the object are unchanged up to the lesser
+of the new and old sizes.
+If the new size is larger, the value of the newly allocated portion
+of the object is indeterminate.
+If
+.Fa ptr
+is a null pointer, the
+.Fn realloc
+function behaves like the
+.Fn malloc 
+function for the specified size.
+If the space cannot be allocated, the object 
+pointed to by
+.Fa ptr
+is unchanged.
+If
+.Fa size
+is zero and
+.Fa ptr
+is not a null pointer, the object it points to is freed.
+.Pp
+
+.Sh ENVIRONMENT
+This malloc will check the environment for a variable called
+.Em MALLOC_OPTIONS
+and scan it for flags.
+Flags are single letters, uppercase means on, lowercase means off.
+.Bl -tag -width indent
+.It A
+``abort'' malloc will coredump the process, rather than tolerate failure.
+This is a very handy debugging aid, since the core file will represent the
+time of failure,
+rather than when the NULL pointer was accessed.
+
+.It D
+``dump'' malloc will dump statistics in a file called ``malloc.out'' at exit.
+
+.It J
+``junk'' fill some junk into the area allocated.
+Currently junk is bytes of 0xd0, this is pronounced ``Duh'' :-)
+
+.It R
+``realloc'' always reallocate when
+.Fn realloc
+is called, even if the initial allocation was big enough.
+This can substantially aid in compacting memory.
+
+.It Z
+``zero'' fill some junk into the area allocated (see ``J''),
+except for the exact length the user asked for, which is zeroed.
+
+.El
+.Pp
+The ``J'' and ``Z'' is mostly for testing and debugging,
+if a program changes behavior if either of these options are used,
+it is buggy.
 .Sh RETURN VALUES
 The
 .Fn malloc
 function returns
 a pointer to the allocated space if successful; otherwise
 a null pointer is returned.
+.Pp
+The
+.Fn free
+function returns no value.
+.Pp
+The
+.Fn realloc
+function returns either a null pointer or a pointer
+to the possibly moved allocated space.
 .Sh SEE ALSO
 .Xr brk 2 ,
-.Xr pagesize 2 ,
-.Xr free 3 ,
-.Xr calloc 3 ,
 .Xr alloca 3 ,
-.Xr realloc 3 ,
+.Xr calloc 3 ,
+.Xr getpagesize 3 ,
 .Xr memory 3
 .Sh STANDARDS
 The
 .Fn malloc
 function conforms to
 .St -ansiC .
-.Sh BUGS
-The current implementation of
-.Xr malloc
-does not always fail gracefully when system
-memory limits are approached.
-It may fail to allocate memory when larger free blocks could be broken
-up, or when limits are exceeded because the size is rounded up.
-It is optimized for sizes that are powers of two.
+.Sh HISTORY
+The present implementation of malloc started out as a filesystem on a drum
+attached to a 20bit binary challenged computer built with discrete germanium
+transistors, and it has since graduated to handle primary storage rather than
+secondary.
+.Pp
+The main difference from other malloc implementations are believed to be that
+the free pages are not accessed until allocated.
+Most malloc implementations will store a data structure containing a, 
+possibly double-, linked list in the free chunks of memory, used to tie
+all the free memory together.
+That is a quite suboptimal thing to do.
+Every time the free-list is traversed, all the otherwise unused, and very
+likely paged out, pages get faulted into primary memory, just to see what
+lies after them in the list.
+.Pp
+On systems which are paging, this can make a factor five in difference on the
+page-faults of a process.