NAME

malloc, free, realloc, calloc, cfree, valloc, vfree, malloc_size, malloc_good_size, malloc_error, malloc_debug, mstats, alloca − memory allocator

SYNOPSIS

#include <stdlib.h>

void ∗malloc(size_t byteSize)

void free(void ∗ptr)

void ∗realloc(void ∗oldptr, size_t newsize)

void ∗calloc(size_t numElems, size_t byteSize)

void cfree(void ∗ptr)

void ∗valloc(size_t byteSize)

void vfree(void ∗ptr)

size_t malloc_size(void ∗ptr)

size_t malloc_good_size(size_t byteSize)

void (∗malloc_error(void (∗func)(int)))(int)

int malloc_debug(int level)

size_t mstats(void)

char ∗alloca(int size)

DESCRIPTION

Malloc and free provide a general-purpose memory allocation package.  Malloc returns a pointer to a block of at least size bytes beginning on a long boundary. 

The argument to free is a pointer to a block previously allocated by malloc; this space is made available for further allocation.

Needless to say, grave disorder will result if the space assigned by malloc is overrun or if some random number is handed to free.

Malloc maintains multiple lists of free blocks according to size, allocating space from the appropriate list.  It calls vm_allocate (see vm_allocate(2)) to get more memory from the system when there is no suitable space already free.

Realloc changes the size of the block pointed to by ptr to size bytes and returns a pointer to the (possibly moved) block.  The contents will be unchanged up to the lesser of the new and old sizes. 

Calloc allocates space for an array of nelem elements of size elsize.  The space is initialized to zeros. 

Cfree is equivalent to free.

Valloc allocates a page-aligned space of size byteSize. 

Vfree is equivalent to free.

Malloc_size returns the size of the block pointed to by the argument. 

Malloc_good_size adapts malloc to keep a large number of object of the specified size as efficiently as possible, and returns the actual size that malloc will allocate for that size. 

Malloc_error sets an internal pointer to a routine which is called whenever malloc runs out of virtual memory space or discovers an error.  By default, the routine pointed to prints an error message on stderr, sets errno to ENOMEM and returns, causing malloc to return NULL. 

The routine is called with an integer representing the type of error discovered: 0, 1, or 2 means an error was returned by vm_allocate, vm_deallocate, or vm_copy, respectively; 3 means an attempt to free or reallocate space that was already freed; 4 means that an internal verification of the memory heap failed; and 5 means an attempt to free or reallocate space that was never allocated. 

Malloc_debug sets an internal variable to control the amount of error checking performed by Malloc.  The value can be set to values from 0 to 31, setting five bits individually, and returning the old value.  Level 0 does no checking and data must never be accessed after it is freed.  Level 1 (the default), delays freeing of data until the next call to free or malloc which provides some compatilibility with common, but incorrect, code which depends on the contents of freed data remaining undisturbed (see BUGS section below).  Level 2 clears out or unmapps all data as it is freed, making it easier to catch usage of freed data spaces.  Level 4 checks that data being freed hasn’t already been freed.  Level 8 checks internal data structures for consistency for all memory allocated as the same size of the data being allocated or freed.  Level 16 checks the internal data structures for all sizes of data for consistency.  These levels can be set independently: Level 32 adds a one deep stack and checks that data hasn’t already been freed. 

Mstats prints a summary of memory usage by malloc on stderr. The efficiency value is calculated based on the rounded-off block sizes, and is the ratio of the space available in the blocks to the total amount of memory allocated by malloc. The value returned is the total amount of memory allocated, in bytes.

Alloca allocates size bytes of space in the stack frame of the caller.  This temporary space is automatically freed on return. 

Each of the allocation routines returns a pointer to space suitably aligned (after possible pointer coercion) for storage of any type of object.  If the space is of pagesize/2 or larger, the memory returned will be page-aligned. 

SEE ALSO

vm_allocate(2), vm_deallocate(2)

DIAGNOSTICS

Malloc, realloc and calloc return a null pointer (0), and set errno to ENOMEM if there is no available memory. 

The malloc routines call an error-handling function upon detection of an error.  By default, the error-handler prints a general message describing the cause of the error to stderr, and then either aborts or attempts to continue, depending on the cause of the error.  By supplying your own error-handling function, using the malloc_error function to set it, you can get additional information about the cause of the error by setting a debugger break-point in your error-handling function, and using the debugger’s "where" or "up" and "down" commands to uncover the location in your program where the error occurred.  Using the "print" command, you should be able to print the expressions that were passed as arguments to the malloc or free functions.  The malloc_debug function can be very useful in tracking down the cause of the problem by turning on additional checking of the malloc operations, so that errors are reported closer to the actual cause of the problem. 

NOTES

Good sizes to call malloc with are: 16, 32, 64, 128, 176, 252, 340, 508, 680, 1020, 1360, 2044, 2724, 4088 bytes, or any multiple of 8192 bytes, as these are the sizes to which malloc rounds requests.  These choices of size also minimize fragmentation caused by packing these requests into 8192 byte regions.  Other sizes may be added by calling malloc_good_size.

Calloc is defined in a way that requires that its arguments to be multiplied together.  Calling Calloc with the second argument equal to 1 will avoid the multiplication, and run slightly faster. 

BUGS

Malloc should guarantee nothing about the state of a block once it has been passed to free.  However, some other versions of malloc will guarantee than a block that have been freed is left unchanged until a subsequent call to malloc, calloc, or realloc. If this package is use with malloc_debug’s level 1 set (the default), after a call to free, the contents are left undisturbed (and unfreed) until the next call to free or realloc. Also, to get at least partial compatibility with applications that used the very questionable practice of attempting storage compaction by calling realloc on previously freed blocks, realloc works if ptr points to a block freed since the last call of free.

Level 8 and 16 checking can get very slow. 

Malloc may fail to allocate memory when larger free blocks could be broken up, or when limits are exceeded because the size is rounded up. 

Alloca and valloc are machine dependent; their use is discouraged. 

4th Berkeley Distribution  —  June 21, 1989