NAME

malloc, free, realloc, calloc, cfree, memalign, valloc, alloca, malloc_debug, malloc_verify − memory allocator

SYNOPSIS

char ∗malloc(size)
unsigned size;

free(ptr)
char ∗ptr;

char ∗realloc(ptr, size)
char ∗ptr;
unsigned size;

char ∗calloc(nelem, elsize)
unsigned nelem, elsize;

cfree(ptr)
char ∗ptr;

char ∗memalign(alignment, size)
unsigned alignment;
unsigned size;

char ∗valloc(size)
unsigned size;

char ∗alloca(size)
int size;

DESCRIPTION

These routines provide a general-purpose memory allocation package.  They maintain a table of free blocks for efficient allocation and coalescing of free storage.  When there is no suitable space already free, the allocation routines call sbrk (see brk(2)) to get more memory from the system.

Each of the allocation routines returns a pointer to space suitably aligned for storage of any type of object.  They return a null pointer if the request cannot be completed (see DIAGNOSTICS). 

Malloc returns a pointer to a block of at least size bytes beginning on a word boundary. A null (0) pointer is returned if size bytes of memory cannot be allocated. 

Free releases a previously allocated block.  Its argument is a pointer to a block previously allocated by malloc, calloc, realloc, valloc, or memalign. 
 
malloc, calloc, realloc, valloc, or memalign. 

Realloc changes the size of the block referenced 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.  For backwards compatibility, realloc accepts a pointer to a block freed since the most recent call to malloc, calloc, realloc, valloc, or memalign.  Note that using realloc with a block freed before the most recent call to malloc, calloc, realloc, valloc, or memalign is an error. 

Calloc uses malloc to allocate space for an array of nelem elements of size elsize, initializes the space to zeros, and returns a pointer to the initialized block. The block can be freed with free or cfree. 

Memalign allocates size bytes on a specified alignment boundary, and returns a pointer to the allocated block.  The value of the returned address is guaranteed to be an even multiple of alignment.  Note that the value of alignment must be a power of two, and must be greater than or equal to the size of a word. 

Valloc(size) is equivalent to memalign(getpagesize(), size). 

Alloca allocates size bytes of space in the stack frame of the caller, and returns a pointer to the allocated block.  This temporary space is automatically freed when the caller returns. 

SEE ALSO

"Fast Fits" by C. J. Stephenson, in Proceedings of the ACM 9th Symposium on Operating Systems, SIGOPS Operating Systems Review, vol. 17, no. 5, October 1983. 

Core Wars, in Scientific American, May 1984. 

DIAGNOSTICS

Malloc, calloc, realloc, valloc, and memalign return a null pointer (0) and set errno if arguments are invalid, or if there is insufficient available memory, or if the heap has been detectably corrupted, e.g. by storing outside the bounds of a block. 

More detailed diagnostics can be made available to programs using malloc, calloc, realloc, valloc, memalign, cfree, and free, by including a special relocatable object file at link time (see FILES).  This file also provides routines for control of error handling and diagnosis, as defined below.  Note that these routines are not defined in the standard library. 

int malloc_debug(level)
int level;

int malloc_verify()

Malloc_debug sets the level of error diagnosis and reporting during subsequent calls to malloc, calloc, realloc, valloc, memalign, cfree, and free.  The value of level is interpreted as follows:

Level 0 Malloc, calloc, realloc, valloc, memalign, cfree, and free behave the same as in the standard library. 

Level 1 Malloc, calloc, realloc, valloc, memalign, cfree, and free abort with a message to stderr if errors are detected in arguments or in the heap.   If a bad block is encountered, its address and size are included in the message. 

Level 2 Same as level 1, except that the entire heap is examined on every call to malloc, calloc, realloc, valloc, memalign, cfree, and free. 

Malloc_debug returns the previous error diagnostic level.  The default level is 1. 

Malloc_verify attempts to determine if the heap has been corrupted.  It scans all blocks in the heap (both free and allocated) looking for strange addresses or absurd sizes, and also checks for inconsistencies in the free space table.  Malloc_verify returns 1 if all checks pass without error, and otherwise returns 0.  The checks can take a significant amount of time, so it should not be used indiscriminately. 

ERRORS

Malloc, calloc, realloc, valloc, memalign, cfree, and free will set errno if:

EINVAL An invalid argument was given. The value of ptr given to free, cfree, or realloc must be a pointer to a block previously allocated by malloc, calloc, realloc, valloc, or memalign.  The EINVAL condition also occurs if the heap is found to have been corrupted. More detailed information may be obtained by enabling range checks using malloc_debug. 

ENOMEM size bytes of memory could not be allocated. 

FILES

/usr/lib/debug/malloc.o diagnostic versions of malloc, free, etc.

BUGS

Alloca is both machine- and compiler-dependent; its use is discouraged. 

Since realloc accepts a pointer to a block freed since the last call to malloc, calloc, realloc, valloc, or memalign, a degradation of performance results.  The semantics of free should be changed so that the contents of a previously freed block are undefined. 

Sun Release 3.2  —  Last change: 2 August 1985