This commit was manufactured by cvs2svn to create branch 'JB'.

1 files changed, 0 insertions, 424 deletions

diff --git a/lib/libc/stdlib/malloc.3 b/lib/libc/stdlib/malloc.3
deleted file mode 100644
index a7d3240..0000000
--- a/lib/libc/stdlib/malloc.3
+++ /dev/null
@@ -1,424 +0,0 @@
-.\" 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.
-.\"
-.\"     @(#)malloc.3	8.1 (Berkeley) 6/4/93
-.\"     $Id: malloc.3,v 1.14 1997/08/27 06:40:34 phk Exp $
-.\"
-.Dd August 27, 1996
-.Dt MALLOC 3
-.Os FreeBSD 2
-.Sh NAME
-.Nm malloc, calloc, realloc, free
-.Nd general purpose memory allocation functions
-.Sh SYNOPSIS
-.Fd #include <stdlib.h>
-.Ft void *
-.Fn malloc "size_t size"
-.Ft void *
-.Fn calloc "size_t number" "size_t size"
-.Ft void *
-.Fn realloc "void *ptr" "size_t size"
-.Ft void
-.Fn free "void *ptr"
-.Ft char *
-.Va malloc_options;
-.Sh DESCRIPTION
-The
-.Fn malloc
-function allocates
-.Fa size
-bytes of memory.
-The allocated space is suitably aligned (after possible pointer coercion)
-for storage of any type of object.
-If the space is at least
-.Em pagesize
-bytes in length (see
-.Xr getpagesize (3)),
-the returned memory will be page boundary aligned as well.
-If
-.Fn malloc
-fails, a NULL pointer is returned.
-.Pp
-The
-.Fn calloc
-function allocates space for
-.Fa number
-objects,
-each
-.Fa size
-bytes in length.
-The result is identical to calling
-.Fn malloc
-with an argument of
-.Dq "number * size" ,
-with the exception that the allocated memory is initialized to nul bytes.
-.Pp
-The
-.Fn realloc
-function changes the size of the previously allocated memory referenced by
-.Fa ptr
-to
-.Fa size
-bytes.
-The contents of the memory 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 memory is undefined.
-If the requested memory cannot be allocated, NULL is returned and
-the memory referenced by
-.Fa ptr
-is valid and unchanged.
-If
-.Fa ptr
-is NULL, the
-.Fn realloc
-function behaves identically to
-.Fn malloc
-for the specified size.
-.Pp
-The
-.Fn free
-function causes the allocated memory referenced by
-.Fa ptr
-to be made available for future allocations.
-If
-.Fa ptr
-is NULL, no action occurs.
-.Sh TUNING
-Once, when the first call is made to one of these memory allocation
-routines, various flags will be set or reset, which affect the
-workings of this allocation implementation.
-.Pp
-The ``name'' of the file referenced by the symbolic link named
-.Pa /etc/malloc.conf ,
-the value of the environment variable
-.Ev MALLOC_OPTIONS ,
-and the string pointed to by the global variable
-.Va malloc_options 
-will be interpreted, in that order, character by character as flags.
-.Pp
-Most flags are single letters,
-where uppercase indicates that the behavior is set, or on,
-and lowercase means that the behavior is not set, or off.
-.Bl -tag -width indent
-.It A
-All warnings (except for the warning about unknown
-flags being set), and failure to allocate memory become fatal.
-The process will call
-.Fn abort 3
-in these cases.
-.It J
-Each byte of new memory allocated by
-.Fn malloc
-or
-.Fn realloc
-as well as all memory returned by
-.Fn free
-or 
-.Fn realloc
-will be initialized to 0xd0.
-This options also sets the
-.Dq R
-option.
-This is intended for debugging and will impact performance negatively.
-.It H
-Pass a hint to the kernel about pages unused by the allocation functions.
-This will help performance if the system is paging excessively.  This
-option is on by default.
-.It R
-Cause the
-.Fn realloc
-function to always reallocate memory even if the initial allocation was
-sufficiently large.
-This can substantially aid in compacting memory.
-.It U
-Generate
-.Dq utrace
-entries for
-.Xr ktrace 1 ,
-for all operations.
-Consult the source for details on this option.
-.It V
-Attempting to allocate zero bytes will return a NULL pointer instead of
-a valid pointer.
-(The default behavior is to make a minimal allocation and return a 
-pointer to it.)
-This option is provided for System V compatibility.
-This option is incompatible with the
-.Dq X
-option.
-.It X
-Rather than return failure for any allocation function,
-display a diagnostic message on stderr and cause the program to drop
-core (using
-.Fn abort 3 ).
-This option should be set at compile time by including the following in
-the source code:
-.Bd -literal -offset indent
-extern char *malloc_options;
-malloc_options = "X";
-.Ed
-.It Z
-This option implicitly sets the
-.Dq J
-and
-.Dq R
-options, and then zeros out the bytes that were requested.
-This is intended for debugging and will impact performance negatively.
-.It <
-Reduce the size of the cache by a factor of two.
-The default cache size is 16 pages.
-This option can be specified multiple times.
-.It >
-Double the size of the cache by a factor of two.
-The default cache size is 16 pages.
-This option can be specified multiple times.
-.El
-.Pp
-The
-.Dq J
-and
-.Dq Z
-options are intended for testing and debugging.
-An application which changes its behavior when these options are used 
-is flawed.
-.Sh EXAMPLES
-To set a systemwide reduction of cache size, and to dump core whenever
-a problem occurs:
-.Pp
-.Bd -literal -offset indent
-ln -s 'A<' /etc/malloc.conf
-.Ed
-.Pp
-To specify in the source that a program does no return value checking
-on calls to these functions:
-.Bd -literal -offset indent
-extern char *malloc_options;
-malloc_options = "X";
-.Ed
-.Sh ENVIRONMENT
-The following environment variables affect the execution of the allocation
-functions:
-.Bl -tag -width MMM
-.It Ev MALLOC_OPTIONS
-If the environment variable
-.Ev MALLOC_OPTIONS
-is set, the characters it contains will be interpreted as flags to the
-allocation functions.
-.Sh RETURN VALUES
-The
-.Fn malloc
-and
-.Fn calloc
-functions return a pointer to the allocated memory if successful; otherwise
-a NULL pointer is returned.
-.Pp
-The
-.Fn realloc
-function returns a pointer, possibly identical to
-.Fa ptr ,
-to the allocated memory
-if successful; otherwise a NULL pointer is returned, in which case the
-memory referenced by
-.Fa ptr
-is still available and intact.
-.Pp
-The
-.Fn free
-function returns no value.
-.Sh "DEBUGGING MALLOC PROBLEMS"
-.Pp
-The major difference between this implementation and other allocation
-implementations is that the free pages are not accessed unless allocated,
-and are aggressively returned to the kernel for reuse.
-.Bd -filled -offset indent
-Most allocation implementations will store a data structure containing a
-linked list in the free chunks of memory,
-used to tie all the free memory together.
-That can be suboptimal,
-as every time the free-list is traversed,
-the otherwise unused, and likely paged out,
-pages are faulted into primary memory.
-On systems which are paging,
-this can result in a factor of five increase in the number of page-faults
-done by a process.
-.Ed
-.Pp
-A side effect of this architecture is that many minor transgressions on
-the interface which would traditionally not be detected are in fact 
-detected.  As a result, programs that have been running happily for 
-years may suddenly start to complain loudly, when linked with this
-allocation implementation.
-.Pp
-The first and most important thing to do is to set the
-.Dq A
-option.
-This option forces a coredump (if possible) at the first sign of trouble,
-rather than the normal policy of trying to continue if at all possible.
-.Pp
-It is probably also a good idea to recompile the program with suitable
-options and symbols for debugger support.
-.Pp
-If the program starts to give unusual results, coredump or generally behave
-differently without emitting any of the messages listed in the next
-section, it is likely because it depends on the storage being filled with
-nul bytes.  Try running it with
-.Dq Z
-option set;
-if that improves the situation, this diagnosis has been confirmed.
-If the program still misbehaves,
-the likely problem is accessing memory outside the allocated area,
-more likely after than before the allocated area.
-.Pp
-Alternatively, if the symptoms are not easy to reproduce, setting the
-.Dq J
-option may help provoke the problem.
-.Pp
-In truly difficult cases, the
-.Dq U
-option, if supported by the kernel, can provide a detailed trace of
-all calls made to these functions.
-.Pp
-Unfortunately this implementation does not provide much detail about
-the problems it detects, the performance impact for storing such information
-would be prohibitive.
-There are a number of allocation implementations available on the 'Net
-which focus on detecting and pinpointing problems by trading performance
-for extra sanity checks and detailed diagnostics.
-.Sh "DIAGNOSTIC MESSAGES
-If 
-.Fn malloc ,
-.Fn calloc ,
-.Fn realloc
-or
-.Fn free
-detect an error or warning condition,
-a message will be printed to file descriptor STDERR_FILENO.
-Errors will result in the process dumping core.
-If the
-.Dq A
-option is set, all warnings are treated as errors.
-.Pp
-The following is a brief description of possible error messages and
-their meanings:
-.Pp
-.Bl -tag -width indent
-.It "(ES): mumble mumble mumble
-The allocation functions were compiled with
-.Dq EXTRA_SANITY
-defined, and an error was found during the additional error checking.
-Consult the source code for further information.
-.It "allocation failed
-If the
-.Dq A
-option is specified it is a fatal error for an allocation function to fail.
-.It "mmap(2) failed, check limits
-This most likely means that the system is dangerously overloaded or that
-the process' limits are incorrectly specified.
-.It "freelist is destroyed
-The internal free-list has been corrupted.
-.El
-.Pp
-.Bl -tag -width indent
-The following is a brief description of possible warning messages and
-their meanings:
-.Pp
-.It "chunk/page is already free
-The process attempted to
-.Fn free
-memory which had already been freed.
-.It "junk pointer ...
-A pointer specified to one of the allocation functions points outside the
-bounds of the memory of which they are aware.
-.It "malloc() has never been called
-No memory has been allocated,
-yet something is being freed or
-realloc'ed.
-.It "modified (chunk-/page-) pointer
-The pointer passed to
-.Fn free
-or
-.Fn realloc
-has been modified.
-.It "pointer to wrong page
-The pointer that
-.Fn malloc
-or
-.Fn calloc
-is trying to free does not reference a possible page.
-.It "recursive call
-A process has attempted to call an allocation function recursively.
-This is not permitted.  In particular, signal handlers should not
-attempt to allocate memory.
-.It "out of memory
-The
-.Dq X
-option was specified and an allocation of memory failed.
-.It "unknown char in MALLOC_OPTIONS
-An unknown option was specified.
-Even with the
-.Dq A
-option set, this warning is still only a warning.
-.Sh SEE ALSO
-.Xr brk 2 ,
-.Xr alloca 3 ,
-.Xr getpagesize 3 ,
-.Xr memory 3
-.Pa /usr/share/doc/papers/malloc.ascii.gz
-.Sh STANDARDS
-The
-.Fn malloc ,
-.Fn calloc ,
-.Fn realloc
-and
-.Fn free
-functions conform to
-.St -ansiC .
-.Sh BUGS
-The messages printed in case of problems provide no detail about the
-actual values.
-.Pp
-It can be argued that returning a null pointer when asked to
-allocate zero bytes is a silly response to a silly question.
-.Pp
-This implementation was authored by Poul-Henning Kamp.
-Please report any problems to him at
-.Li <phk@FreeBSD.org> .
-.Sh HISTORY
-The present allocation implementation started out as a filesystem for a
-drum attached to a 20bit binary challenged computer which was built 
-with discrete germanium transistors.  It has since graduated to 
-handle primary storage rather than secondary.
-It first appeared in its new shape and ability in FreeBSD release 2.2.