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 guarantee 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 realloca-
     tion 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 mak-
				  ing 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 mem-
				  ory 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 speci-
				  fied 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.  Set-
				  ting 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 conditions, making it more useful to catch only
				  those errors which will cause memory corruption.  MallocCorruptionAbort is always set on 64-bit processes.

     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