MALLOC
Section: Linux Programmer's Manual (3) Updated: 2009-01-13 Index
Return to Main Contents
NAME
calloc, malloc, free, realloc - Allocate and free dynamic memory
SYNOPSIS
#include <stdlib.h>
void *calloc(size_t nmemb, size_t size);
void *malloc(size_t size);
void free(void *ptr);
void *realloc(void *ptr, size_t size);
DESCRIPTION
calloc()
allocates memory for an array of
nmemb
elements of
size
bytes each and returns a pointer to the allocated memory.
The memory is set to zero.
If
nmemb
or
size
is 0, then
calloc()
returns either NULL,
or a unique pointer value that can later be successfully passed to
free().
malloc()
allocates
size
bytes and returns a pointer to the allocated memory.
The memory is not cleared.
If
size
is 0, then
malloc()
returns either NULL,
or a unique pointer value that can later be successfully passed to
free().
free()
frees the memory space pointed to by
ptr,
which must have been returned by a previous call to
malloc(),
calloc()
or
realloc().
Otherwise, or if
free(ptr)
has already been called before, undefined behavior occurs.
If
ptr
is NULL, no operation is performed.
realloc()
changes the size of the memory block pointed to by
ptr
to
size
bytes.
The contents will be unchanged to the minimum of the old and new sizes;
newly allocated memory will be uninitialized.
If
ptr
is NULL, then the call is equivalent to
malloc(size),
for all values of
size;
if
size
is equal to zero,
and
ptr
is not NULL, then the call is equivalent to
free(ptr).
Unless
ptr
is NULL, it must have been returned by an earlier call to
malloc(),
calloc()
or
realloc().
If the area pointed to was moved, a
free(ptr)
is done.
RETURN VALUE
For
calloc()
and
malloc(),
return a pointer to the allocated memory, which is suitably
aligned for any kind of variable.
On error, these functions return NULL.
NULL may also be returned by a successful call to
malloc()
with a
size
of zero,
or by a successful call to
calloc()
with
nmemb
or
size
equal to zero.
free()
returns no value.
realloc()
returns a pointer to the newly allocated memory, which is suitably
aligned for any kind of variable and may be different from
ptr,
or NULL if the request fails.
If
size
was equal to 0, either NULL or a pointer suitable to be passed to
free()
is returned.
If
realloc()
fails the original block is left untouched; it is not freed or moved.
CONFORMING TO
C89, C99.
NOTES
Normally,
malloc()
allocates memory from the heap, and adjusts the size of the heap
as required, using
sbrk(2).
When allocating blocks of memory larger than
MMAP_THRESHOLD
bytes, the glibc
malloc()
implementation allocates the memory as a private anonymous mapping using
mmap(2).
MMAP_THRESHOLD
is 128 kB by default, but is adjustable using
mallopt(3).
Allocations performed using
mmap(2)
are unaffected by the
RLIMIT_DATA
resource limit (see
getrlimit(2)).
The Unix98 standard requires
malloc(),
calloc(),
and
realloc()
to set
errno
to
ENOMEM
upon failure.
Glibc assumes that this is done
(and the glibc versions of these routines do this); if you
use a private malloc implementation that does not set
errno,
then certain library routines may fail without having
a reason in
errno.
Crashes in
malloc(),
calloc(),
realloc(),
or
free()
are almost always related to heap corruption, such as overflowing
an allocated chunk or freeing the same pointer twice.
Recent versions of Linux libc (later than 5.4.23) and glibc (2.x)
include a
malloc()
implementation which is tunable via environment variables.
When
MALLOC_CHECK_
is set, a special (less efficient) implementation is used which
is designed to be tolerant against simple errors, such as double
calls of
free()
with the same argument, or overruns of a single byte (off-by-one
bugs).
Not all such errors can be protected against, however, and
memory leaks can result.
If
MALLOC_CHECK_
is set to 0, any detected heap corruption is silently ignored;
if set to 1, a diagnostic message is printed on stderr;
if set to 2,
abort(3)
is called immediately;
if set to 3, a diagnostic message is printed on stderr
and the program is aborted.
Using a nonzero
MALLOC_CHECK_
value can be useful because otherwise
a crash may happen much later, and the true cause for the problem
is then very hard to track down.
BUGS
By default, Linux follows an optimistic memory allocation strategy.
This means that when
malloc()
returns non-NULL there is no guarantee that the memory really
is available.
This is a really bad bug.
In case it turns out that the system is out of memory,
one or more processes will be killed by the infamous OOM killer.
In case Linux is employed under circumstances where it would be
less desirable to suddenly lose some randomly picked processes,
and moreover the kernel version is sufficiently recent,
one can switch off this overcommitting behavior using a command like:
# echo 2 > /proc/sys/vm/overcommit_memory
See also the kernel Documentation directory, files
vm/overcommit-accounting
and
sysctl/vm.txt.
SEE ALSO
brk(2),
mallopt(3),
mmap(2),
alloca(3),
posix_memalign(3)
COLOPHON
This page is part of release 3.27 of the Linux
man-pages
project.
A description of the project,
and information about reporting bugs,
can be found at
http://www.kernel.org/doc/man-pages/.
Index
- NAME
-
- SYNOPSIS
-
- DESCRIPTION
-
- RETURN VALUE
-
- CONFORMING TO
-
- NOTES
-
- BUGS
-
- SEE ALSO
-
- COLOPHON
-
This document was created by
man2html,
using the manual pages.
|