malloc(3C)malloc(3C)NAMEmalloc(), alloca(), calloc(), free(), mallinfo(), mallopt(), memo‐
rymap(), realloc(), valloc() - main memory allocator
SYNOPSISalloca()
System V Synopsis
Remarks
The functionality in the old package has been incorporated into The
library corresponding to the linker option is now an empty library on
PA-RISC based systems only; it does not exist on Makefiles that refer‐
ence this library on PA-RISC based systems will continue to work, but
they will not work on
Obsolescent Interfaces
has been deprecated at HP-UX 11i Version 1 and is now obsolete. The
function is more useful for statistics.
DESCRIPTION
The functions described here provide a simple, general purpose memory
allocation package:
Allocates space for a block of at least
size bytes, but does not initialize the space.
Allocates space for an array of
nelem elements, each of size elsize bytes, and
initializes the space to zeros. Actual amount of
space allocated will be at least nelem * elsize
bytes.
Changes the size of the block pointed to by
ptr to size bytes and returns a pointer to the
(possibly moved) block. Existing contents are
unchanged up to the lesser of the new and old
sizes. If ptr is a NULL pointer, behaves like
for the specified size. If size is zero and ptr
is not a NULL pointer, the object it points to is
freed and NULL is returned. of blocks with spe‐
cial alignments, such as those created by is not
supported.
Allocates space for a block of at least
size bytes starting on a boundary aligned to a
multiple of the value returned by (__SC_PAGE‐
SIZE). This space is uninitialized.
Deallocates the space pointed to by
ptr (a pointer to a block previously allocated by
or and makes the space available for further
allocation. If ptr is a NULL pointer, no action
occurs.
Provides for control over the allocation algorithm
and other options in the package. The available
values for cmd are:
Set maxfast to value. The algorithm
allocates all blocks below the
size of maxfast in large groups,
then doles them out very quickly.
The default value for maxfast is
zero.
Set numlblks to value. The above men‐
tioned ``large groups'' each con‐
tain numlblks blocks. numlblks
must be greater than 1. The
default value for numlblks is
Set grain to value. The sizes of all
blocks smaller than maxfast are
considered to be rounded up to the
nearest multiple of grain. grain
must be greater than zero. The
default value of grain is the
smallest number of bytes that can
accommodate alignment of any data
type. value is rounded up to a
multiple of the default when grain
is set.
Block all blockable signals in
and This option is provided for
those who need to write signal
handlers that allocate memory.
When set, the routines can be
called from within signal handlers
(they become re-entrant). Default
action is to block all blockable
signals.
NOTE: performance of will be
impacted considerably when the
option is set.
Do not block all blockable signals in
and This option cancels signal
blocking initiated by the option.
Enable the feature of
This option is provided for 32-bit
applications with one arena.
Release of last block happens only
when size of the free block is
greater than the threshold.
The threshold value is defined as
The feature is disabled if the
value is greater than or equal to
threshold value. Default action
is not to release last block.
These values are defined in the header file.
can be called repeatedly; but once the first
small block is allocated, it is not possible to
change the and values.
Provides instrumentation describing space usage,
but cannot be called until the first small block
is allocated. It returns the structure
The structure is defined in the header file.
Each of the allocation routines returns a pointer to space suitably
aligned (after possible pointer coercion) for storage of any type of
object.
Displays the contents of the memory allocator
for HP-UX 32-bit operating systems only. A list
of addresses and block descriptions is written
(using to standard output. If the value of the
show_stats parameter is 1, statistics concerning
number of blocks and sizes used will also be
written. If the value is zero, only the memory
map will be written.
The addresses and sizes displayed by may not cor‐
respond to those requested by an application.
The size of a block (as viewed by the allocator)
includes header information and padding to prop‐
erly align the block. The address is also offset
by a certain amount to accommodate the header
information.
has been deprecated at HP-UX 11i Version 1 and is
now obsolete.
Allocates space from the stack of the caller
for a block of at least size bytes, but does not
initialize the space. The space is automatically
freed when the calling routine exits.
Memory returned by is not related to memory allo‐
cated by other memory allocation functions.
Behavior of addresses returned by as parameters
to other memory functions is undefined.
The implementation of this routine is system
dependent and its use is discouraged.
RETURN VALUE
Upon successful completion, and return a pointer to space suitably
aligned (after possible pointer coercion) for storage of any type of
object. Otherwise, they return a NULL pointer. If returns a NULL
pointer, the memory pointed to by the original pointer is left intact.
returns zero for success and nonzero for failure.
DIAGNOSTICS
and return a NULL pointer if there is no available memory, or if the
memory managed by has been detectably corrupted. This memory may
become corrupted if data is stored outside the bounds of a block, or if
an invalid pointer (a pointer not generated by or is passed as an argu‐
ment to or
If is called after any allocation of a small block and cmd is not set
to or or if cmd or value is invalid, nonzero is returned. Otherwise,
it returns zero.
ERRORS
and set to and return a NULL pointer when an out-of-memory
condition arises.
and set to and return a NULL pointer when the memory being
managed by has been detectably corrupted.
EXTERNAL INFLUENCES
For PA-RISC based systems, the performance of the family of APIs can be
tuned via the environment variables and
For systems, in addition to and three global variables can be used for
performance tuning: and
For threaded applications, uses multiple arenas. Memory requests from
different threads are handled by different arenas. can be used to
adjust the number of arenas and how many pages each time an arena
expands itself (the expansion factor), assuming that the page size is
4096 bytes. In general, the more threads in an application, the more
arenas should be used for better performance. The number of arenas can
be from 1 to 64 for threaded applications.
For non-threaded applications, only one arena is used. If the environ‐
ment variable is not set, or the number of arenas is set to be out of
the range, the default number of 8 will be used. The expansion factor
is from 1 to 4096, default value is 32. Again, if the factor is out of
the range, the default value will be used.
Here is an example of how to use
This means that the number of arenas is 16, and the expansion size is
8*4096 bytes. In general, the more arenas you use, the smaller the
expansion factor should be, and vice versa.
is used to turn on the small block allocator, and to set up parameters
for the small block allocator, namely, maxfast, grain, and numlblks.
Applications with small block allocator turned on usually run faster
than with it turned off. Small block allocator can be turned on
through however, it is not early enough for C++/Java applications. The
environment variable turns it on before the application starts. The
call can still be used the same way. If the environment variable is
set, and no small block allocator has been used, the subsequent calls
can still overwrite whatever is set through If the environment variable
is set, and small block allocator has been used, then will have no
effect.
To use this environment variable,
This means that the maxfast size is 512, the number of small blocks is
100, and the grain size is 16. You have to supply all 3 values, and in
that order. If not, the default values will be used instead.
Three new global variables, and are introduced for Itanium-based sys‐
tems to over-ride the environment option. When these three variables
are initialized within an application, has no effect. This way, a
finely tuned application can lock in performance across different user
environments. However, as a subsequent call to before any block of
memory was allocated will change the behavior. By default, these three
variables will be initialized to zero at start up. It is the same as
setting them to
By default, SBA (Small Block Allocation) is turned on for Itanium-based
systems. This may contribute to better application performance. A
user can set
This will turn off SBA.
For all other possible values, please refer to
is used to turn on the thread local cache. Turning this option on sets
up a private cache for each thread to which access is effectively non-
threaded, so there is less contention on the arenas. For some multi-
threaded applications this can give a significant performance improve‐
ment.
The thread local cache saves blocks of sizes that have previously been
used, and thus may be requested again. The size of the cache is con‐
figurable. The cache is organized in buckets of sizes that are powers
of two; that is, there is a bucket for all blocks in the size range
64-127 bytes, another for 128-255 bytes, and so on.
Thread Local Cache can be tuned by setting the environment variable as
follows:
The values must be supplied in the exact order indicated. The first
three parameters are mandatory, and the last two are optional.
denotes the number of pointers cached per bucket. If is 0, then thread
local cache is disabled. The maximum value for is 32768.
is an indication of the number of buckets. The maximum block size that
will be cached is can range between 8 and 32.
is an indication in minutes of after how long blocks in an unused cache
will be released to the arena. is only a hint, so caches may or may
not be retired after the specified time period. If is 0, retirement is
disabled. The maximum value for is 1440 (that is, 24 hours).
enables cached blocks to be exchanged among threads. A thread that
heavily allocates blocks of a certain size is soon bound to run out of
blocks in its private cache. The exchange allows the thread to borrow
blocks from a global pool if available. This may be more efficient
than going back to the arena. is a hint to the caching algorithm indi‐
cating a particular number of cache misses after which it will search
the global pool for appropriate sized blocks. The algorithm also
releases unused cache blocks to the global pool. If is 0 or not set,
cache exchange is turned off.
is an indication of the size of the global cache pool. This parameter
is valid only if is turned on. The default value for is 8.
The maximum number of blocks that will be cached for each thread is
Here are examples of how to use
This means that is 1024, is 32, is 20 minutes, is 4, and is 8.
This is a valid configuration where the global pool is not activated.
and have no effect on non-threaded applications, while has.
NOTE: Modifying these variables increases the chances of surfacing
existing user memory defects such as buffer overrun.
WARNINGS
functions use and (see brk(2)) to increase the address space of a
process. Therefore, an application program that uses or must not use
them to decrease the address space, because this confuses the func‐
tions.
and do not check their pointer argument for validity.
The following actions are considered bad programming practices and
should not be done. The results are unpredictable, probably undesir‐
able and not supported. Examples of undesirable results are loss of
data, memory fault, bus error or infinite loop.
· Attempting to or a pointer not generated as the result of a
call to or
· Reading or writing data outside the boundaries of an allo‐
cated block.
· Attempting to an aligned block such as the result of
The following actions are strongly discouraged and may be unsupported
in a future version of
· Attempting to the same block twice.
· Depending on unmodified contents of a block after it has been
freed.
· Attempting to a block after it is freed.
Undocumented features of earlier memory allocators have not been dupli‐
cated. Applications which used any of the above bad programming prac‐
tices or discouraged practices are not guaranteed to continue function‐
ing at future releases.
Compatibility
The only external difference between the old allocator and the alloca‐
tor is that the old allocator would return a NULL pointer for a request
of zero bytes. The allocator returns a valid memory address. This is
not a concern for most applications.
By default, SBA (Small Block Allocation) is turned on for Itanium-based
systems and is turned off for PA-RISC systems. This was due to perfor‐
mance concerns. Please refer to the section of this manpage for
details.
SEE ALSObrk(2), errno(2), thread_safety(5).
STANDARDS CONFORMANCEmalloc(3C)
