manpagez: man (manual) pages & more
man malloc(3)
Home | html | info | man
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.  When
     extending a region allocated with calloc(3), realloc(3) does not guaran-
     tee 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.


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 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 <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 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 leaks can be used.

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

     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 likeli-
                                  hood that a program making assumptions about
                                  the contents 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 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 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 <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 conditions, making it
                                  more useful to catch only those errors which
                                  will cause memory corruption.  MallocCorrup-
                                  tionAbort is always set on 64-bit processes.

     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.


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

Mac OS X 10.9.1 - Generated Wed Jan 8 19:38:25 CST 2014