NAME
malloc, free, realloc, calloc, mallopt, mallinfo, alloca -
Provides a memory allocator
LIBRARY
Standard C Library (libc.a)
Berkeley Compatibility Library (libbsd.a)
Pthreads library (libpthreads.a)
SYNOPSIS
#include <malloc.h>
#include <sys/types.h>
void *malloc (
size_t size );
char *alloca (
int size );
void free (
void *pointer );
void *realloc (
void *pointer,
size_t size );
int mallopt (
int command,
int value );
struct mallinfo mallinfo( void ) ;
void *calloc (
size_t num_of_elts,
size_t elt_size );
PARAMETERS
size Specifies a number of bytes of memory.
pointer Points to the block of memory that was returned by
the malloc() or calloc() function.
command Specifies a mallopt() command to be set: M_MXFAST,
M_NLBLKS, M_GRAIN, or M_KEEP.
value Specifies the value used to set the mallopt() com-
mand.
num_of_elts
Specifies the number of elements in the array.
elt_size Specifies the size of each element in the array.
DESCRIPTION
The malloc() and free() functions provide a simple,
general-purpose memory allocation package.
The malloc() function returns a pointer to a block of memory
of at least the number of bytes specified by the size param-
eter. The block is aligned so that it can be used for any
type of data.
The free() function frees the block of memory pointed to by
the pointer parameter for further allocation. The block
pointed to by the pointer parameter must have been previ-
ously allocated by either the malloc(), realloc(), or cal-
loc() functions.
The realloc() function 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 pointer
to the block. The contents of the block remain unchanged up
to the lesser of the old and new sizes. If necessary, a new
block is allocated, and data is copied to it. If the
pointer parameter is a null pointer, the realloc() function
simply allocates a new block of the requested size. If the
size parameter is 0 (zero), the realloc() function frees the
specified block.
The calloc() function allocates space for an array with the
number of elements specified by the num_of_elts parameter,
where each element is of the size specified by the elt_size
parameter. The space is initialized to zeros.
The alloca() function 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 function
that called the alloca() function returns to its caller.
The mallopt() and mallinfo() functions allow tuning the
allocation algorithm at execution time. They are provided
for compatibility and do not provide any significant perfor-
mance improvement.
The mallopt() function initiates a mechanism that can be
used to allocate small blocks of memory quickly. You can use
the mallopt() function to allocate a large group (called a
holding block) of these small blocks at one time. Then,
each time a program requests a small amount of memory, a
pointer to one of the preallocated small blocks is returned.
Different holding blocks are created for different sizes of
small blocks and are created when needed. This function
allows the programmer to set the following three parameters
to maximize efficient small block allocation for a particu-
lar application:
size Below this value, requests to the malloc() func-
tion are filled using the special small block
algorithm. Initially, this value, which is called
maxfast, is zero, which means that the small block
option is not normally in use by malloc().
number The number of small blocks in a holding block. If
holding blocks have many more small blocks than
the program is using, space will be wasted. If
holding blocks are too small or have too few small
blocks in each, performance gain is lost.
grain The grain of small block sizes. This value deter-
mines what range of small block sizes is con-
sidered the same size, which influences the number
of separate holding blocks allocated. For exam-
ple, if the grain parameter is 16 bytes, all small
blocks of 16 bytes or less belong to one holding
block and blocks from 17 to 32 bytes belong to
another holding block. Thus, if the grain parame-
ter is too small, space may be wasted because many
holding blocks are created.
The values for the command parameter to the mallopt() func-
tion are:
M_MXFAST Sets maxfast to the value parameter. 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 0 (zero).
M_NLBLKS Sets numblks to the value parameter. The
aforementioned large groups each contain numblks
blocks. The value for numblks must be greater
than 1. The default value is 100.
M_GRAIN Sets grain to the value parameter (must be greater
than 0 (zero)). The sizes of all blocks smaller
than maxfast are considered to be rounded up to
the nearest multiple of grain. The default value
for the grain parameter is the smallest number of
bytes that allows alignment of any data type. When
the grain parameter is set, the value parameter is
rounded up to a multiple of the default
M_KEEP Preserves data in a free block until the next call
to the malloc(), realloc(), or calloc() function.
This option is provided only for compatibility
with the older version of the malloc() function
and is not recommended.
The mallopt() function may be called repeatedly, but parame-
ters cannot be changed after the first small block is allo-
cated from a holding block. If the mallopt() function is
called again after the first small block is allocated, it
returns an error.
The mallinfo() function can be used during program develop-
ment to determine the best settings of these parameters for
a particular application. It must only be called after some
storage has been allocated. Information describing space
usage is returned. Refer to the malloc.h file for details
of the mallinfo structure.
NOTES
The mallopt() and mallinfo() functions are not supported for
multi-threaded applications.
The mallopt() and mallinfo() functions are provided for Sys-
tem V compatibility only, and should not be used by new,
portable applications. The behavior of the malloc() and
free() functions may not be affected by calls to mallopt().
The structure returned by the mallinfo() function may not
contain any useful information. The mallopt() and mal-
linfo() functions are designed for tuning a specific algo-
rithm. OSF/1 uses a new, more efficient algorithm.
The valloc() function found in many BSD systems is supported
as a compatibility interface in the Berkeley Compatibility
Library (libbsd.a). The function of the valloc() function
is superceded by the malloc() function, which automatically
page aligns large (>= 1 page) requests. The valloc() syntax
follows:
char *valloc (size)
unsigned int size;
AES Support Level:
Full use (calloc(),
free(), malloc(), realloc())
RETURN VALUES
Each of the allocation functions 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.
The malloc(), realloc(), and calloc() functions 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 pointer parameter could be destroyed.
Upon successful completion, the mallopt() function returns 0
(zero). Otherwise, a nonzero value is returned.
The mallinfo() function returns a pointer to a mallinfo
structure, defined in the malloc.h header file.
Acknowledgement and Disclaimer