MALLOC(3) BSD Library Functions Manual MALLOC(3)

NAME
     mmaalllloocc, ccaalllloocc, vvaalllloocc, rreeaalllloocc, rreeaallllooccff, ffrreeee, mmaallllooccssiizzee,
     mmaallllooccggooooddssiizzee - memory allocation

SYNOPSIS
     ##iinncclluuddee <>

     void *
     mmaalllloocc(sizet size);

     void *
     ccaalllloocc(sizet count, sizet size);

     void *
     vvaalllloocc(sizet size);

     void *
     rreeaalllloocc(void *ptr, sizet size);

     void *
     rreeaallllooccff(void *ptr, sizet size);

     void
     ffrreeee(void *ptr);

     sizet
     mmaallllooccssiizzee(void *ptr);

     sizet
     mmaallllooccggooooddssiizzee(sizet size);

DESCRIPTION
     The mmaalllloocc(), ccaalllloocc(), vvaalllloocc(), rreeaalllloocc(), and rreeaallllooccff() functions
     allocate memory.  The allocated memory is aligned such that it can be
     used for any data type, including AltiVec-related types.  The ffrreeee()
     function frees allocations that were created via the preceding allocation
     functions.  The mmaallllooccssiizzee() and mmaallllooccggooooddssiizzee() functions provide
     information related to the amount of padding space at the end of alloca-
     tions.

     The mmaalllloocc() function allocates size bytes of memory and returns a
     pointer to the allocated memory.  mmaalllloocc() returns a NULL pointer if
     there is an error.

     The ccaalllloocc() 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.  ccaalllloocc() returns a NULL pointer if there is an error.

     The vvaalllloocc() function allocates size bytes of memory and returns a
     pointer to the allocated memory.  The allocated memory is aligned on a
     page boundary.  vvaalllloocc() returns a NULL pointer if there is an error.

     The rreeaalllloocc() function tries to change the size of the allocation pointed
     to by ptr to size, and return ptr.  If there is not enough room to
     enlarge the memory allocation pointed to by ptr, rreeaalllloocc() 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.  rreeaalllloocc() returns a NULL pointer if there is an
     error, and the allocation pointed to by ptr is still valid.

     The rreeaallllooccff() function is identical to the rreeaalllloocc() 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 ffrreeee() function deallocates the memory allocation pointed to by ptr.

     The mmaallllooccssiizzee() function returns the size of the memory block that
     backs the allocation pointed to by ptr.  The memory block size is always
     at least as large as the allocation it backs, and may be larger.

     The mmaallllooccggooooddssiizzee() function rounds size up to a value that the allo-
     cator implementation can allocate without adding any padding and returns
     that rounded up value.

RETURN VALUES
     If successful, the mmaalllloocc(), ccaalllloocc(), and vvaalllloocc() functions return a
     pointer to allocated memory.  If there is an error, they return a NULL
     pointer and set errno to ENOMEM.

     If successful, the rreeaalllloocc() and rreeaallllooccff() functions return a pointer to
     allocated memory.  If there is an error, it returns a NULL pointer and
     sets errno to ENOMEM.

     The ffrreeee() function does not return a value.

DDEEBBUUGGGGIINNGG AALLLLOOCCAATTIIOONN EERRRROORRSS
     A number of facilities are provided to aid in debugging allocation errors
     in applications.  These facilities are primarily controlled via environ-
     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 functions.

     MallocLogFile             Create/append messages to the given file
                                  path  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 variable is set.

     MallocDoNotProtectPostlude   If set, do not add a guard page after large
                                  blocks, even if the MallocGuardEdges envi-
                                  ronment variable is set.

     MallocStackLogging           If set, record all stacks, so that tools
                                  like lleeaakkss can be used.

     MallocStackLoggingNoCompact  If set, record all stacks in a manner that
                                  is compatible with the mmaalllloocchhiissttoorryy pro-
                                  gram.

     MallocPreScribble            If set, fill memory that has been allocated
                                  with 0xaa bytes.  This increases the likeli-
                                  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 with 0x55 bytes.  This increases the
                                  likelihood that a program will fail due to
                                  accessing memory that is no longer allo-
                                  cated.

     MallocCheckHeapStart      If set, specifies the number of allocations
                                   to wait before begining periodic heap
                                  checks every  as specified by
                                  MallocCheckHeapEach.  If
                                  MallocCheckHeapStart is set but
                                  MallocCheckHeapEach is not specified, the
                                  default check repetition is 1000.

     MallocCheckHeapEach       If set, run a consistency check on the heap
                                  every  operations.  MallocCheckHeapEach
                                  is only meaningful if MallocCheckHeapStart
                                  is also set.

     MallocCheckHeapSleep      Sets the number of seconds to sleep (waiting
                                  for a debugger to attach) when
                                  MallocCheckHeapStart is set and a heap cor-
                                  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 of seconds) only the very first time a
                                  heap corruption is detected.

     MallocCheckHeapAbort      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.

     MallocBadFreeAbort        If set to a non-zero value, causes abort(3)
                                  to be called if the pointer passed to
                                  free(3) was previously freed, or is other-
                                  wise illegal.

     MallocHelp                   If set, print a list of environment vari-
                                  ables that are paid heed to by the alloca-
                                  tion-related functions, along with short
                                  descriptions.  The list should correspond to
                                  this documentation.

DDIIAAGGNNOOSSTTIICC MMEESSSSAAGGEESS
SEE ALSO
     leaks(1), mallochistory(1), abort(3)
     /Developer/Documentation/ReleaseNotes/DeveloperTools/MallocOptions.html

BSD                            November 21, 2002                           BSD