NAME
malloc
, calloc
,
realloc
, free
—
general purpose memory allocation
functions
LIBRARY
library “libc”
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
Themalloc
()
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.