1 files changed, 426 insertions, 0 deletions

diff --git a/src/lib/libc/stdlib/malloc.3 b/src/lib/libc/stdlib/malloc.3
new file mode 100644
index 0000000000..2af8900656
--- /dev/null
+++ b/src/lib/libc/stdlib/malloc.3
@@ -0,0 +1,426 @@
+.\"
+.\" Copyright (c) 1980, 1991, 1993
+.\"     The Regents of the University of California.  All rights reserved.
+.\"
+.\" This code is derived from software contributed to Berkeley by
+.\" the American National Standards Committee X3, on Information
+.\" Processing Systems.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. Neither the name of the University nor the names of its contributors
+.\"    may be used to endorse or promote products derived from this software
+.\"    without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\"     $OpenBSD: malloc.3,v 1.32 2003/10/16 17:05:04 tedu Exp $
+.\"
+.Dd August 27, 1996
+.Dt MALLOC 3
+.Os
+.Sh NAME
+.Nm malloc ,
+.Nm calloc ,
+.Nm realloc ,
+.Nm free ,
+.Nm cfree
+.Nd memory allocation and deallocation
+.Sh SYNOPSIS
+.Fd #include <stdlib.h>
+.Ft void *
+.Fn malloc "size_t size"
+.Ft void *
+.Fn calloc "size_t nmemb" "size_t size"
+.Ft void *
+.Fn realloc "void *ptr" "size_t size"
+.Ft void
+.Fn free "void *ptr"
+.Ft void
+.Fn cfree "void *ptr"
+.Ft char *
+.Va malloc_options
+.Sh DESCRIPTION
+The
+.Fn malloc
+function allocates uninitialized space for an object whose
+size is specified by
+.Fa size .
+The
+.Fn malloc
+function maintains multiple lists of free blocks according to size, allocating
+space from the appropriate list.
+.Pp
+The allocated space is
+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
+Allocation of a zero size object returns a pointer to a zero size object.
+This zero size object is access protected, so any access to it will
+generate an exception (SIGSEGV).
+Many zero-sized objects can be placed consecutively in shared
+protected pages.
+The minimum size of the protection on each object is suitably aligned and
+sized as previously stated, but the protection may extend further depending
+on where in a protected zone the object lands.
+.Pp
+The
+.Fn calloc
+function allocates space for an array of
+.Fa nmemb
+objects, each of whose size is
+.Fa size .
+The space is initialized to all bits zero.
+.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
+A
+.Fn cfree
+function is also provided for compatibility with old systems and other
+.Nm malloc
+libraries; it is simply an alias for
+.Fn free .
+.Pp
+The
+.Fn realloc
+function changes the size of the object pointed to by
+.Fa ptr
+to
+.Fa size
+bytes and returns a pointer to the (possibly moved) object.
+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 and uninitialized.
+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 and a new zero size
+object is returned.
+.Pp
+When using
+.Fn realloc
+one must be careful to avoid the following idiom:
+.Pp
+.Bd -literal -offset indent
+size += 50;
+if ((p = realloc(p, size)) == NULL)
+        return (NULL);
+.Ed
+.Pp
+Do not adjust the variable describing how much memory has been allocated
+until one knows the allocation has been successful.
+This can cause aberrant program behavior if the incorrect size value is used.
+In most cases, the above sample will also result in a leak of memory.
+As stated earlier, a return value of
+.Dv NULL
+indicates that the old object still remains allocated.
+Better code looks like this:
+.Bd -literal -offset indent
+newsize = size + 50;
+if ((newp = realloc(p, newsize)) == NULL) {
+        free(p);
+        p = NULL;
+        size = 0;
+        return (NULL);
+}
+p = newp;
+size = newsize;
+.Ed
+.Pp
+Malloc will first look for a symbolic link called
+.Pa /etc/malloc.conf
+and next check the environment for a variable called
+.Ev MALLOC_OPTIONS
+and finally for the global variable
+.Va malloc_options
+and scan them for flags in that order.
+Flags are single letters, uppercase means on, lowercase means off.
+.Bl -tag -width indent
+.It Cm A
+.Dq Abort .
+.Fn 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.
+.Pp
+.It Cm D
+.Dq Dump .
+.Fn malloc
+will dump statistics in a file called
+.Pa malloc.out
+at exit.
+This option requires the library to have been compiled with -DMALLOC_STATS in
+order to have any effect.
+.Pp
+.It Cm G
+Enable guard pages and chunk randomization.
+Each page size or larger allocation is followed by a guard page that will
+cause a segmentation fault upon any access.
+Smaller than page size chunks are returned in a random order.
+.Pp
+.It Cm J
+.Dq Junk .
+Fill some junk into the area allocated.
+Currently junk is bytes of 0xd0; this is pronounced
+.Dq Duh .
+\&:-)
+.Pp
+.It Cm H
+.Dq Hint .
+Pass a hint to the kernel about pages we don't use.
+If the machine is paging a lot this may help a bit.
+.Pp
+.It Cm N
+Do not output warning messages when encountering possible corruption
+or bad pointers.
+.Pp
+.It Cm R
+.Dq realloc .
+Always reallocate when
+.Fn realloc
+is called, even if the initial allocation was big enough.
+This can substantially aid in compacting memory.
+.\".Pp
+.\".It Cm U
+.\".Dq utrace .
+.\"Generate entries for
+.\".Xr ktrace 1
+.\"for all operations.
+.\"Consult the source for this one.
+.Pp
+.It Cm X
+.Dq xmalloc .
+Rather than return failure,
+.Xr abort 3
+the program with a diagnostic message on stderr.
+It is the intention that this option be set at compile time by
+including in the source:
+.Bd -literal -offset indent
+extern char *malloc_options;
+malloc_options = "X";
+.Ed
+.Pp
+.It Cm Z
+.Dq Zero .
+Fill some junk into the area allocated (see
+.Cm J ) ,
+except for the exact length the user asked for, which is zeroed.
+.Pp
+.It Cm <
+.Dq Half the cache size .
+Reduce the size of the cache by a factor of two.
+.Pp
+.It Cm >
+.Dq Double the cache size .
+Double the size of the cache by a factor of two.
+.El
+.Pp
+So to set a systemwide reduction of cache size and coredumps on problems
+one would:
+.Li ln -s 'A<' /etc/malloc.conf
+.Pp
+The
+.Cm J
+and
+.Cm Z
+flags are mostly for testing and debugging.
+If a program changes behavior if either of these options are used,
+it is buggy.
+.Pp
+The default cache size is 16 pages.
+.Sh RETURN VALUES
+The
+.Fn malloc
+and
+.Fn calloc
+functions return a pointer to the allocated space if successful; otherwise,
+a null pointer is returned and
+.Va errno
+is set to
+.Er ENOMEM .
+.Pp
+The
+.Fn free
+and
+.Fn cfree
+functions return no value.
+.Pp
+The
+.Fn realloc
+function returns a pointer to the (possibly moved) allocated space
+if successful; otherwise, a null pointer is returned and
+.Va errno
+is set to
+.Er ENOMEM .
+.Sh ENVIRONMENT
+See above.
+.Sh FILES
+.Bl -tag -width "/etc/malloc.conf"
+.It Pa /etc/malloc.conf
+symbolic link to filename containing option flags
+.El
+.Sh DIAGNOSTICS
+If
+.Fn malloc ,
+.Fn calloc ,
+.Fn realloc ,
+or
+.Fn free
+detect an error or warning condition,
+a message will be printed to file descriptor
+2 (not using stdio).
+Errors will always result in the process being
+.Xr abort 3 'ed.
+If the
+.Cm A
+option has been specified, warnings will also
+.Xr abort 3
+the process.
+.Pp
+Here is a brief description of the error messages and what they mean:
+.Bl -tag -width Fl
+.It Dq (ES): mumble mumble mumble
+.Fn malloc
+has been compiled with
+.Dv \&-DEXTRA_SANITY
+and something looks fishy in there.
+Consult sources and/or wizards.
+.It Dq allocation failed
+If the
+.Cm A
+option is specified it is an error for
+.Fn malloc ,
+.Fn calloc ,
+or
+.Fn realloc
+to return
+.Dv NULL .
+.It Dq mmap(2) failed, check limits.
+This is a rather weird condition that is most likely to indicate a
+seriously overloaded system or a
+.Xr ulimit 1
+restriction.
+.It Dq freelist is destroyed.
+.Fn malloc Ns 's
+internal freelist has been stomped on.
+.El
+.Pp
+Here is a brief description of the warning messages and what they mean:
+.Bl -tag -width Fl
+.It Dq chunk/page is already free.
+A pointer to a free chunk is attempted freed again.
+.It Dq junk pointer, too high to make sense.
+The pointer doesn't make sense.
+It's above the area of memory that
+.Fn malloc
+knows something about.
+This could be a pointer from some
+.Xr mmap 2 'ed
+memory.
+.It Dq junk pointer, too low to make sense.
+The pointer doesn't make sense.
+It's below the area of memory that
+.Fn malloc
+knows something about.
+This pointer probably came from your data or bss segments.
+.It Dq malloc() has never been called.
+Nothing has ever been allocated, yet something is being freed or
+realloc'ed.
+.It Dq modified (chunk-/page-) pointer.
+The pointer passed to free or realloc has been modified.
+.It Dq pointer to wrong page.
+The pointer that
+.Fn malloc
+is trying to free is not pointing to
+a sensible page.
+.It Dq recursive call.
+An attempt was made to call recursively into these functions, i.e., from a
+signal handler.
+This behavior is not supported.
+In particular, signal handlers should
+.Em not
+use any of the
+.Fn malloc
+functions nor utilize any other functions which may call
+.Fn malloc
+(e.g.,
+.Xr stdio 3
+routines).
+.It Dq unknown char in MALLOC_OPTIONS
+We found something we didn't understand.
+.El
+.Sh SEE ALSO
+.Xr brk 2 ,
+.Xr alloca 3 ,
+.Xr getpagesize 3 ,
+.Xr memory 3
+.Sh STANDARDS
+The
+.Fn malloc
+function conforms to
+.St -ansiC .
+.Sh HISTORY
+The present implementation of
+.Fn malloc
+started out as a filesystem on a drum
+attached to a 20-bit 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
+.Fn malloc
+implementations are believed to be that
+the free pages are not accessed until allocated.
+Most
+.Fn 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.