MALLOC(3,L) AIX Technical Reference MALLOC(3,L)
-------------------------------------------------------------------------------
malloc, free, realloc, calloc, valloc, alloca, mallopt, mallinfo
PURPOSE
Provides a means to allocate memory.
DEFAULT MALLOC SUBROUTINES
LIBRARY
Standard C Library (libc.a)
SYNTAX
#include <stdlib.h> void *realloc (ptr, size)
#include <sys/types.h> void *ptr;
size_t size;
void *malloc (size)
size_t size; void *calloc (nelem, elsize)
size_t nelem, elsize;
void free (ptr)
void *ptr;
ALTERNATE MALLOC SUBROUTINES
LIBRARY
Malloc Library (libmalloc.a)
SYNTAX
Processed November 7, 1990 MALLOC(3,L) 1
MALLOC(3,L) AIX Technical Reference MALLOC(3,L)
#include <malloc.h> char *calloc (nelem, elsize)
unsigned nelem, elsize;
char *malloc (size)
unsigned size; int mallopt (cmd, value)
int cmd, value;
void free (ptr)
struct mallinfo mallinfo ();
char *ptr
char *realloc (ptr, size)
char *ptr;
unsigned size;
DESCRIPTION
The malloc and free subroutines provide a simple general purpose memory
allocation package.
Two different malloc suites are provided. The default malloc suite includes
malloc, free, realloc, calloc, valloc, and alloca. The alternate malloc suite
includes malloc, free, realoc, calloc, mallopt, and mallinfo. To use the
alternate malloc, add -1malloc when running cc or ld. Except where noted, the
four subroutines shared by both suites (malloc, free, realloc, and calloc)
behave the same.
The default malloc allocates memory in a block which is a power of two. The
default malloc is faster than the alternate malloc because the allocated memory
is page aligned. However, it is more wasteful of memory than the alternate
malloc.
The alternate malloc adds only a small header to each piece allocated, so it
doesn't use as much memory as the default malloc. The memory allocated by the
alternate malloc is not page aligned, so the malloc runs slower because of the
increased paging.
If your program needs to use as much of the available memory as possible, you
should consider using the alternate malloc suite, or use the sbrk system call
directly. (Note that the alternate malloc doesn't automatically allocate as
much of the available memory as possible.) This is especially relevant for
AIX/370 programs compiled in S/370 (non-XA) mode. These processes have a
smaller virtual address space than XA-mode processes or AIX PS/2 processes.
The malloc subroutine returns a pointer to a block of at least size bytes. The
block is aligned so that it can be used for any type of data. Undefined
results occur if the space assigned by malloc is overrun.
The malloc subroutine searches memory for the first contiguous area of free
space of at least size bytes. The search is performed in a circular pattern
from the last block of memory allocated or freed. During the search, malloc
Processed November 7, 1990 MALLOC(3,L) 2
MALLOC(3,L) AIX Technical Reference MALLOC(3,L)
joins adjacent free blocks of memory. If a large enough contiguous area of
free space is not found, then malloc issues an sbrk system call to get more
memory from the system.
The free subroutine frees the block memory pointed to by the ptr parameter for
further allocation. The block pointed to by the ptr parameter must have been
previously allocated by the malloc subroutine. The default free subroutine
does not change the contents of this block of memory, but the alternate free
subroutine does, unless you use the M_KEEP directive of mallopt. Undefined
results occur if the ptr parameter is not a valid pointer.
The realloc subroutine changes the size of the block of memory pointed to by
the ptr parameter to the number of bytes specified by the size parameter, and
then it returns a pointer to the block. The contents of the block remain
unchanged up to the lesser of the old and new sizes. If a large enough block
of memory is not available, then realloc calls the malloc subroutine to enlarge
the memory area, and then moves the data to the new space.
The calloc subroutine allocates space for an array with the number of elements
specified by the nelem parameter. Each element is of the size specified by the
elsize parameter. The space is initialized to 0's.
Each of the allocation subroutines returns a pointer to space suitably aligned
for storage of any type of object. Cast the pointer to the type
pointer-to-element before using it.
mallopt (part of the alternate malloc suite) provides for control over the
allocation algorithm. The available values for cmd are:
M_MXFAST Set maxfast to value. The algorithm allocates all blocks below
the size of maxfast in large groups and then doles them out very
quickly. The default value for maxfast is 24.
M_NLBLKS Set numlblks to value. The "large groups" mentioned in the
previous item each contain numlblks blocks. numlblks must be
greater than 0. The default value for numlblks is 100.
M_GRAIN Set grain to value. The sizes of all blocks smaller than maxfast
are considered to be rounded up to the nearest multiple of grain.
grain must be greater than 0. The default values of grain is the
smallest number of bytes which will allow alignment of any data
type. Value will be rounded up to a multiple of the default when
grain is set.
M_KEEP Preserve data in a freed block until the next malloc, realloc, or
calloc. This option is provided only for compatibility with the
default version of malloc and is not recommended.
These values are defined in the <malloc.h> header file.
Processed November 7, 1990 MALLOC(3,L) 3
MALLOC(3,L) AIX Technical Reference MALLOC(3,L)
mallopt may be called repeatedly, but may not be called after the first small
block is allocated. If mallopt is called after any allocation or if cmd or
value are invalid, non-zero is returned. Otherwise, it returns zero.
mallinfo (part of the alternate malloc suite) provides instrumentation
describing space usage. It returns the structure:
struct mallinfo {
int arena; /* total space in arena */
int ordblks; /* number of ordinary blocks */
int smblks; /* number of small blocks */
int hblkhd; /* space in holding block headers */
int hblks; /* number of holding blocks */
int usmblks; /* space in small blocks in use */
int fsmblks; /* space in free small blocks */
int uordblks; /* space in ordinary blocks in use */
int fordblks; /* space in free ordinary blocks */
int keepcost; /* space penalty if keep option is used */
}
This structure is defined in the <malloc.h> header file.
The malloc, realloc, and calloc subroutines return a NULL pointer if there is
no available memory or if the memory arena has been corrupted by storing
outside the bounds of a block. When this happens, the block pointed to by the
ptr parameter could be destroyed.
ERROR CONDITIONS
The malloc, realloc, and calloc subroutines will fail if the following is true:
ENOMEM Insufficient memory is available.
COMPATIBILITY NOTE
The valloc subroutine, found in many BSD systems, is supported as a
compatibility interface. It is used by compiling the Berkeley Compatibility
Library (libbsd.a). The function of valloc is superceeded by malloc, which
automatically page aligns large (greater than or equal to 1 page) requests.
Its syntax is as follows:
char *valloc (size)
unsigned int size;
The alloca subroutine is included also for compatibility with older BSD
programs and is used by compiling with the Berkeley Compatibility Library
(libbsd.a). This subroutine allocates size bytes of space in the stack frame
of the caller. This temporary space is automatically freed on return. Its
syntax is as follows:
include <alloca.h>
Processed November 7, 1990 MALLOC(3,L) 4
MALLOC(3,L) AIX Technical Reference MALLOC(3,L)
char *alloca (size)
int size;
Processed November 7, 1990 MALLOC(3,L) 5