malloc, free, realloc, calloc, mallopt, mallinfo, 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( )

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

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.

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: AIX Version 3 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.To deal with this style of allocation, sample code is provided in /usr/lpp/bos/samples.

Parameters

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 the null pointer.

Error Codes

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

Implementation Specifics

These subroutines are part of Base Operating System (BOS) Runtime.

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 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 following is the syntax for the valloc subroutine:

char *valloc (Size)
unsigned int Size;

Related Information

The _end, _etext, or _edata identifier.

The #pragma compiler instruction.

Subroutines Overview and Understanding System Memory Allocation in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.