MALLOC(3) BSD Library Functions Manual MALLOC(3)NAME
malloc, calloc, realloc, free — general purpose memory allocation func‐
tions
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include <stdlib.h>
void *
malloc(size_t size);
void *
calloc(size_t number, size_t size);
void *
realloc(void *ptr, size_t size);
void
free(void *ptr);
DESCRIPTION
The malloc() function allocates size bytes of uninitialized memory. The
allocated space is suitably aligned (after possible pointer coercion) for
storage of any type of object.
The calloc() function allocates space for number objects, each size bytes
in length. The result is identical to calling malloc() with an argument
of “number * size”, with the exception that the allocated memory is
explicitly initialized to zero bytes.
The realloc() function changes the size of the previously allocated mem‐
ory referenced by ptr to size bytes. The contents of the memory 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 memory is unde‐
fined. Upon success, the memory referenced by ptr is freed and a pointer
to the newly allocated memory is returned. Note that realloc() may move
the memory allocation, resulting in a different return value than ptr.
If ptr is NULL, the realloc() function behaves identically to malloc()
for the specified size.
The free() function causes the allocated memory referenced by ptr to be
made available for future allocations. If ptr is NULL, no action occurs.
RETURN VALUES
The malloc() and calloc() functions return a pointer to the allocated
memory if successful; otherwise a NULL pointer is returned and errno is
set to ENOMEM.
The realloc() function returns a pointer, possibly identical to ptr, to
the allocated memory if successful; otherwise a NULL pointer is returned,
and errno is set to ENOMEM if the error was the result of an allocation
failure. The realloc() function always leaves the original buffer intact
when an error occurs.
The free() function returns no value.
EXAMPLES
When using malloc(), be careful to avoid the following idiom:
if ((p = malloc(number * size)) == NULL)
err(EXIT_FAILURE, "malloc");
The multiplication may lead to an integer overflow. To avoid this,
calloc() is recommended.
If malloc() must be used, be sure to test for overflow:
if (size && number > SIZE_MAX / size) {
errno = EOVERFLOW;
err(EXIT_FAILURE, "allocation");
}
When using realloc(), one must be careful to avoid the following idiom:
nsize += 50;
if ((p = realloc(p, nsize)) == NULL)
return NULL;
Do not adjust the variable describing how much memory has been allocated
until it is known that the allocation has been successful. This can
cause aberrant program behavior if the incorrect size value is used. In
most cases, the above example will also leak memory. As stated earlier,
a return value of NULL indicates that the old object still remains allo‐
cated. Better code looks like this:
newsize = size + 50;
if ((p2 = realloc(p, newsize)) == NULL) {
if (p != NULL)
free(p);
p = NULL;
return NULL;
}
p = p2;
size = newsize;
SEE ALSOmadvise(2), mmap(2), sbrk(2), alloca(3), atexit(3), getpagesize(3),
memory(3), posix_memalign(3)
For the implementation details, see jemalloc(3).
STANDARDS
The malloc(), calloc(), realloc() and free() functions conform to ISO/IEC
9899:1990 (“ISO C90”).
BSD May 3, 2010 BSD
