summaryrefslogtreecommitdiff
path: root/lib/libc/stdlib/malloc.3
diff options
context:
space:
mode:
authorlukem <lukem@NetBSD.org>1999-08-02 03:18:46 +0000
committerlukem <lukem@NetBSD.org>1999-08-02 03:18:46 +0000
commitc2601fffeebc82a2f1ea844841a6f94f575da778 (patch)
treeda688dbaa82ffa5be878f56fefb037695aec2737 /lib/libc/stdlib/malloc.3
parent95d53bad01cd3d352a7e3037bdd4b18ae8939e46 (diff)
replace malloc(3) with one from freebsd which documents our new malloc.c
(also from freebsd). comment out references to reallocf with .\"XXX" for now. i also fixed some roff misuse as well. replace calloc(3), free(3) and realloc(3) with links to malloc(3)
Diffstat (limited to 'lib/libc/stdlib/malloc.3')
-rw-r--r--lib/libc/stdlib/malloc.3429
1 files changed, 399 insertions, 30 deletions
diff --git a/lib/libc/stdlib/malloc.3 b/lib/libc/stdlib/malloc.3
index 6ac3172b6d1..e5abb3679b7 100644
--- a/lib/libc/stdlib/malloc.3
+++ b/lib/libc/stdlib/malloc.3
@@ -1,4 +1,4 @@
-.\" $NetBSD: malloc.3,v 1.9 1999/03/22 19:44:57 garbled Exp $
+.\" $NetBSD: malloc.3,v 1.10 1999/08/02 03:18:47 lukem Exp $
.\"
.\" Copyright (c) 1980, 1991, 1993
.\" The Regents of the University of California. All rights reserved.
@@ -35,60 +35,429 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
-.\" from: @(#)malloc.3 8.1 (Berkeley) 6/4/93
+.\" @(#)malloc.3 8.1 (Berkeley) 6/4/93
+.\" From FreeBSD: Id: malloc.3,v 1.18 1999/03/28 14:16:04 phk Exp
.\"
-.Dd June 4, 1993
+.Dd August 2, 1999
.Dt MALLOC 3
.Os
.Sh NAME
-.Nm malloc
-.Nd general memory allocation function
+.Nm malloc ,
+.Nm calloc ,
+.Nm realloc ,
+.Nm free
+.\"XXX",
+.\"XXX".Nm reallocf
+.Nd general purpose memory allocation functions
.Sh LIBRARY
.Lb libc
.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"
+.\"XXX".Ft void *
+.\"XXX".Fn reallocf "void *ptr" "size_t size"
+.Ft void
+.Fn free "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 .
+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 all bits zero.
+.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
-function maintains multiple lists of free blocks according to size, allocating
-space from the appropriate list.
+for the specified size.
+.\"XXX".Pp
+.\"XXX"The
+.\"XXX".Fn reallocf
+.\"XXX"function call is identical to the realloc function call, except that it
+.\"XXX"will free the passed pointer when the requested memory cannot be allocated.
+.\"XXX"This is a FreeBSD
+.\"XXX"specific API designed to ease the problems with traditional coding styles
+.\"XXX"for realloc causing memory leaks in libraries.
.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.
+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
+.\"XXX".Fn malloc ,
+.\"XXX".Fn realloc
+.\"XXX"or
+.\"XXX".Fn reallocf
+.Fn malloc
+or
+.Fn realloc
+as well as all memory returned by
+.\"XXX".Fn free ,
+.\"XXX".Fn realloc
+.\"XXX"or
+.\"XXX"Fn reallocf
+.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 off by default.
+.It R
+Causes the
+.Fn realloc
+.\"XXX"and
+.\"XXX".Fn reallocf
+.\"XXX"functions
+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.
+.El
.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
+.\"XXX"and
+.\"XXX".Fn reallocf
+.\"XXX"functions return
function returns
-a pointer to the allocated space if successful; otherwise
-a null pointer is returned.
+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.
+.El
.Sh SEE ALSO
.Xr brk 2 ,
.Xr alloca 3 ,
-.Xr calloc 3 ,
-.Xr free 3 ,
.Xr getpagesize 3 ,
-.Xr memory 3 ,
-.Xr realloc 3
+.Xr memory 3
+.\"XXX" .Pa /usr/share/doc/papers/malloc.ascii.gz
.Sh STANDARDS
The
-.Fn malloc
-function conforms to
+.Fn malloc ,
+.Fn calloc ,
+.Fn realloc
+and
+.Fn free
+functions conform to
.St -ansiC .
.Sh BUGS
-The current implementation of
-.Fn 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.
+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
+.Fx 2.2 , and then in
+.Nx 1.5 .