Mac OS X Manual Page For malloc(3) (original) (raw)
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 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 **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.
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 environ-ment environment ment variables. The recognized environment variables and their meanings are documented below.
ENVIRONMENT The following environment variables change the behavior of the alloca-tion-related allocation-related tion-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 envi-ronment environment
ronment variable is set.
MallocDoNotProtectPostlude If set, do not add a guard page after large
blocks, even if the MallocGuardEdges envi-ronment environment
ronment 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** pro-gram. program.
gram.
MallocPreScribble If set, fill memory that has been allocated
with 0xaa bytes. This increases the likeli-hood likelihood
hood that a program making assumptions about
the contents of freshly allocated memory
will fail.
MallocScribble If set, fill memory that has been deallo-cated deallocated
cated with 0x55 bytes. This increases the
likelihood that a program will fail due to
accessing memory that is no longer allo-cated. allocated.
cated.
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 cor-ruption corruption
ruption 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 num-ber number
ber 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)](abort.3.html#//apple%5Fref/doc/man/3/abort) to
be called if a heap corruption is detected,
instead of any sleeping.
MallocErrorAbort If set, causes [abort(3)](abort.3.html#//apple%5Fref/doc/man/3/abort) to be called if an
error was encountered in malloc(3) or
[free(3)](free.3.html#//apple%5Fref/doc/man/3/free) , such as a calling [free(3)](free.3.html#//apple%5Fref/doc/man/3/free) on a
pointer previously freed.
MallocHelp If set, print a list of environment vari-ables variables
ables that are paid heed to by the alloca-tion-related allocation-related
tion-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