 |
Index for
Section 3 |
|
 |
Alphabetical
listing for M |
|
 |
Bottom of
page |
|
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
size Specifies a number of bytes of memory.
pointer
Points to the block of memory that was returned by the malloc() or
calloc() function.
command
Specifies a mallopt() function command.
value
Specifies M_MXFAST, M_NLBLKS, M_GRAIN, or M_KEEP.
num_of_elts
Specifies the number of elements in the array.
elt_size
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 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
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).
const int __delayed_free = 2;
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 single-threaded 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.
const int __fast_free_max = 13;
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).
const int __first_fit = 0;
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.
const unsigned long __madvisor = 0;
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.)
const int __max_cache = 15;
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.
const size_t __mingrow = 49152;
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.
const 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
__mingrow or __mingrowfactor * heap_size_in_bytes.
const size_t __minshrink = 16384;
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.
const double __minshrinkfactor = 0.001;
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.
const 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.
const unsigned long __sbrk_override = 0;
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.)
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.
const 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.
const unsigned long __taso_mode = 0;
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 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.
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:
[ENOMEM] Insufficient storage space is available.
[EINVAL] [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:
[EINVAL] 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)
|
Index for
Section 3 |
|
|
Alphabetical
listing for M |
|
 |
Top of
page |
|