 |
» |
|
|
|
NAMEmalloc(), free(), realloc(), calloc(), valloc(), mallopt(), mallinfo(), memorymap(), alloca() — main memory allocator SYNOPSIS#include <stdlib.h> void *malloc(size_t size); void *calloc(size_t nelem, size_t elsize); void *realloc(void *ptr, size_t size); void *valloc(size_t size); void free(void *ptr); void memorymap(int show_stats); alloca#include <alloca.h> void *alloca(size_t size); SYSTEM V SYNOPSIS (HP-UX)#include <malloc.h> void *malloc(size_t size); void free(void *ptr); void *realloc(void *ptr, size_t size); void *calloc(size_t nelem, size_t elsize); int mallopt(int cmd, int value); struct mallinfo mallinfo(void); RemarksThe functionality in the old
malloc(3X)
package has been incorporated into
malloc(3C).
The library
(/usr/lib/libmalloc.a)
corresponding to the
-lmalloc
linker option is now an empty library.
Makefiles that reference this library will continue to work. Obsolescent InterfacesThe
memorymap()
function has been deprecated as of HP-UX 11.11, and will be obsolete at the
next release of HP-UX. DESCRIPTIONThe functions described in this manual entry
provide a simple, general purpose memory allocation package:
- malloc()
Allocates space for a block of at least
size
bytes, but does not initialize the space. - calloc()
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. - realloc()
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,
realloc()
behaves like
malloc()
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.
realloc()
of blocks with special alignments, such as those created by
valloc(),
is not supported. - valloc()
Allocates space for a block of at least
size
bytes starting on a boundary aligned to a multiple of the value returned by
sysconf
(__SC_PAGESIZE).
This space is uninitialized. - free()
Deallocates the space pointed to by
ptr
(a pointer to a block previously allocated by
malloc(),
realloc(),
calloc(),
or
valloc())
and makes the space available for further allocation.
If
ptr
is a NULL pointer, no action occurs. - mallopt()
Provides for control over the allocation algorithm
and other options in the
malloc(3C)
package.
The available values for
cmd
are:
- M_MXFAST
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. - M_NLBLKS
Set
numlblks
to
value.
The above mentioned ``large groups'' each contain
numlblks
blocks.
numlblks
must be greater than 1.
The default value for
numlblks
is
100. - M_GRAIN
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. - M_KEEP
Preserve data in a freed block until the next
malloc(),
realloc(),
or
calloc().
This option is provided only for compatibility
with the old version of
malloc()
and is not recommended. - M_BLOCK
Block all blockable signals in
malloc(),
realloc(),
calloc(),
and
free().
This option is provided for those
who need to write signal handlers that allocate memory.
When set, the
malloc(3C)
routines can be called from within signal handlers
(they become re-entrant).
Default action is
not
to block all blockable signals. - M_UBLOCK
Do not block all blockable signals in
malloc(),
realloc(),
calloc(),
and
free().
This option cancels signal blocking initiated by the
M_BLOCK
option.
These values are defined in the
<malloc.h>
header file. mallopt()
can be called repeatedly; but once the first small block
is allocated, it is not possible to change the
M_MAXFAST,
M_NLBLKS,
and
M_GRAIN
values. - mallinfo()
Provides instrumentation describing space usage,
but cannot be called until the first small block is allocated.
It returns the structure
mallinfo:
arena : total space in arena
fsmblks : number of bytes in free small blocks
fordblks : number of bytes in free ordinary blocks
hblks : number of holding blocks
hblkhd : number of bytes in holding block headers
keepcost : cost of enabling keep option
ordblks : number of ordinary blocks
smblks : number of small blocks
uordblks : number of bytes in ordinary blocks in use
usmblks : number of bytes in small blocks in use The
mallinfo
structure is defined in the
<malloc.h>
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.
- memorymap()
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
printf())
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
memorymap()
may not correspond to those requested by an application.
The size of a block (as viewed by the allocator)
includes header information and padding to properly align the block.
The address is also offset by a certain amount
to accommodate the header information. memorymap()
has been deprecated at HP-UX 11.11 and will be obsolete at the next release. - alloca()
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
alloca()
is not related to
memory allocated by other memory allocation functions.
Behavior of addresses returned by
alloca()
as parameters to other memory functions is undefined. The implementation of this routine is
system dependent and its use is discouraged.
RETURN VALUEUpon successful completion,
malloc(),
realloc(),
calloc(),
and
valloc()
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
realloc()
returns a NULL pointer,
the memory pointed to by the original pointer is left intact. mallopt()
returns zero for success and nonzero for failure. DIAGNOSTICSmalloc(),
realloc(),
calloc(),
and
valloc()
return a NULL pointer if there is no available memory,
or if the memory managed by
malloc()
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
malloc(),
realloc(),
calloc(),
or
valloc()
is passed as an argument to
free()
or
realloc(). If
mallopt()
is called after any allocation of a small block and
cmd
is not set to
M_BLOCK
or
M_UBLOCK,
or if
cmd
or
value
is invalid, nonzero is returned.
Otherwise, it returns zero. ERRORS- ENOMEM
malloc(),
realloc(),
calloc(),
and
valloc()
set
errno
to
ENOMEM
and return a
NULL pointer when an out-of-memory condition arises. - EINVAL
malloc(),
realloc(),
calloc(),
and
valloc()
set
errno
to
EINVAL
and return a NULL
pointer when the memory being managed by
malloc()
has been detectably corrupted.
EXTERNAL INFLUENCESThe performance of the
malloc()
family can be tuned via two new environment variables,
_M_ARENA_OPTS
and
_M_SBA_OPTS. For threaded applications,
malloc()
uses multiple arenas. Memory requests from different threads are handled
by different arenas.
_M_ARENA_OPTS
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 environment
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
_M_ARENA_OPTS, $ export _M_ARENA_OPTS = 16:8 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. _M_SBA_OPTS
is 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
mallopt();
however, it is not early
enough for C++/Java applications. The environment
variable turns it on before the application starts. The
mallopt()
call can still be used the same way. If the
environment variable is set, and no small block
allocator has been used, the subsequent
mallopt()
calls can still overwrite whatever is set through
_M_SBA_OPTS.
If the environment variable is set, and
small block allocator has been used, then
mallopt()
will have no effect. To use this environment variable, $ export _M_SBA_OPTS = 512:100:16 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. _M_ARENA_OPTS
has no effects on non-threaded applications, while
_M_SBA_OPTS
has. WARNINGSmalloc()
functions use
brk()
and
sbrk()
(see
brk(2))
to increase the address space of a process.
Therefore, an application program that uses
brk()
or
sbrk()
must not use them to decrease the address space,
because this confuses the
malloc()
functions. free()
and
realloc()
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 undesirable
and not supported. Examples of undesirable results
are loss of data, memory fault, bus error or infinite loop.
Attempting to
free()
or
realloc()
a pointer not generated as the result of a call to
malloc(),
realloc(),
calloc(),
or
valloc(). Reading or writing data outside the boundaries of an allocated block. Attempting to
realloc()
an aligned block such as the result of
valloc().
The following actions are strongly discouraged and may be unsupported
in a future version of
malloc():
Attempting to
free()
the same block twice. Depending on unmodified contents of a block after it has been freed. Attempting to
realloc()
a block after it is freed.
Undocumented features of earlier memory allocators
have not been duplicated. Applications which used any of the
above bad programming practices or discouraged practices
are not guaranteed to continue functioning at future releases. Obsolescent InterfacesThe
memorymap(3C)
function has been deprecated as of HP-UX 11.11, and will be obsolete at the
next release of HP-UX. The
mallinfo()
function is more useful for
malloc
statistics. COMPATIBILITYThe only external difference between the old
malloc(3X)
allocator and the
malloc(3C)
allocator is that the old allocator would return
a NULL pointer for a request of zero bytes.
The
malloc(3C)
allocator returns a valid memory address.
This is not a concern for most applications. STANDARDS CONFORMANCEmalloc(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C calloc(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C free(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C mallinfo(): SVID2, XPG2 mallopt(): SVID2, SVID3, XPG2 realloc(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C |
Printable version
