NAME
malloc,
calloc,
realloc,
free —
general purpose memory
allocation functions
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 memory 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 undefined. 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. If
size is 0, either
NULL
or a
pointer that can be safely passed to
free(3) is returned.
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,
reallocarr(3) 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");
}
The above test is not sufficient in all cases. For example, multiplying ints
requires a different set of checks:
int num, size;
...
/* Avoid invalid requests */
if (size < 0 || num < 0)
errc(1, EOVERFLOW, "overflow");
/* Check for signed int overflow */
if (size && num > INT_MAX / size)
errc(1, EOVERFLOW, "overflow");
if ((p = malloc(size * num)) == NULL)
err(1, "malloc");
Assuming the implementation checks for integer overflow as
NetBSD does, it is much easier to use
calloc() or
reallocarr(3).
The above examples could be simplified to:
ptr = NULL;
if ((e = reallocarr(&ptr, num, size)))
errx(1, "reallocarr", strerror(e));
or at the cost of initialization:
if ((p = calloc(num, size)) == NULL)
err(1, "calloc");
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
allocated. 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 ALSO
madvise(2),
mmap(2),
sbrk(2),
aligned_alloc(3),
alloca(3),
atexit(3),
getpagesize(3),
memory(3),
posix_memalign(3),
reallocarr(3)
For the implementation details, see
jemalloc(3).
STANDARDS
The
malloc(),
calloc(),
realloc() and
free() functions conform to
ISO/IEC 9899:1990 (“ISO C90”).
HISTORY
A
free() internal kernel function and a predecessor to
malloc(),
alloc(), first appeared in
Version 1 AT&T UNIX. The C Library functions
alloc() and
free() appeared in
Version 6 AT&T UNIX. The functions
malloc(),
calloc(), and
realloc() first appeared in
Version 7
AT&T UNIX.
A new implementation by Chris Kingsley was introduced in
4.2BSD, followed by a complete rewrite by Poul-Henning
Kamp (“phk's malloc” or “new malloc”) which appeared
in
FreeBSD 2.2 and was included in
NetBSD 1.5 and
OpenBSD 2.0.
These implementations were all
sbrk(2) based.
The
jemalloc(3) allocator became
the default system allocator first in
FreeBSD 7.0 and
then in
NetBSD 5.0.