| MALLOC(3) | Library Functions Manual | MALLOC(3) |
calloc, free,
malloc, realloc,
reallocf, valloc,
aligned_alloc — memory
allocation
#include
<stdlib.h>
void *
calloc(size_t count,
size_t size);
void
free(void *ptr);
void *
malloc(size_t size);
void *
realloc(void *ptr,
size_t size);
void *
reallocf(void *ptr,
size_t size);
void *
valloc(size_t size);
void *
aligned_alloc(size_t alignment,
size_t size);
The
malloc(),
calloc(), valloc(),
realloc(), and reallocf()
functions allocate memory. The allocated memory is aligned such that it can
be used for any data type, including AltiVec- and SSE-related types. The
aligned_alloc() function allocates memory with the
requested alignment. The free() function frees
allocations that were created via the preceding allocation functions.
The
malloc()
function allocates size bytes of memory and returns a
pointer to the allocated memory.
The
calloc()
function contiguously allocates enough space for count
objects that are size bytes of memory each and returns
a pointer to the allocated memory. The allocated memory is filled with bytes
of value zero.
The
valloc()
function allocates size bytes of memory and returns a
pointer to the allocated memory. The allocated memory is aligned on a page
boundary.
The
aligned_alloc()
function allocates size bytes of memory with an
alignment specified by alignment and returns a pointer
to the allocated memory.
The
realloc()
function tries to change the size of the allocation pointed to by
ptr to size, and returns
ptr. If there is not enough room to enlarge the memory
allocation pointed to by ptr,
realloc() creates a new allocation, copies as much
of the old data pointed to by ptr as will fit to the
new allocation, frees the old allocation, and returns a pointer to the
allocated memory. If ptr is
NULL, realloc() is identical
to a call to malloc() for size
bytes. If size is zero and ptr
is not NULL, a new, minimum sized object is
allocated and the original object is freed. When extending a region
allocated with calloc(3), realloc(3) does not guarantee that the additional
memory is also zero-filled.
The
reallocf()
function is identical to the realloc() function,
except that it will free the passed pointer when the requested memory cannot
be allocated. This is a FreeBSD specific API
designed to ease the problems with traditional coding styles for realloc
causing memory leaks in libraries.
The
free()
function deallocates the memory allocation pointed to by
ptr. If
ptr is a NULL pointer, no operation is performed.
If successful, calloc(),
malloc(), realloc(),
reallocf(), valloc(), and
aligned_alloc() functions return a pointer to
allocated memory. If there is an error, they return a
NULL pointer and set errno to
ENOMEM.
In addition, aligned_alloc() returns a
NULL pointer and sets errno to
EINVAL if size is not an
integral multiple of alignment, or if
alignment is not a power of 2 at least as large as
sizeof(void *).
For realloc(), the input pointer is still
valid if reallocation failed. For reallocf(), the
input pointer will have been freed if reallocation failed.
The free() function does not return a
value.
A number of facilities are provided to aid in debugging allocation errors in applications. These facilities are primarily controlled via environment variables. The recognized environment variables and their meanings are documented below.
The following environment variables change the behavior of the allocation-related functions.
MallocDebugReportMallocGuardEdgesMallocDoNotProtectPreludeMallocGuardEdges environment variable is set.MallocDoNotProtectPostludeMallocGuardEdges environment variable is set.MallocStackLoggingSet to "vm" to record only allocation of virtual memory regions allocated by system calls and mach traps, such as by mmap(1)
Set to "malloc" to record only allocations via malloc(3) and related interfaces, not virtual memory regions.
Set to "lite" to record current allocations only, not history. These are recorded by in-memory data structures, instead of an on-disk log.
MallocStackLoggingNoCompactmalloc_history program.MallocStackLoggingDirectoryMallocScribbleMallocCheckHeapStart
<s>MallocCheckHeapEach. If
MallocCheckHeapStart is set but
MallocCheckHeapEach is not specified, the default
check repetition is 1000.MallocCheckHeapEach
<n>MallocCheckHeapEach is only meaningful if
MallocCheckHeapStart is also set.MallocCheckHeapSleep
<t>MallocCheckHeapStart is set and a heap
corruption is detected. The default is 100 seconds. Setting this to zero
means not to sleep at all. Setting this to a negative number means to
sleep (for the positive number of seconds) only the very first time a heap
corruption is detected.MallocCheckHeapAbort
<b>MallocCheckHeapStart is set and this is set
to a non-zero value, causes abort(3)
to be called if a heap corruption is detected, instead of any
sleeping.MallocErrorAbortMallocCorruptionAbortMallocErrorAbort but will not abort in
out of memory conditions, making it more useful to catch only those errors
which will cause memory corruption. MallocCorruptionAbort is always set on
64-bit processes.MallocZeroOnFreeMallocZeroOnFree can be set to 0
or 1 to explicitly disable or enable this zeroing behavior to aid in
diagnosing such bugs. Support for this environment variable will
eventually be removed, and it should not be used by shipping
software.MallocCheckZeroOnFreeCorruptionMallocHelpleaks(1), malloc_history(1), abort(3), malloc_size(3), malloc_zone_malloc(3), posix_memalign(3), libgmalloc(3)
| August 13, 2008 | macOS 15.0 |