malloc(3)malloc(3)NAME
alloca, calloc, free, mallinfo, malloc, mallopt, realloc, valloc - Pro‐
vide a memory allocator
SYNOPSIS
#include <stdlib.h>
void *calloc(
size_t num_of_elts,
size_t elt_size ); void free(
void *pointer ); void *malloc(
size_t size ); void *realloc
void *pointer,
size_t size ); void *valloc(
size_t size );
The following function definitions do not conform to current standards
and are supported only for backward compatibility. char *valloc(
size_t size );
#include <alloca.h>
void *alloca(
int size );
The following function definitions are provided only for System V com‐
patibility:
#include <malloc.h>
struct mallinfo mallinfo(
void ); int mallopt(
int command,
int value );
LIBRARY
Standard C Library (libc)
[Tru64 UNIX] Dense Malloc Library (libdensemalloc)
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards as follows:
calloc(), free(), malloc(), realloc(), valloc(): XSH5.0
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
Specifies a number of bytes of memory. Points to the block of memory
that was returned by the malloc() or calloc() function. Specifies a
mallopt() function command. Specifies M_MXFAST, M_NLBLKS, M_GRAIN, or
M_KEEP. Specifies the number of elements in the array. Specifies the
size of each element in the array.
DESCRIPTION
The malloc() and free() functions provide a simple, general-purpose
memory allocation package.
Note
See also the subsection “Using the densemalloc Library” for information
on using libdensemalloc to improve the performance of certain programs.
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, and the contents
of the memory are undefined. 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 as follows: By either the
malloc(), realloc(), or calloc() functions. [XPG4-UNIX] 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, and
the contents of any memory added beyond the limit of the old size is
undefined. If necessary, a new block is allocated, and data is copied
to it. If the pointer parameter is a null pointer, the realloc() func‐
tion simply allocates a new block of the requested size. If the size
parameter is 0 (zero) and pointer is not a null pointer, 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 initial‐
ized to zeros.
[Tru64 UNIX] 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 contents of the memory is
undefined.
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 has the same effect as malloc(), except that the
allocated memory is automatically aligned 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 minimal effect on the
current Tru64 UNIX implementation of memory allocation. See the NOTES
section for details.
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 appli‐
cation. It must only be called after some storage has been allocated.
Information describing space usage is returned. Refer to the
/usr/include/malloc.h header file for details of the mallinfo struc‐
ture.
Tuning Memory Allocation
Note
See also the subsection “Using the densemalloc Library” for information
on the densemalloc tuning variables.
The behavior of these memory allocation functions can be tuned to opti‐
mize 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 Tru64
UNIX 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.
Except where noted, these variables also apply to the functions
described in amalloc(3). The variable __delayed_free is used to cause
the free function to use a “delay” slot (of size 1). This means that
any time you call free, it saves your pointer and actually frees what
you last called free with. This is intended to compensate for misuse of
realloc, where the user frees a pointer and then calls realloc with it.
Because the delay slot is shared across all threads, this fea‐
ture will not provide reliable protection for multithreaded
applications. Sharing the delay slot also results in it being
accessed internally with atomic instruction sequences, which can
create a bottleneck on multiCPU systems.
A value of 1 turns this feature on for single-threaded applica‐
tions. A value of 2 turns this feature on for both single and
multithreaded applications. A value of 0 (zero) turns this fea‐
ture off. All other values cause undefined behavior. It is rec‐
ommended that all multithreaded applications should try to use
the value 0 or 1. The default value of 2 will change to 1 in a
future release. The variable __fast_free_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 a heap size of 130 MB 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 mem‐
ory requested). The variable __first_fit is currently intended
only for performance critical multithreaded applications. It
should not be used with single threaded applications. Its value
is used to allow malloc and amalloc to skip up to a larger
internal cache list if the optimum node size list is found to be
in use by another thread. The allowed values are 0, 1, and 2. Do
not use any other value. A value of 0 disables this feature. A
value of 1 allows the next larger list to be used, and a value
of 2 allows the next list after that to also be used (three
lists in total).
Increasing the value of __first_fit can increase both execution
speed and memory consumption of multithreaded applications mak‐
ing heavy concurrent use of either malloc functions or the same
arena with amalloc functions. The __madvisor variable controls
how malloc communicates memory usage information to the kernel.
Permissible values for __madvisor are 0 and 1. If the variable
value is 1, any physical memory associated with the virtual mem‐
ory range is removed, reducing the resident set size (RSS). The
kernel does not need to swap this memory out.
Setting a value of 1 for __madvisor results in a trivial
decrease in execution speed. If execution speed is important,
leave the setting at the default value of 0. (Does not apply to
amalloc functions.) The __max_cache variable suggests the num‐
ber of internal cache (lookaside) lists to be used by malloc and
amalloc. Each list contains blocks within the same size range. A
larger value of __max_cache causes the internal caching of
larger sized blocks. The currently allowable values for this
variable are 15, 18, 21, 24, and 27. Do not use any other value.
The given values correspond to lists containing nodes up to 632,
1272, 2552, 5112, and 10232 bytes in size, respectively. The
maximum length of the lists is determined by the __fast_free_max
variable described elsewhere in this section.
Application requests for storage that can be satisfied from a
node on a cache list typically happen somewhat faster than those
that cannot. Increasing the value of this variable can increase
both the execution speed and that memory consumption of an
application that allocates nodes in the given size range. The
variable __mingrow is the minimum size that the heap is allowed
to grow in response to any request for a buffer that would grow
the heap. The amount to grow is the larger of __mingrow or
__mingrowfactor * heap_size_in_bytes. The value of this variable
is used in whole-page increments; any value that is not an inte‐
gral 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 time. The vari‐
able __mingrowfactor is the minimum fraction that the heap will
be allowed to grow. The actual amount grown is the larger of
__mingrow or __mingrowfactor * heap_size_in_bytes. The variable
__minshrink is the minimum size that the heap is allowed to
shrink in response to the freeing of space at the end of the
heap. The heap will shrink if the space is greater than __min‐
shrink and greater than __minshrinkfactor * heap_size_in_bytes.
This variable has no effect unless __noshrink is 0. The vari‐
able __minshrinkfactor is the minimum fraction that the heap is
allowed to shrink 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 *
heap_size_in_bytes.
This variable has no effect unless __noshrink is 0. The vari‐
able __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. Permissi‐
ble 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. The variable __sbrk_override controls
the manner in which the heap growth is obtained. If this vari‐
able is set to 1 (the default) and the call to sbrk to grow the
heap fails, a call is made to mmap to attempt to obtain memory.
This technique is extremely valuable to programs running in taso
mode. (Does not apply to amalloc functions.) If the variable is
set to 0, no call is made to mmap if the call to sbrk fails.
Caution
The use of this method to obtain heap space will cause sbrk(0)
to return a value that does not reflect the true end of the
heap. 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. Per‐
missible values for __small_buff are 0 and 1.
If the process is using a great many small (1 to 15 byte) buf‐
fers, setting __small_buff to 1 reduces heap overhead. The
variable __taso_mode is set to 1 to indicate that the program is
executing in taso mode. If the variable is set to 1, the point‐
ers returned by malloc and realloc are bounds checked and the
ENOMEM error is returned if the pointer exceeds MAXINT.
Using the densemalloc Library
The densemalloc library provides an alternate set of malloc routines
that implement a “dense malloc” memory allocation strategy. This strat‐
egy can improve run-time performance in programs that meet the follow‐
ing criteria: Make heavy use of heap memory Call malloc and free (and
realloc) infrequently Allocate memory in many small chunks (under 64
bytes) Reference those chunks very frequently Rarely free those chunks
In general, the “dense malloc” strategy packs memory more tightly, at a
slight cost of execution speed of malloc and free, by reducing the
bookkeeping overhead and round-up padding attached to allocated chunks.
When the processor loads chunks of memory into its caches, they pack
more densely and the caches can then be more effective. In applica‐
tions where cache density is a dominant factor in runtime performance,
this can have a significantly positive net effect.
To use the “dense malloc” memory allocator, proceed as follows. If
your program is to be linked with the -non_shared option, link the
densemalloc library into your program by adding the following sequence
to your cc or ld command-line(s):
-all -ldensemalloc -none
If your program is to be linked with the -call_shared option, you have
two choices: You can reference the densemalloc library at link time by
adding the following sequence to your cc or ld command line(s):
-ldensemalloc You can experiment using densemalloc before link‐
ing with that library by executing the following in a shell and
then running the program:
_RLD_LIST="libdensemalloc.so:DEFAULT"
For example, for the C Shell:
setenv _RLD_LIST "libdensemalloc.so:DEFAULT"
If the program's performance is improved, then link with dense‐
malloc as described previously.
The “dense malloc” memory allocator can be adjusted with the tuning
variables described in this section. To use these, define a statically
initialized variable of the appropriate type with the desired value,
for example:
const int __dense_malloc_max_size = 128;
The “dense malloc” allocator defaults, limits, and tuning variables
are: Determines how large a chunk of the address space is reserved for
each pool (each size 8, 16, 32, 48 ...). If this space is exhausted,
another location will be used, but this slows down free().
default (taso): 0x600000
default (non-taso): 0x1800000 (shown above) Sets the mmap hint
address for where to allocate the smallest of the pools; the
rest are allocated upward from there.
default (taso): 0x0
default (non-taso): 0x2F000000000 (shown above) Determines the
size of the largest request that will be allocated by this allo‐
cator. If not a multiple of 16, the value is rounded up to the
next multiple of 16. Requests for memory that are larger than
this value are filled by the normal malloc routines.
default: 64 bytes
limit: 128 bytes Specifies, in pages, how large an increment
should be obtained on each allocation from the kernel.
default: 8 pages
NOTES
The mallopt() and mallinfo() functions are designed for tuning a spe‐
cific algorithm. The Tru64 UNIX operating system uses a new, more effi‐
cient algorithm. The mallopt() and mallinfo() functions are provided
for System V compatibility only and should not be used by new applica‐
tions. With the exception of the M_KEEP option, the mallopt() function
has no effect on allocator behavior, and the structure returned by the
mallinfo() function might not contain any useful information.
The valloc() function is marked as a LEGACY function in the XSH speci‐
fication and should not be used in new applications.
RESTRICTIONS
Because the alloca() function requires inclusion of <alloca.h> in order
to work correctly, this function is not portable.
Use of brk(), sbrk(), mmap(), or other virtual memory primitives can
interfere with the operation of malloc() and its associated functions.
RETURN VALUES
Each of the allocation functions returns a pointer to space that is
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 no memory is available or if the memory arena has been cor‐
rupted 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). If
the argument makes no sense, mallopt() returns -1 and sets errno to
indicate the error. Otherwise, another nonzero value is returned.
The mallinfo() function returns a pointer to a mallinfo structure,
defined in the /usr/include/malloc.h header file.
ERRORS
The malloc(), calloc(), realloc(), and valloc() functions set errno to
the specified values for the following conditions:
Insufficient storage space is available. [Tru64 UNIX] For malloc(),
this value indicates that the value of the size parameter is out of
range.
[Tru64 UNIX] For realloc(), this value indicates that the buf‐
fer is already free.
The mallopt() function sets errno to the specified values for the fol‐
lowing conditions:
The value argument makes no sense. Conditions that can cause this error
include: M_MXFAST argument < 0 M_NBLKS argument <= 1 M_GRAIN argument
<= 0 All commands after the first small block is allocated An unknown
command
Additionally, malloc() and its associated routines call other libc rou‐
tines, which can set errno (for example, sbrk()).
SEE ALSO
Functions: amalloc(3), sysconf(3)
Standards: standards(5)malloc(3)
