CodeCogs

memory allocation

You're viewing an older version of this page (#3275). View the current version.

NAME

malloc, calloc, valloc, realloc, reallocf, free, malloc_size, malloc_good_size

INTERFACE

#include <stdlib.h> void malloc ( size_t size ) void calloc ( size_t count, size_t size ) void valloc ( size_t size ) void realloc ( void *ptr, size_t size ) void reallocf ( void *ptr, size_t size ) void free ( void *ptr ) size_t malloc_size ( void *ptr ) size_t malloc_good_size ( 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-related types. The free function frees allocations that were created via the preceding allocation functions. The malloc_size and malloc_good_size functions provide information related to the amount of padding space at the end of allocations. \n \n The malloc function allocates \c size bytes of memory and returns a pointer to the allocated memory. malloc returns a NULL pointer if there is an error. \n \n The calloc function contiguously allocates enough space for \c count objects that are \c size bytes of memory each and returns a pointer to the allocated memory. The allocated memory is filled with bytes of value zero. calloc returns a NULL pointer if there is an error. \n \n The valloc function allocates \c size bytes of memory and returns a pointer to the allocated memory. The allocated memory is aligned on a page boundary. valloc returns a NULL pointer if there is an error. \n \n The realloc function tries to change the size of the allocation pointed to by \c ptr to \c size, and return \c ptr. If there is not enough room to enlarge the memory allocation pointed to by \c ptr, realloc creates a new allocation, copies as much of the old data pointed to by \c ptr as will fit to the new allocation, frees the old allocation, and returns a pointer to the allocated memory. realloc returns a NULL pointer if there is an error, and the allocation pointed to by \c ptr is still valid. \n \n 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. \n \n The free function deallocates the memory allocation pointed to by \c ptr. \n \n The malloc_size function returns the size of the memory block that backs the allocation pointed to by \c ptr. The memory block size is always at least as large as the allocation it backs, and may be larger. \n \n The malloc_good_size function rounds \c size up to a value that the allocator implementation can allocate without adding any padding and returns that rounded up value.

RETURN VALUES

If successful, the malloc , calloc , and valloc functions return a pointer to allocated memory. If there is an error, they return a NULL pointer and set errno to ENOMEM. \n \n If successful, the realloc and reallocf functions return a pointer to allocated memory. If there is an error, it returns a NULL pointer and sets errno to ENOMEM. \n \n 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. <table cellspacing="0" class="refpage" style="margin-left:25px"> <tr> <td valign="top" nowrap> MallocLogFile <f> </td> <td valign="top"> Create/append messages to the given file path \c <f> instead of writing to the standard error. </td> </tr> <tr> <td valign="top" nowrap> MallocGuardEdges </td> <td valign="top"> If set, add a guard page before and after each large block. </td> </tr> <tr> <td valign="top" nowrap> MallocDoNotProtectPrelude </td> <td valign="top"> If set, do not add a guard page before large blocks, even if the MallocGuardEdges environment variable is set. </td> </tr> <tr> <td valign="top" nowrap> MallocDoNotProtectPostlude </td> <td valign="top"> If set, do not add a guard page after large blocks, even if the MallocGuardEdges environment variable is set. </td> </tr> <tr> <td valign="top" nowrap> MallocStackLogging </td> <td valign="top"> If set, record all stacks, so that tools like leaks can be used. </td> </tr> <tr> <td valign="top" nowrap> MallocStackLoggingNoCompact </td> <td valign="top"> If set, record all stacks in a manner that is compatible with the malloc_history program. </td> </tr> <tr> <td valign="top" nowrap> MallocPreScribble </td> <td valign="top"> If set, fill memory that has been allocated with 0xaa bytes. This increases the likelihood that a program making assumptions about the contents of freshly allocated memory will fail. </td> </tr> <tr> <td valign="top" nowrap> MallocScribble </td> <td valign="top"> 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. </td> </tr> <tr> <td valign="top" nowrap> MallocCheckHeapStart <s> </td> <td valign="top"> If set, specifies the number of allocations \c <s> to wait before begining periodic heap checks every \c <n> as specified by MallocCheckHeapEach. If MallocCheckHeapStart is set but MallocCheckHeapEach is not specified, the default check repetition is 1000. </td> </tr> <tr> <td valign="top" nowrap> MallocCheckHeapEach <n> </td> <td valign="top"> If set, run a consistency check on the heap every \c <n> operations. MallocCheckHeapEach is only meaningful if MallocCheckHeapStart is also set. </td> </tr> <tr> <td valign="top" nowrap> MallocCheckHeapSleep <t> </td> <td valign="top"> 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. </td> </tr> <tr> <td valign="top" nowrap> MallocCheckHeapAbort </td> <td valign="top"> 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. </td> </tr> <tr> <td valign="top" nowrap> MallocBadFreeAbort </td> <td valign="top"> If set to a non-zero value, causes abort (3) to be called if the pointer passed to reference:free (3) was previously freed, or is otherwise illegal. </td> </tr> <tr> <td valign="top" nowrap> MallocHelp </td> <td valign="top"> 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. </td> </tr> </table>

malloc