This commit was manufactured by cvs2git to create branch 'OPENBSD_2_5'.OPENBSD_2_5

1 files changed, 355 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..9edff6709c
--- /dev/null
+++ b/src/lib/libc/stdlib/malloc.3
@@ -0,0 +1,355 @@
+.\" 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. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"     This product includes software developed by the University of
+.\"     California, Berkeley and its contributors.
+.\" 4. 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.11 1999/03/23 21:07:57 millert Exp $
+.\"
+.Dd August 27, 1996
+.Dt MALLOC 3
+.Os OpenBSD
+.Sh NAME
+.Nm malloc ,
+.Nd general memory allocation function
+.Pp
+.Nm free ,
+.Nm cfree
+.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 cfree "void *ptr"
+.Ft void *
+.Fn realloc "void *ptr" "size_t size"
+.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.
+.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
+if ((p = realloc(p, nsize)) == NULL)
+        return NULL;
+.Ed
+.Pp
+In most cases, this will result in a leak of memory.
+As stated earlier, a return value of
+.Fa NULL
+indicates that the old object still remains allocated.
+Better code looks like this:
+.Bd -literal -offset indent
+if ((p2 = realloc(p, nsize)) == NULL) {
+        if (p)
+                free(p);
+        p = NULL;
+        return NULL;
+}
+p = p2;
+.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 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.
+This option requires the library to have been compiled with -DMALLOC_STATS in
+order to have any effect.
+
+.It J
+``junk'' fill some junk into the area allocated.
+Currently junk is bytes of 0xd0, this is pronounced ``Duh'' :-)
+
+.It H
+``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.
+
+.It N
+Do not output warning messages when encountering possible corruption
+or bad pointers.
+
+.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 U
+``utrace'' generate entries for
+.Xr ktrace 1
+for all operations.
+Consult the source for this one.
+
+.It X
+``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
+
+.It Z
+``zero'' fill some junk into the area allocated (see ``J''),
+except for the exact length the user asked for, which is zeroed.
+
+.It <
+``Half the cache size'' Reduce the size of the cache by a factor of two.
+
+.It >
+``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 ``J'' and ``Z'' is 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 ENVIRONMENT
+See above.
+.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 a pointer to the possibly moved allocated space;
+otherwise a null pointer is returned.
+.Sh MESSAGES
+If 
+.Fn malloc ,
+.Fn free
+or 
+.Fn realloc
+detects an error or warning condition,
+a message will be printed to filedescriptor
+2 (not using stdio).
+Errors will always result in the process being 
+.Xr abort 2 'ed,
+If the ``A'' option has been specified, also warnings will
+.Xr abort 2 
+the process.
+.Pp
+Here is a brief description of the error messages and what they mean:
+.Pp
+``(ES): mumble mumble mumble'':
+malloc have been compiled with -DEXTRA_SANITY and something looks
+fishy in there.  Consult sources and or wizards.
+.Pp
+``allocation failed''
+if the ``A'' option is specified it is an error for
+.Fn malloc
+or 
+.Fn realloc
+to return NULL.
+.Pp
+``mmap(2) failed, check limits.''
+This is a rather weird condition that is most likely to mean that
+the system is seriously overloaded or that your ulimits are sick.
+.Pp
+``freelist is destroyed.''
+mallocs internal freelist has been stomped on.
+.Pp
+Here is a brief description of the warning messages and what they mean:
+.Pp
+``chunk/page is already free.''
+A pointer to a free chunk is attempted freed again.
+.Pp
+``junk pointer, too high to make sense.''
+The pointer doesn't make sense.  It's above the area of memory that
+malloc knows something about.
+This could be a pointer from some
+.Xr mmap 2 'ed 
+memory.
+.Pp
+``junk pointer, too low to make sense.''
+The pointer doesn't make sense.  It's below the area of memory that
+malloc knows something about.
+This pointer probably came from your data or bss segments.
+.Pp
+``malloc() has never been called.''
+Nothing has ever been allocated, yet something is being freed or
+realloc'ed.
+.Pp
+``modified (chunk-/page-) pointer.''
+The pointer passed to free or realloc has been modified.
+.Pp
+``pointer to wrong page.''
+The pointer that malloc is trying to free is not pointing to
+a sensible page.
+.Pp
+``recursive call.''
+You have tried to call recursively into these functions.
+I can only imagine this as happening if you call one of these
+functions from a signal function, which happens to be called
+while you're already in here.
+Well, sorry to say: that's not supported.
+If this is a problem for you I'd like to hear about it.  It
+would be possible to add a sigblock() around this package,
+but it would have a performance penalty that is not acceptable
+as the default.
+.Pp
+``unknown char in MALLOC_OPTIONS''
+we found something we didn't understand.
+.Sh FILES
+.Bl -tag -width "/etc/malloc.conf"
+.It Pa /etc/malloc.conf
+symbolic link to file containing option flags
+.Sh SEE ALSO
+.Xr brk 2 ,
+.Xr alloca 3 ,
+.Xr calloc 3 ,
+.Xr getpagesize 3 ,
+.Xr memory 3
+.Pa /usr/share/doc/papers/malloc.ascii.gz
+.Sh STANDARDS
+The
+.Fn malloc
+function conforms to
+.St -ansiC .
+.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.