MALLOC(3) BSD Library Functions Manual MALLOC(3)
NAME
calloc, free, malloc, realloc, reallocf, valloc -- memory allocation
SYNOPSIS
#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);
DESCRIPTION
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 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 mem-ory memory
ory 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 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 allo-cation, allocation,
cation, 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.
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.
RETURN VALUES
If successful, calloc(), malloc(), realloc(), reallocf(), and valloc() functions return a pointer to
allocated memory. If there is an error, they return a NULL pointer and set errno to ENOMEM.
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.
DEBUGGING ALLOCATION ERRORS
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.
ENVIRONMENT
The following environment variables change the behavior of the allocation-related functions.
MallocLogFile <f> Create/append messages to the given file path <f> instead of writing to
the standard error.
MallocGuardEdges If set, add a guard page before and after each large block.
MallocDoNotProtectPrelude If set, do not add a guard page before large blocks, even if the
MallocGuardEdges environment variable is set.
MallocDoNotProtectPostlude If set, do not add a guard page after large blocks, even if the
MallocGuardEdges environment variable is set.
MallocStackLogging If set, record all stacks, so that tools like leaks can be used.
MallocStackLoggingNoCompact If set, record all stacks in a manner that is compatible with the
malloc_history program.
MallocPreScribble If set, fill memory that has been allocated with 0xaa bytes. This
increases the likelihood that a program making assumptions about the con-tents contents
tents of freshly allocated memory will fail.
MallocScribble If set, fill memory that has been deallocated with 0x55 bytes. This
increases the likelihood that a program will fail due to accessing memory
that is no longer allocated.
MallocCheckHeapStart <s> If set, specifies the number of allocations <s> to wait before begining
periodic heap checks every <n> as specified by MallocCheckHeapEach. If
MallocCheckHeapStart is set but MallocCheckHeapEach is not specified, the
default check repetition is 1000.
MallocCheckHeapEach <n> If set, run a consistency check on the heap every <n> operations.
MallocCheckHeapEach is only meaningful if MallocCheckHeapStart is also
set.
MallocCheckHeapSleep <t> Sets the number of seconds to sleep (waiting for a debugger to attach)
when 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> When 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.
MallocErrorAbort If set, causes abort(3) to be called if an error was encountered in
malloc(3) or free(3) , such as a calling free(3) on a pointer previously
freed.
MallocHelp If set, print a list of environment variables that are paid heed to by the
allocation-related functions, along with short descriptions. The list
should correspond to this documentation.
DIAGNOSTIC MESSAGES
SEE ALSO
leaks(1), malloc_history(1), abort(3), malloc_size(3) /Developer/ADC Reference
Library/releasenotes/DeveloperTools/MallocOptions.html
BSD May 23, 2006 BSD
|