malloc, free, realloc, calloc, mallopt, mallinfo, mallinfo_heap, alloca, valloc, or posix_memalign Subroutine

Edit online

Purpose

Provides a complete set of memory allocation, reallocation, deallocation, and heap management tools.

Libraries

Berkeley Compatibility Library (libbsd.a)

Standard C Library (libc.a)

Malloc Subsystem APIs

malloc

Syntax (malloc)

#include <stdlib.h>
void *malloc (Size)
size_t Size;

Description (malloc)

The malloc subroutine returns a pointer to a block of memory of at least the number of bytes specified by the Size parameter. The block is aligned so that it can be used for any type of data. Undefined results occur if the space assigned by the malloc subroutine is overrun.

Parameters (malloc)

Item Description
Size Specifies the size, in bytes, of memory to allocate.

Return Values (malloc)

Upon successful completion, the malloc subroutine returns a pointer to space suitably aligned for the storage of any type of object. If the size requested is 0, malloc returns NULL in normal circumstances. However, if the program was compiled with the defined _LINUX_SOURCE_COMPAT macro, malloc returns a valid pointer to a space of size 0.

If the request cannot be satisfied for any reason, the malloc subroutine returns NULL.

Error Codes (malloc)

Item Description
ENOMEM Insufficient storage space is available to service the request.

free

Syntax (free)

#include <stdlib.h>
void free (Pointer)
void * Pointer;

Description (free)

The free subroutine deallocates a block of memory previously allocated by the malloc subsystem. Undefined results occur if the Pointer parameter is not an address that has previously been allocated by the malloc subsystem, or if the Pointer parameter has already been deallocated. If the Pointer parameter is NULL, no action occurs.

Parameters (free)

Item Description
Pointer Specifies a pointer to space previously allocated by the malloc subsystem.

Return Values (free)

The free subroutine does not return a value. Upon successful completion with nonzero arguments, the realloc subroutine returns a pointer to the (possibly moved) allocated space. If the Size parameter is 0 and the Pointer parameter is not null, no action occurs.

Error Codes (free)

The free subroutine does not set errno.

realloc (free)

Syntax (realloc)

#include <stdlib.h>
void *realloc (Pointer, Size)
void *Pointer;
size_t Size;

Description (realloc)

The realloc subroutine changes the size of the memory object pointed to by the Pointer parameter to the number of bytes specified by the Size parameter. The Pointer must point to an address returned by a malloc subsystem allocation routine, and must not have been previously deallocated. Undefined results occur if Pointer does not meet these criteria.

The contents of the memory object remain unchanged up to the lesser of the old and new sizes. If the current memory object cannot be enlarged to satisfy the request, the realloc subroutine acquires a new memory object and copies the existing data to the new space. The old memory object is then freed. If no memory object can be acquired to accommodate the request, the object remains unchanged.

If the Pointer parameter is null, the realloc subroutine is equivalent to a malloc subroutine of the same size.

If the Size parameter is 0 and the Pointer parameter is not null, the realloc subroutine is equivalent to a free subroutine of the same size.

Parameters (realloc)

Item Description
Pointer Specifies a Pointer to space previously allocated by the malloc subsystem.
Size Specifies the new size, in bytes, of the memory object.

Return Values (realloc)

Upon successful completion with nonzero arguments, the realloc subroutine returns a pointer to the (possibly moved) allocated space. If the Size parameter is 0 and the Pointer parameter is not null, return behavior is equivalent to that of the free subroutine. If the Pointer parameter is null and the Size parameter is not zero, return behavior is equivalent to that of the malloc subroutine.

Error Codes (realloc)

Item Description
ENOMEM Insufficient storage space is available to service the request.

calloc

Syntax (calloc)

#include <stdlib.h>
void *calloc (NumberOfElements, ElementSize)
size_t NumberOfElements;
size_t ElementSize;

Description (calloc)

The calloc subroutine allocates space for an array containing the NumberOfElements objects. The ElementSize parameter specifies the size of each element in bytes. After the array is allocated, all bits are initialized to 0.

The order and contiguity of storage allocated by successive calls to the calloc subroutine is unspecified. The pointer returned points to the first (lowest) byte address of the allocated space. The allocated space is aligned so that it can be used for any type of data. Undefined results occur if the space assigned by the calloc subroutine is overrun.

Parameters (calloc)

Item Description
NumberOfElements Specifies the number of elements in the array.
ElementSize Specifies the size, in bytes, of each element in the array.

Return Values (calloc)

Upon successful completion, the calloc subroutine returns a pointer to the allocated, zero-initialized array. If the size requested is 0, the calloc subroutine returns NULL in normal circumstances. However, if the program was compiled with the macro _LINUX_SOURCE_COMPAT defined, the calloc subroutine returns a valid pointer to a space of size 0.

If the request cannot be satisfied for any reason, the calloc subroutine returns NULL.

Error Codes (calloc)

Item Description
ENOMEM Insufficient storage space is available to service the request.

mallopt

Syntax (mallopt)

#include <malloc.h>
#include <stdlib.h>
int mallopt (Command, Value)
int Command;
int Value;

Description (mallopt)

The mallopt subroutine is provided for source-level compatibility with the System V malloc subroutine. The mallopt subroutine supports the following commands:
Table 1. Commands and effects
Command Value Effect
M_MXFAST 0 If called before any other malloc subsystem subroutine, this enables the Default allocation policy for the process.
M_MXFAST 1 If called before any other malloc subsystem subroutine, this enables the 3.1 allocation policy for the process.
M_DISCLAIM 0 If called while the Default Allocator is enabled, all free memory in the process heap is disclaimed.
M_MALIGN N If called at runtime, sets the default malloc allocation alignment to the value N. The N value must be a power of 2 (greater than or equal to the size of a pointer).

Parameters (mallopt)

Item Description
Command Specifies the mallopt command to be executed.
Value Specifies the size of each element in the array.

Return Values (mallopt)

Upon successful completion, the mallopt subroutine returns 0. Otherwise, 1 is returned. If an invalid alignment is requested (one that is not a power of 2), mallopt fails with a return value of 1, although subsequent calls to malloc are unaffected and continue to provide the alignment value from before the failed mallopt call.

Error Codes (mallopt)

The mallopt subroutine does not set errno.

mallinfo

Syntax (mallinfo)

#include <malloc.h>
#include <stdlib.h>
struct mallinfo mallinfo();

Description (mallinfo)

The mallinfo subroutine can be used to obtain information about the heap managed by the malloc subsystem.

Return Values (mallinfo)

The mallinfo subroutine returns a structure of type struct mallinfo, filled in with relevant information and statistics about the heap. The contents of this structure can be interpreted using the definition of struct mallinfo in the /usr/include/malloc.h file.

Error Codes (mallinfo)

The mallinfo subroutine does not set errno.

mallinfo_heap

Syntax (mallinfo_heap)

#include <malloc.h>
#include <stdlib.h>
struct mallinfo_heap mallinfo_heap (Heap)
int Heap;

Description (mallinfo_heap)

In a multiheap context, the mallinfo_heap subroutine can be used to obtain information about a specific heap managed by the malloc subsystem.

Parameters (mallinfo_heap)

Item Description
Heap Specifies which heap to query.

Return Values (mallinfo_heap)

mallinfo_heap returns a structure of type struct mallinfo_heap, filled in with relevant information and statistics about the heap. The contents of this structure can be interpreted using the definition of struct mallinfo_heap in the /usr/include/malloc.h file.

Error Codes (mallinfo_heap)

The mallinfo_heap subroutine does not set errno.

alloca

Syntax (alloca)

#include <stdlib.h>
char *alloca (Size)
int Size;

Description (alloca)

The alloca subroutine returns a pointer to a block of memory of at least the number of bytes specified by the Size parameter. The space is allocated from the stack frame of the caller and is automatically freed when the calling subroutine returns.

If the alloca subroutine is used in code compiled with the IBM® XL C for AIX® compiler, #pragma alloca must be added to the source code before referencing the alloca subroutine. Alternatively, you can add the -ma compiler flag or the <alloca.h> header file.

Parameters (alloca)

Item Description
Size Specifies the size, in bytes, of memory to allocate.

Return Values (alloca)

The alloca subroutine returns a pointer to space of the requested size.

Error Codes (alloca)

The alloca subroutine does not set errno.

valloc

Syntax (valloc)

#include <stdlib.h>
void *valloc (Size)
size_t Size;

Description (valloc)

The valloc subroutine is supported as a compatibility interface in the Berkeley Compatibility Library (libbsd.a), as well as in libc.a. The valloc subroutine has the same effect as malloc, except that the allocated memory is aligned to a multiple of the value returned by sysconf (_ SC_PAGESIZE).

Parameters (valloc)

Item Description
Size Specifies the size, in bytes, of memory to allocate.

Return Values (valloc)

Upon successful completion, the valloc subroutine returns a pointer to a memory object that is Size bytes in length, aligned to a page-boundary. Undefined results occur if the space assigned by the valloc subroutine is overrun.

If the request cannot be satisfied for any reason, valloc returns NULL.

Error Codes (valloc)

Item Description
ENOMEM Insufficient storage space is available to service the request.

posix_memalign

Syntax (posix_memalign)

#include <stdlib.h>
int posix_memalign(void **Pointer2Pointer, Align, Size)
void ** Pointer2Pointer;
size_t Align;
size_t Size;

Description (posix_memalign)

The posix_memalign subroutine allocates Size bytes of memory aligned on a boundary specified by Align. The address of this memory is stored in Pointer2Pointer.

Parameters (posix_memalign)

Item Description
Pointer2Pointer Specifies the location in which the address should be copied.
Align Specifies the alignment of the allocated memory, in bytes. The Align parameter must be a power-of-two multiple of the size of a pointer.
Size Specifies the size, in bytes, of memory to allocate.

Return Values (posix_memalign)

Upon successful completion, posix_memalign returns 0. Otherwise, an error number is returned to indicate the error.

Error Codes (posix_memalign)

Item Description
EINVAL The value of Align is not a power-of-two multiple of the size of a pointer.
ENOMEM Insufficient storage space is available to service the request.