MALLOCCV(3) MALLOCCV(3)
NAME
malloc, free, realloc, calloc, memalign, valloc, cvmalloc_error -
WorkShop memory allocation library
SYNOPSIS
#include <stdlib.h>
void *malloc (sizet size);
void free (void *ptr);
void *realloc (void *ptr, sizet size);
void *calloc (sizet nelem, sizet elsize);
void *memalign (sizet alignment, sizet size);
void *valloc (sizet size);
void cvmallocerror (char *message);
DESCRIPTION
The WorkShop Performance Tools contain a malloc library, -lmalloc_cv,
which provides tracing and error detection around calls to the various
malloc routines.
The library provides an intercept layer for calls to malloc, free,
realloc, memalign, and valloc; the intercept allows tracing of all calls
with the WorkShop performance tools.
Calls to malloc, free, and realloc are passed through to whatever memory
allocation library the program is linked with. Calls to calloc are
actually not intercepted, but rely on the underlying calloc to call
malloc to get the space allocated. Calls to memalign are implemented by
allocating a block large enough to hold the aligned area asked for by the
user, as well as a guard area that holds a flag indicating that the user
block was obtained through memalign, and the address of the larger block.
Calls to valloc are translated into a call to getpagesize, followed by a
memalign call.
The last function, cvmalloc_error is called whenever any error is
detected; a debugger trap may be placed at exit from that routine to
interactively examine malloc errors.
MALLOC TRACING
The library provides for tracing of all calls to any of the entry points
listed above, as well as any of the errors listed below. The trace is
normally captured using a WorkShop performance experiment. It may be
written in ASCII to stderr by enabling the environment variable
MALLOC_TRACING, although this typically produces a great deal of output.
Page 1
MALLOCCV(3) MALLOCCV(3)
ERROR DETECTION
The library will detect some errors under all conditions, and others if
MALLOC_FASTCHK error detection is enabled. All errors pass through the
routine cvmalloc_error and a trap can be placed at the exit from that
routine to catch the problem. Errors are also traced.
The errors that are always detected are:
malloc call failing (returning NULL).
realloc call failing (returning NULL).
realloc call with an address outside the range of heap addresses
returned by malloc or memalign.
memalign call with an improper alignment.
free call with an address that is improperly aligned.
free call with an address outside the range of heap addresses
returned by malloc or memalign.
If MALLOC_FASTCHK is enabled, the library will also detect:
free or realloc calls where the words prior to the user block have
been corrupted.
free or realloc calls where the words following the user block have
been corrupted.
free or realloc calls where the address is that of a block that has
already been freed. This error may not always be detected if the
area around the block is reallocated after it was first freed.
The behavior of the library is governed by various environment variables:
MALLOCVERBOSE n
(where n is an integer) controls printing of messages from the
library. If n = 0, messages are printed to stderr ony when an error
occurs. If n = 1 (the default), a messages is printed during
initialization, so that the user can tell that the library was
properly included in the application. If n = 2 or greater, detailed
information about all traced events, including the callstack at the
time the error was detected, is printed. This option is not
normally used by the end user, as it can produce a huge vloume of
output.
MALLOCTRACING
enables tracing of all calls through the library. Tracing is
normally done in the course of a performance experiment; the
variable need not be set in such cases, as the running of the
experiment will automatically enable it. If the option is enabled
when the program is run independently, and MALLOC_VERBOSE is set to
2 or greater, the trace events and program call stacks will be
written to stderr.
MALLOCFASTCHK
enables corruption detection for library calls. Corruption
detection is done by allocating a space larger than the requested
area, and putting specific patterns in front of and behind the area
returned to the caller. When free is called, the patterns are
Page 2
MALLOCCV(3) MALLOCCV(3)
checked, and if the area was overwritten, an error message is
printed using an internal call to the routine cvmalloc_error. Under
the debugger, a trap may be set at exit from this routine to catch
the program at the error.
MALLOCFULLWARN
enables detection of some calls that are not strictly errors, but
represent sloppy programming, including free(NULL), malloc(0), and
realloc(ptr,0).
MALLOCMAXMALLOC n
(where n is an integer, in any base) sets a maximum size for any
malloc or realloc or memalign allocation. Any request exceeding
that size will be flagged as an error, and return a NULL pointer.
MALLOCNOREUSE
specifies that no area that has been freed will be reused. With
this option enabled, no actual free calls are really made, and the
process space and swap requirements can grow quite large. If
MALLOC_FASTCHK is not enabled, any space that is freed by a realloc
may or may not get reused; if MALLOC_FASTCHK is enabled, such space
will not be reused.
MALLOCCLEARFREE
will clear the data upon any free call. It will only work if
MALLOC_FASTCHK is also enabled.
MALLOCCLEARFREEPATTERN <pattern>
specifies a pattern to clear the data if MALLOC_CLEAR_FREE is
enabled. The default pattern is 0xcafebeef for the 32-bit version,
and 0xcafebeefcafebeef for the 64-bit versions. Only full words
(double words for 64-bits) are cleared to the pattern.
MALLOCCLEARMALLOC
will clear the memory area upon each allocation. It also requires
MALLOC_FASTCHK be enabled.
MALLOCCLEARMALLOCPATTERN <pattern>
specifies a pattern to clear the data if MALLOC_CLEAR_MALLOC is
enabled. The default pattern is 0xfacebeef for the 32-bit version,
and 0xfacebeeffacebeef for the 64-bit versions. Only full words
(double words for 64-bits) are cleared to the pattern.
SEE ALSO
malloc(3C), malloc(3X), cvspeed(1), cvperf(1).
DIAGNOSTICS
As ouput from the library routines.
Page 3