NAME

malloc, free, realloc, calloc, mallopt, mallinfo, alloca, valloc − 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); #include <alloca.h>
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); void ∗valloc(            /∗ libc.a version ∗/
        size_t size);    /∗ returns pointer to void ∗/ char ∗valloc(            /∗ libbsd.a ∗/
        size_t size);    /∗ returns pointer to char ∗/

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_elts
Specifies 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.  If the size parameter is 0 (zero), the malloc() function returns a null pointer. 

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(), calloc(), or valloc() 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. 

Note

The alloca() function requires inclusion of <alloca.h>.  Without this header file, alloca() allocates memory in the heap instead of the stack; this memory is not necessarily freed when the calling routine exits. 

The valloc() function, found in many BSD systems, is supported in two ways:

       •In libbsd.a, as a BSD-compatible interface returning a pointer to a char

       •In libc.a, returning a pointer to void

Both interfaces automatically align requests to a page boundary (that is, the value returned by a call to getpagesize()). 

The mallopt() and mallinfo() functions are intended to allow tuning the allocation algorithm at execution time.  They have no effect on the current DEC OSF/1 implementation of memory allocation.  See NOTES. 

The mallopt() function can 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. 

Tuning Memory Allocation

The behavior of these memory allocation functions can be tuned to optimize their performance in a particular application. 

The following variables control how the functions operate.  Note that these variables and their effects are specific to the current DEC OSF/1 memory allocation implementation.  The default values for these variables are specified by libc.  To specify values other than the defaults, create a module containing definitions for the complete set of variables and include that module in your compilation.  (If you define only some of these variables, your compilation will produce “multiply defined” errors if you link the program nonshared.)  For each variable in this list, the default value is indicated after the equal sign. 

unsigned long __noshrink = 0
The variable __noshrink controls management of the heap size (which in turn controls the size of the required swap area).  As the user makes calls to free() or realloc(), the memory associated with the call can be put back into the pool of free memory.  Permissible values for __noshrink are 0 and 1. 

If the memory that is freed resides at the end of the heap and meets the constraints of __minshrink and __minshrinkfactor, it can be returned to the kernel by sbrk(nnn) if __noshrink is 0.  If __noshrink is 1, no attempts are made to return the freed memory. 

Set __noshrink to 1 if execution speed is more important than economy of memory usage. 

size_t __minshrink = 16384;
The variable __minshrink is the minimum size that the heap is allowed to shrink by the use of sbrk(nnn) in response to the freeing of space at the end of the heap.  The heap will shrink if the space is greater than __minshrink and greater than (__minshrinkfactor ∗ the size of the heap in bytes). 

This variable has no effect unless __noshrink is 0. 

double __minshrinkfactor = 0.001;
The variable __minshrinkfactor is the minimum fraction that the heap is allowed to shrink by the use of sbrk(nnn) in response to the freeing of space at the end of the heap.  The heap will shrink if the space is greater than __minshrink and greater than (__minshrinkfactor ∗ the size of the heap in bytes). 

This variable has no effect unless __noshrink is 0,

size_t __mingrow = 49152;
The variable __mingrow is the minimum size that the heap is allowed to grow by the use of sbrk(nnn) in response to any request for a buffer that would grow the heap.  The amount to grow is the larger of __mingrow or (__mingrowfactor ∗ the size of the heap in bytes).  The value of this variable is used in whole-page increments; any value that is not an integral multiple of the page size is rounded upward to the next whole number of pages. 

The __mingrow and __mingrowfactor variables control compromises between speed and memory usage; increasing either or both of them increases overhead but decreases execution speed. 

double __mingrowfactor = 0.1;
The variable __mingrowfactor is the minimum fraction that the heap will be allowed to grow.  The actual amount grown is the larger of __mingrowor (__mingrowfactor ∗ the size of the heap in bytes). 

unsigned long __madvisor = 1;
The __madvisor variable controls how malloc communicates memory usage information to the kernel.  If the variable is 1, as pages are freed and returned to the heap by malloc, the kernel is advised that these pages need not be swapped out.  This communication reduces the size of the required swap space.  Permissible values for __madvisor are 0 and 1. 

Setting __madvisor to 1 results in a trivial decrease in execution speed.  If execution speed is of paramount importance, set the variable to 0. 

unsigned long __small_buff = 0;
The __small_buff variable affects how malloc allocates space for extremely small buffers.  If the variable is 1, malloc allocates 24 bytes for requests of 1 to 15 bytes; if it is 0, the buffer allocated is 32 bytes.  The size of 32 bytes is required by X/Open guidelines specifying that a buffer must be so aligned that it can be assigned to any type of object.  Permissible values for __small_buff are 0 and 1. 

If the process is using a great many small (1 to 15 byte) buffers, setting __small_buff to 1 reduces heap overhead. 

int __fast_free_max = 13;
The variable __fast_fast_max is the maximum number of small buffers that malloc retains in the free list without attempting to coalesce.  This number is further adjusted by the number of megabytes in the user heap.  As the heap size increases, this number in reduced by 1 for each 10 MB of heap so that at 130 MB of heap only one buffer of each type is held in the free list. 

Increasing the value of __fast_free_max increases both execution speed and overhead (the size of the heap in relation to the memory requested). 

NOTES

The mallopt() and mallinfo() functions are not supported for multi-threaded applications. 

The mallopt() and mallinfo() functions are designed for tuning a specific algorithm.  The DEC OSF/1 operating system uses a new, more efficient algorithm.  The mallopt() and mallinfo() functions are provided for System V compatibility only and should not be used by new applications.  The behavior of the current malloc() and free() functions is not be affected by calls to mallopt().  The structure returned by the mallinfo() function might not contain any useful information. 

RESTRICTIONS

Because the alloca() function requires inclusion of <alloca.h> in order to work correctly, this function is not portable. 

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(), calloc(), and valloc() 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. 

ERRORS

No errors are defined for this routine.