alloca, calloc, free, mallinfo, malloc, mallopt, realloc,
valloc - Provide a memory allocator
#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 compatibility:
#include <malloc.h>
struct mallinfo mallinfo(
void ); int mallopt(
int command,
int value );
Standard C Library (libc)
[Tru64 UNIX] Dense Malloc Library (libdensemalloc)
Interfaces documented on this reference page conform to
industry standards 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.
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.
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() function 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 initialized 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 application. 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 structure.
Tuning Memory Allocation [Toc] [Back]
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 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 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 feature 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 singlethreaded
applications. A value of 2 turns this
feature on for both single and multithreaded applications.
A value of 0 (zero) turns this feature
off. All other values cause undefined behavior. It
is recommended 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 memory 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 making 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 memory
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
number 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 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 time. The variable
__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 __minshrink and greater than __minshrinkfactor
* heap_size_in_bytes.
This variable has no effect unless __noshrink is 0.
The variable __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 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. The variable
__sbrk_override controls the manner in which
the heap growth is obtained. If this variable 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. 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. 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 pointers
returned by malloc and realloc are bounds checked
and the ENOMEM error is returned if the pointer
exceeds MAXINT.
Using the densemalloc Library [Toc] [Back]
The densemalloc library provides an alternate set of malloc
routines that implement a "dense malloc" memory allocation
strategy. This strategy can improve run-time performance
in programs that meet the following 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
applications 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 linking 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 densemalloc 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 allocator. 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
The mallopt() and mallinfo() functions are designed for
tuning a specific algorithm. The Tru64 UNIX 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.
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 specification and should not be used in new applications.
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.
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 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). 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.
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 buffer is already free.
The mallopt() function sets errno to the specified values
for the following 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 routines, which can set errno (for example,
sbrk()).
Functions: amalloc(3), sysconf(3)
Standards: standards(5)
malloc(3)
[ Back ] |
