MALLOC(3) — C LIBRARY FUNCTIONS

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;

#include <alloca.h>
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. Each returns a NULL pointer if the request cannot be completed (see DIAGNOSTICS).

malloc() returns a pointer to a block of at least size bytes, which is appropriately aligned. A NULL (0) pointer is returned if size is 0 or 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, malloc, 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: 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: 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.

ERRORS

malloc, calloc, realloc, valloc, memalign, cfree, and free() will each fail if one or more of the following are true:

EINVAL The requested allocation size is zero or an invalid argument was specified. The value of ptr passed to free, cfree, or realloc() must be a pointer to a block previously allocated by malloc, calloc, realloc, valloc, or memalign.

EINVAL The allocation 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.

DIAGNOSTICS

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: 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 The routines abort with a message to the standard error 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 the above routines.

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.

FILES

/usr/lib/debug/malloc.o diagnostic versions of malloc() routines.

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.

Museum

Related Articles