This manual page is for Mac OS X version 10.6.3

Reading manual pages

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. If ptr is a NULL pointer, no
     operation is performed.

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.

     MallocStackLoggingDirectory  If set, records stack logs to the directory specified instead of saving
                                  them to the default location (/tmp).

     MallocScribble               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.  Also 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 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 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.

     MallocCorruptionAbort        Similar to MallocErrorAbort but will not abort in out of memory condi-tions, conditions,
                                  tions, making it more useful to catch only those errors which will cause
                                  memory corruption.  MallocCorruptionAbort is always set on 64-bit pro-cesses. processes.
                                  cesses.

     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), malloc_zone_malloc(3), posix_memalign(3),
     libgmalloc(3)

BSD                                             Aug 13, 2008                                             BSD