MALLOC(3C)MALLOC(3C)NAME
malloc, free, realloc, calloc, memalign, valloc - main memory allocator
SYNOPSIS
#include <stdlib.h>
void *malloc (size_t size);
void free (void *ptr);
void *realloc (void *ptr, size_t size);
void *calloc (size_t nelem, size_t elsize);
void *memalign (size_t alignment, size_t size);
void *valloc (size_t size);
DESCRIPTION
malloc and free provide a simple general-purpose memory allocation
package. malloc returns a pointer to a block of at least size bytes
suitably aligned for any use.
The argument to free is a pointer to a block previously allocated by
malloc; after free is performed this space is made available for further
allocation, but its contents are left undisturbed.
Undefined results will occur if the space allocated by malloc is overrun
or if some random value is passed as the argument to free.
malloc allocates the first big enough contiguous reach of free space
found in a circular search from the last block allocated or freed,
coalescing adjacent free blocks as it searches. It calls sbrk [see
brk(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. If no free block of
size bytes is available in the storage arena, then realloc will ask
malloc to enlarge the arena by size bytes and will then move the data to
the new space. If ptr is NULL, realloc behaves like malloc(size). If
size is zero, the storage associated with ptr is freed and realloc
returns the same result as does malloc(0).
calloc allocates space for an array of nelem elements of size elsize.
The space is initialized to zeros.
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 a multiple of alignment. Note that the value
of alignment must be a power of two and must be greater than or equal to
Page 1
MALLOC(3C)MALLOC(3C)
the size of a word, or, for 64 bit objects, the size of a doubleword.
valloc(size) is equivalent to memalign(sysconf(_SC_PAGESIZE),size). For
more information see sysconf(3c).
Each of the allocation routines returns a pointer to space suitably
aligned (after possible pointer coercion) for storage of any type of
object.
SEE ALSObrk(2), sysconf(3c), malloc(3X)DIAGNOSTICS
malloc, realloc, calloc, memalign, and valloc return a NULL pointer if
there is no available memory or if the arena has been detectably
corrupted by storing outside the bounds of a block. When this happens
the block pointed to by ptr may be destroyed.
NOTES
How an application manages its heap can greatly affect the performance of
these routines. For most applications, this set will perform well. For
some applications, the more flexible malloc(3X) package might be more
appropriate.
A SEGV or Bus Error inside the malloc routine is almost certainly caused
by a previous memory overwrite by the user. This is a delayed error which
is caused by a previous overwrite of unallocated memory and is not a bug
in malloc itself.
When called with size of zero, malloc returns a valid pointer to a block
of zero bytes. Storage into a block of length zero will corrupt the
malloc arena and may have serious consequences.
Products, libraries, or commands that provide their own malloc package
must provide all of the entry points listed above, or the normal libc
malloc entry point for the unimplemented routine(s) may be called
instead, leading to corrupted heaps, since it is unlikely that the
internal details of the heap management will be the same. If the malloc
package is also intended to replace malloc(3X), it must also provide the
additional routines listed there.
Page 2
