diff options
Diffstat (limited to 'lib/libc/stdlib/malloc.3')
| -rw-r--r-- | lib/libc/stdlib/malloc.3 | 424 |
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. |
