malloc_ss(3)

NAME
     malloc, free, realloc, calloc, memalign, valloc, ssmalloc_error -
     SpeedShop memory allocation library

SYNOPSIS
     #include <stdlib.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);

     void *memalign (size_t alignment, size_t size);

     void *valloc (size_t size);

     void ssmalloc_error (char *message);

DESCRIPTION
     The SpeedShop Performance Tools contain a malloc library, -lmalloc_ss,
     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 SpeedShop 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, ssmalloc_error is not a user-accessible function, it
     is an internal static function.  It is called whenever any error is
     detected, so that 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 SpeedShop performance experiment.  It may be
     written in ASCII to stderr by enabling the environment variable
     _SSMALLOC_TRACING, although this typically produces a great deal of
     output.
ERROR DETECTION
     The library will detect some errors under all conditions, and others if
     _SSMALLOC_FASTCHK error detection is enabled.  All errors pass through
     the routine ssmalloc_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 _SSMALLOC_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:

     _SPEEDSHOP_VERBOSE
          If set to a zero-length string, messages are printed to stderr only
          when an error occurs.  If set to a non-zero length string), 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 volume of
          output.

     _SSMALLOC_TRACING
          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 _SSMALLOC_VERBOSE is set
          to 2 or greater, the trace events and program call stacks will be
          written to stderr.

     _SSMALLOC_FASTCHK
          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
          checked, and if the area was overwritten, an error message is
          printed using an internal call to the routine ssmalloc_error. Under
          the debugger, a trap may be set at exit from this routine to catch
          the program at the error.

     _SSMALLOC_FULLWARN
          enables detection of some calls that are not strictly errors, but
          represent sloppy programming, including free(NULL), malloc(0), and
          realloc(ptr,0).

     _SSMALLOC_MAXMALLOC n
          (where n is a non-zero 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.
          Setting _SSMALLOC_MAXMALLOC to zero disables the test.  Note that
          the size argument to malloc is an unsigned variable, and a small
          negative number will be treated as a very large unsigned number, and
          will typically trigger this error if _SSMALLOC_MAXMALLOC is set.

     _SSMALLOC_NO_REUSE
          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.

     _SSMALLOC_CLEAR_FREE
          will clear the data upon any free call.  It will only work if
          _SSMALLOC_FASTCHK is also enabled.

     _SSMALLOC_CLEAR_FREE_PATTERN <pattern>
          specifies a pattern to clear the data if _SSMALLOC_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.

     _SSMALLOC_CLEAR_MALLOC
          will clear the memory area upon each allocation.  It also requires
          _SSMALLOC_FASTCHK be enabled.

     _SSMALLOC_CLEAR_MALLOC_PATTERN <pattern>
          specifies a pattern to clear the data if _SSMALLOC_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), ssrun(1), prof(1), ssdump(1), ssrt(3).

DIAGNOSTICS
     As ouput from the library routines.