[ Bottom of Page | Previous Page | Next Page | Contents | Index | Library Home | Legal | Search ]

Technical Reference: Base Operating System and Extensions, Volume 1

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

Purpose

Provides a memory allocator.

Libraries

Berkeley Compatibility Library (libbsd.a)

Standard C Library (libc.a)

Syntax

#include <stdlib.h>

void *malloc (Size)
size_t Size;


void free (Pointer)
void *Pointer;

void *realloc (Pointer, Size) 
void *Pointer; 
size_t Size;

void *calloc (NumberOfElements, ElementSize)
size_t NumberOfElements;
size_t ElementSize;

char *alloca (Size) 
int Size;

void *valloc (Size)
size_t Size;

#include <malloc.h> 
#include <stdlib.h>

int mallopt (Command, Value)
int Command;
int Value;

struct mallinfo mallinfo( )
struct mallinfo_heap mallinfo_heap (Heap)
int Heap;

Description

The malloc and free subroutines provide a general-purpose memory allocation package.

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.

The free subroutine frees a block of memory previously allocated by the malloc subroutine. Undefined results occur if the Pointer parameter is not a valid pointer. If the Pointer parameter is a null value, no action will occur.

The realloc subroutine changes the size of the block of memory pointed to by the Pointer parameter to the number of bytes specified by the Size parameter and returns a new pointer to the block. The pointer specified by the Pointer parameter must have been created with the malloc, calloc, or realloc subroutines and not been deallocated with the free or realloc subroutines. Undefined results occur if the Pointer parameter is not a valid pointer

The contents of the block returned by the realloc subroutine remain unchanged up to the lesser of the old and new sizes. If a large enough block of memory is not available, the realloc subroutine acquires a new area and moves the data to the new space. The realloc subroutine supports the old realloc protocol wherein the realloc protocol returns a pointer to a previously freed block of memory if that block satisfies the realloc request. The realloc subroutine searches a list, maintained by the free subroutine, of the ten most recently freed blocks of memory. If the list does not contain a memory block that satisfies the specified Size parameter, the realloc subroutine calls the malloc subroutine. This list is cleared by calls to the malloc, calloc, valloc, or realloc subroutines.

The calloc subroutine allocates space for an array with the number of elements specified by the NumberOfElements parameter. The ElementSize parameter specifies in bytes each element, and initializes space to zeros. 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 valloc subroutine, found in many BSD systems, is supported as a compatibility interface in the Berkeley Compatibility Library (libbsd.a). The valloc subroutine calls the malloc subroutine and automatically page-aligns requests that are greater than one page. The only difference between the valloc subroutine in the libbsd.a library and the one in the standard C library (described above) is in the value returned when the size parameter is zero.

The alloca subroutine allocates the number of bytes of space specified by the Size parameter in the stack frame of the caller. This space is automatically freed when the subroutine that called the alloca subroutine returns to its caller.

If alloca is used in the code and compiled with the C++ compiler, #pragma alloca would also have to be added before the usage of alloca in the code. Alternatively, the tag -ma would have to be used while compiling the code.

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

The mallopt and mallinfo subroutines are provided for source-level compatibility with the System V malloc subroutine. Nothing done with the mallopt subroutine affects how memory is allocated by the system, unless the M_MXFAST option is used..

The mallinfo subroutine can be used to obtain information about the heap managed by the malloc subroutine. Refer to the malloc.h file for details of the mallinfo structure.

Note
When MALLOCTYPE is set to buckets and the memory request is within the range of block sizes defined for the buckets, the memory request is serviced but the heap statistics that are reported by mallinfo are not updated.

The mallinfo_heap subroutine provides information about a specific heap if MULTIHEAPS is enabled. The mallinfo_heap subroutine returns a structure that details the properties and statistics of the heap specified by the user. Refer to the malloc.h file for details about the mallinfo_heap structure.

Note
The mallinfo_heap subroutine should not be used with Malloc 3.1.

Note
AIX uses a delayed paging slot allocation technique for storage allocated to applications. When storage is allocated to an application with a subroutine such as malloc, no paging space is assigned to that storage until the storage is referenced. This technique is useful for applications that allocate large sparse memory segments. However, this technique may affect portability of applications that allocate very large amounts of memory. If the application expects that calls to malloc will fail when there is not enough backing storage to support the memory request, the application may allocate too much memory. When this memory is referenced later, the machine quickly runs out of paging space and the operating system kills processes so that the system is not completely exhausted of virtual memory.The application that allocates memory must ensure that backing storage exists for the storage being allocated. Setting the PSALLOC environment variable to PSALLOC=early changes the paging space allocation technique to an early allocation algorithm. In early allocation, paging space is assigned once the memory is requested. See the Paging Space and Virtual Memory in the AIX 5L Version 5.2 System Management Concepts: Operating System and Devices for more information.

Parameters

Size Specifies a number of bytes of memory.
Pointer Points to the block of memory that was returned by the malloc or calloc subroutines. The Pointer parameter points to the first (lowest) byte address of the block.
Command Specifies a mallopt subroutine command. If M_DISCLAIM is used, then the paging space and physical memory in use by freed malloc space is returned to the system resource pool. If they are needed to fulfill a malloc request, they will be allocated to the process as needed. The address space is not altered. This will only release whole pages at a time. The M_MXFAST command can change how the system allocates memory by enabling or disabling the default and 3.1 allocator. The M_NLBLKS, M_GRAIN, and M_KEEP commands are only provided for source code compatability, and do not provide any functionality.
Value Specifies the value to which the M_DISCLAIM, M_MXFAST, M_NLBLKS, M_GRAIN, or M_KEEP label is to be set. M_NLBLKS, M_GRAIN, and M_KEEP are provided only for source code compatibility. They do not affect the operation of subsequent calls to the malloc subroutine. For M_MXFAST, setting Value to 0 disables the 3.1 allocator, and enable the default allocator. Setting Value to a positive value will disable the default allocator, and enable the 3.1 allocator. For M_DISCLAIM, Value does not affect the behavior of mallopt(), and should be set to NULL.
NumberOfElements Specifies the number of elements in the array.
ElementSize Specifies the size of each element in the array.
Heap Specifies a heap number from 0 to 31.

Return Values

Each of the allocation subroutines returns a pointer to space suitably aligned for storage of any type of object. Cast the pointer to the pointer-to-element type before using it.

The malloc, realloc, calloc , and valloc subroutines return a null pointer if there is no available memory, or if the memory arena has been corrupted by being stored outside the bounds of a block. When this happens, the block pointed to by the Pointer parameter may be destroyed.

If the malloc or valloc subroutine is called with a size of 0, the subroutine returns a null pointer. If the realloc subroutine is called with a nonnull pointer and a size of 0, the realloc subroutine attempts to free the pointer and return a null pointer. If the realloc subroutine is called with a null pointer, it calls the malloc subroutine for the specified size and returns a non-null pointer if malloc succeeds or a null pointer if malloc fails.

Error Codes

When the memory allocation subroutines are unsuccessful, the global variable errno may be set to the following values:

EINVAL Indicates a call has requested 0 bytes.
ENOMEM Indicates that not enough storage space was available.

Related Information

The _end, _etext, or _edata (_end, _etext, or _edata Identifier) identifier.

User Defined Malloc Replacement, Debug Malloc, Malloc Multiheap, Malloc Buckets, Malloc Log, Malloc Trace, System Memory Allocation Using the malloc Subsystem, Subroutines, Example Programs, and Libraries in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs, and Understanding Paging Space Allocation Policies section in AIX 5L Version 5.2 System Management Concepts: Operating System and Devices.

[ Top of Page | Previous Page | Next Page | Contents | Index | Library Home | Legal | Search ]