From f954a53a9a7dced3fb4c80b1e8dd267981ae025d Mon Sep 17 00:00:00 2001 From: cvs2svn Date: Mon, 19 Oct 1998 21:47:13 +0000 Subject: This commit was manufactured by cvs2git to create branch 'OPENBSD_2_4'. --- src/lib/libc/stdlib/malloc.3 | 350 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 350 insertions(+) create mode 100644 src/lib/libc/stdlib/malloc.3 (limited to 'src/lib/libc/stdlib/malloc.3') diff --git a/src/lib/libc/stdlib/malloc.3 b/src/lib/libc/stdlib/malloc.3 new file mode 100644 index 0000000000..d5f8837ec2 --- /dev/null +++ b/src/lib/libc/stdlib/malloc.3 @@ -0,0 +1,350 @@ +.\" 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.9 1998/08/15 20:32:02 deraadt 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 +.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 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 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 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. -- cgit v1.2.3-55-g6feb