diff options
Diffstat (limited to 'lib/libc/stdlib/malloc.3')
| -rw-r--r-- | lib/libc/stdlib/malloc.3 | 294 |
1 files changed, 294 insertions, 0 deletions
diff --git a/lib/libc/stdlib/malloc.3 b/lib/libc/stdlib/malloc.3 new file mode 100644 index 0000000..98dabbc --- /dev/null +++ b/lib/libc/stdlib/malloc.3 @@ -0,0 +1,294 @@ +.\" 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.8 1997/02/22 15:03:10 peter Exp $ +.\" +.Dd August 27, 1996 +.Dt MALLOC 3 +.Os FreeBSD 2 +.Sh NAME +.Nm malloc +.Nd general memory allocation function +.Pp +.Nm free +.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 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 +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 +The +.Fn realloc +function changes the size of the object pointed to by +.Fa ptr +to the size specified by +.Fa size . +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. +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. +.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. + +.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 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 ktrace(1) for all operations. +Consult the source for this one. + +.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 returns either a null pointer or a pointer +to the possibly moved allocated space. +.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 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. |
