MALLOC.DBG(3)                   Domain/OS BSD                    MALLOC.DBG(3)



NAME
     malloc, free, realloc, calloc - memory allocator with debugging support

SYNOPSIS
     char *malloc(size)
     unsigned size;

     free(ptr)
     char *ptr;

     char *realloc(ptr, size)
     char *ptr;
     unsigned size;

     char *calloc(nelem, elsize)
     unsigned nelem, elsize;

DESCRIPTION
     /usr/apollo/lib/libmalloc.dbg is an installed library providing, in
     addition to all of the functionality of the routines described in
     malloc(3), additional checking and statistics gathering during execution.
     The routines in this library are useful, therefore, in debugging programs
     in whose failure malloc, free, realloc, or calloc is implicated.

     This version of these routines checks for the truth of the following
     assertions:

     ⊕  The current block is in use (op->ov_magic == MAGIC).  This assertion
        will fail if the block already has been freed or was not acquired
        through malloc.  It also could fail if a program wrote into memory
        before the current block or after the previous block.

     ⊕  The magic number at the beginning of the block is still intact
        (op->ov_rmagic == RMAGIC).  This assertion could fail because a
        program wrote into memory before the start of this block or beyond the
        end of the previous block.  It possibly also could fail because this
        block was not acquired through malloc.

     ⊕  The magic number at the end of the block is still intact (*(u_short
        *)((caddr_t)(op + 1) + op->ov_size) == RMAGIC).  This assertion could
        fail because a program wrote into memory beyond the end of the size of
        its allocated block.

     To use these routines, you must install /usr/apollo/lib/libmalloc.dbg at
     the level of the shell in which the target program is to run.  Do this by
     way of the shell's inlib command:

          % inlib /usr/apollo/lib/libmalloc.dbg

     Upon detecting a violation of one of these assertions, these routines
     print a message telling you the assertion violated, the address of the
     corrupted block, and memory allocation statistics.  Then, they call
     abort(3), producing a process dump that can be analyzed with tb(1).

EXAMPLE
     Let's say a program running with this module installed fails with the
     following message:

     Malloc assertion violated: *(u_short *)((caddr_t)(op + 1) + op->ov_size) == RMAGIC
     on block 0x00010400
     Memory allocation statistics at failure

     2**sz:       3   4   5   6   7   8   9  10  ... 26  27  28  29  30  31  32
     free:        0   0  31   0   0   0   0   0  ...  0   0   0   0   0   0   0
     used:        0   0   1   0   0   0   0   0  ...  0   0   0   0   0   0   0
          Total in use: 32, total free: 992
     IOT trap

     This message indicates that the program wrote into memory beyond the end
     of the size of its allocated block (violated the assertion that the magic
     number stored at the end of the block was still intact).  The corrupted
     block begins at address 0x00010400 (useful information when running the
     program again under a debugger).

     Interpret the memory allocation statistics like this:

     2**sz:   This row indicates from which free list the allocated memory
              came.  malloc(3) maintains free lists by size of memory block
              allocated, ranging from 2**3 bytes to 2**32 bytes.  The numbers
              in this row represent the logarithm to the base 2 of S, where S
              is the size of the memory blocks maintained by the associated
              free list.

     free:    The numbers in this row indicate how many blocks of the size 2
              to the power of the number in the first row of the same column
              are free.

     used:    The numbers in this row indicate how many blocks of the size 2
              to the power of the number in the first row of the same column
              are allocated.

     In this example, only one 32-byte block has been allocated.  Presumably,
     this block is the corrupted one.

     The "IOT trap" message is returned by the shell, a result of abort having
     been called from this library.  The resulting process dump contains
     specific information useful in debugging.  Use tb(1) to see this
     information.

FILES
     /usr/apollo/lib/libmalloc.dbg   library module

SEE ALSO
     csh(1), sh(1), tb(1), abort(3), malloc(3).
     Domain Binder and Librarian Reference