NAME

dmalloc - debugging malloc library

SYNOPSIS

cc [ flags ] files -ldmalloc [libraries]
 #include "/sprite/src/lib/dmalloc/malloc.h"
 char∗ calloc(nelem,elsize);
void  free(ptr);
char∗ malloc(size);
int  malloc_chain_check(flag);
void  malloc_dump(fd);
int  mallopt(cmd,value)
char∗ realloc(ptr,size);
 int  cmd,fd,flag;
unsigned  elsize,nelem,size;
char∗ ptr;
union val  value;
 

DESCRIPTION

This malloc library is a replacement for the standard library to be used during software development/debugging.  The library can be used without source code modification, just by linking it in.  This library is useful for finding trashed memory, but isn’t useful for finding memory leaks.  See the standard malloc(3) pages for more information on the use of the following functions:

calloc(), free(), malloc(), realloc()

This library differs from the standard malloc library in the following ways:

1. Each malloc segment contains a magic number so that free can verify that the pointer passed points to a valid malloc segment. 

2. Each malloc segment is filled with a non-zero pattern so that code that depends upon malloc segments being null will fail. 

3. The size of each segment will be at least 1 byte larger than requested and the extra bytes will be filled with a non-zero pattern.  When free is called, it will verify that you did not go beyond the number of bytes you asked for. 

4. When a segment is freed, it will be filled with a different non-zero pattern to ensure that the program doesn’t depend upon the use of already freed data. 

5. Whenever any of the string or memory functions (str∗, b∗, mem∗) are called with a pointer that is within the malloc arena,  the operation is checked to verify that it does not overrun the malloced segment.  A failure of this check is considered a "warning level error" (described later) and is handled accordingly. 

7. Run time checking can include verification of the malloc chain at each and every call to one of the malloc functions or manually by calling the malloc_chain_check function. 

6. When a problem is found, the action taken is specified at runtime by environment variables or at compile time by the use of the mallopt() function. 

There are two arbitrary levels of errors, warning and fatal, that this library will detect.  They are broken down as follows:

Warning messages include:

Calling free with a bad pointer

Calling a bstring/string/memory (3) function which will go beyond
the end of a malloc block. Note that the library function is
not modified to refuse the operation.

Fatal errors are:

Detectable corruption to the malloc chain.

The error handling for each level (warning or fatal) are specified using
environment variables or mallopt().  The coding for the error handling is
as follows:

  0 - continue operations

  1 - drop core and exit

  2 - just exit

  3 - drop core, but continue executing.  Core files will
be placed into core.[PID].[counter] i.e: core.00123.001

128 - dump malloc chain and continue

129 - dump malloc chain, dump core, and exit

130 - dump malloc chain, exit

131 - dump malloc chain, dump core, continue processing

In addition error messages can be placed into an error file.

malloc_opt() is used to set the malloc debugging options. The
following options can be set:

MALLOC_WARN - set the error handling for warning level errors.  val is
an integer that can contain any one of the following values:

M_HANDLE_IGNORE - ignore error
M_HANDLE_ABORT - drop core and exit
M_HANDLE_EXIT - just exit (no core drop)
M_HANDLE_CORE - drop core, but keep on going

In addition, M_HANDLE_DUMP may be or’d in to cause a dump of the current
malloc chain.
MALLOC_FATAL - set the error handling for fatal level errors.  val is
equivalent to val for MALLOC_WARN.
MALLOC_ERRFILE - set the destination for malloc error messages.  val is
a pointer to a character string containing the name of the file to be used
for error messages.
MALLOC_CKCHAIN - set the malloc chain checking flag.  If val is
non-zero, chain checking at every call to malloc is turned on.
For example, to set up the session to generate a core file for
every malloc warning, to drop core and exit on a malloc fatal, and
to log all messages to the file "malloc_log" do the following:

#include <malloc.h>
malloc_opt(MALLOC_WARN,131);
malloc_opt(MALLOC_FATAL,1);
malloc_opt(MALLOC_ERRFILE,"malloc_log");

malloc_opt() can be used to set/alter the debugging options at any time. 

malloc_dump() will dump a table of the malloc arena showing all allocated/freed segments and the first few bytes of data in each segment.  fd is the file descriptor to write the data to. 

malloc_chain_check() will check the status of the malloc arena.  If flag is non-zero, an error found in the chain will cause a fatal error.  malloc_chain_check() returns zero when there are no problems found in the malloc chain, non-zero otherwise. 

ENVIRONMENT VARIABLES

Environment variables can be used to control error handling, error logging and malloc chain checking at run time.  The following environment variables are used:

MALLOC_WARN - specifies the error handling for warning errors
MALLOC_FATAL - specifies the error handling for fatal errors
MALLOC_ERRFILE - specifies the error log file for error messages.
MALLOC_CKCHAIN - if 1, turns on malloc chain checking at every call to any of the malloc functions.

For example, to set up the session to generate a core file for every malloc warning, to drop core and exit on a malloc fatal, and to log all messages to the file "malloc_log" do the following:

MALLOC_WARN=131
MALLOC_FATAL=1
MALLOC_ERRFILE=malloc_log
 export MALLOC_WARN MALLOC_FATAL MALLOC_ERRFILE

WARNINGS

This malloc library and it’s associated string and memory functions are much less efficient than the standard functions due in part to the extra error checking.  You do not want to use this library when generating a production (i.e. releasable) version of your software.  It should only be used during development and testing. 

SEE ALSO

stat(2)

AUTHOR

Conor P. Cahill Virtual Technologies Incorporated uunet!virtech!cpcahil

Sprite version 1.0  —