malloc(3) Library Functions Manual malloc(3)
NAME
alloca, calloc, free, mallinfo, malloc, mallopt, realloc, valloc - Provides a memory allocator
LIBRARY
Standard C Library (libc) Berkeley Compatibility Library (libbsd)
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( /* libbsd.a version */
size_t size); /* returns pointer to char */
#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;
STANDARDS
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.
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.
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 call-
er. This space is automatically freed when the function that called the alloca() function returns to its caller. The contents of the memory
is undefined. 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 applica-
tion. 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
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 applica-
tions. 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 applications. A value of 2 turns this feature on for both single and multi-
threaded 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 coa-
lesce. 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 mal-
loc 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 __mingrowor __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 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.) 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.
NOTES
The mallopt() and mallinfo() functions are designed for tuning a specific 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 specification 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.
Usage of brk(), sbrk(), 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
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.
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 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()).
RELATED INFORMATION
Functions: amalloc(3), sysconf(3)
Standards: standards(5) delim off
malloc(3)