OSF

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

sizeSpecifies a number of bytes of memory. 

pointerPoints to the block of memory that was returned by the malloc() or calloc() function. 

commandSpecifies a mallopt() function command. 

valueSpecifies M_MXFAST, M_NLBLKS, M_GRAIN, or M_KEEP. 

num_of_eltsSpecifies the number of elements in the array. 

elt_sizeSpecifies 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 parameter.  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 previously allocated by either the malloc(), realloc(), or calloc() 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. 

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 particular application:

sizeBelow this value, requests to the malloc() function 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(). 

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

grainThe grain of small block sizes.  This value determines what range of small block sizes is considered the same size, which influences the number of separate holding blocks allocated.  For example, 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 parameter is too small, space may be wasted because many holding blocks are created. 

The values for the command parameter to the mallopt() function are:

M_MXFASTSets 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_NLBLKSSets 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_GRAINSets 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_KEEPPreserves 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 parameters cannot be changed after the first small block is allocated 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 development 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 System 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 mallinfo() functions are designed for tuning a specific algorithm.  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.