DMalloc.3x

.\"
.\" (C) Copyright 2006 Hewlett-Packard Development Company, L.P.
.\"
.de G
.br
.B
..
.TH dmALLOC 3 local
.SH NAME
DMmalloc, DMcalloc, DMfree, DMrealloc, DMnotfreed, DMmemcheck - memory allocation debugging
.SH SYNOPSIS
.G
#include <DMalloc.h>
.PP
.G
extern int DMverbose;
.G
extern char *DMtriggeraddr;
.PP
.G
char *
.G
DMmalloc (size, fname, line)
.G
int size;
.G
char *fname;
.G
int line;
.PP
.G
char *
.G
DMcalloc (size, nitems, fname, line)
.G
int nitems;
.PP
.G
char *
.G
DMrealloc (ptr, size, fname, line)
.G
char *ptr;
.PP
.G
DMfree (ptr, fname, line)
.PP
.G
DMnotfreed ()
.PP
.G
DMmemcheck (ptr, fname, line)
.PP
.G
DMtrigger()
.PP
.SH DESCRIPTION
The
.IR DM "(debug memory)"
routines are replacements for the routines
described in
.I malloc(3)
to be used to debug memory allocation problems.
These routines check for overwriting start and/or ends of memory
areas,
passing mis-aligned pointers to
.IR free() ,
the integrity of all outstanding allocated memory,
passing already-freed pointers to
.I free()
and no-doubt some other things.
Some global variables are provided to aid the control of these
routines when using a run-time debugger.
.PP
These routines are written on top of the standard
memory allocation routines and are accessed by
.BR #includ ing 
a header file which re-writes source calls
to the standard routines to be calls to the
.I DM
routines.
This header file contains:
.IP ""
.nf
#define free(p) DMfree(p,__FILE__,__LINE__)
#define malloc(s) DMmalloc(s,__FILE__,__LINE__)
#define calloc(s,i) DMcalloc(s,i,__FILE__,__LINE__)
#define memcheck(p) DMmemcheck(p,__FILE__,__LINE__)
#define realloc(p,s)	DMrealloc(p,s,__FILE__,__LINE__)
.fi
.PP
.B NOTE
that the pre-processor variables __FILE__ and __LINE__
are passed in addition to the normal allocation routine
arguments to facilitate meaningful error messages.
.PP
The routines DM* are exact replacements for the standard routines
with the same name - minus the prefix, "DM",
when the header file is used.
.SH USE
To debug routines with suspect memory allocation problems,
.B #include
the header file, re-make and re-run the program.
Diagnostic output is written to stderr.
This output may be slightly customized - see section on measurements.
.SH MEASUREMENTS
Global variables
.B DMverbose
and
.B DMtriggeraddr
as well as the global function
.I DMtrigger()
are provided to interface to a run-time debugger.
.PP
The default action is for all allocation and free operations to cause
a short message to be written to stderr.
Modifying
.B DMverbose
changes this action.
If
.B DMverbose
is zero,
only errors will be printed.
.PP
.B DMtriggeraddr
may be set to a desired address and whenever this address is
found as an argument a message will be printed regardless of
the state of
.BR DMverbose .
The null function
.I DMtrigger
is called whenever a trigger is detected so that a debugger user
can set a breakpoint on this routine.
.PP
Typical use is to set
.B DMverbose
to 0,
run the program and obtain an error message containing a pointer,
set
.B DMtriggeraddr
to this address and re-run the program.
.PP
.I DMnotfreed
may be run at any time and prints a list of outstanding memory pointers
on stderr.
.PP
.I DMmemcheck
is used to check the validity of a particular memory block from user
code as well as all the outstanding blocks.
Note the macro definition in the header file.
If
.B ptr
is NULL, only the outstanding blocks are checked.
.SH FILES
.SH "SEE ALSO"
malloc(3)
.SH "BUGS"
The table of outstanding memory blocks can only hold 4K entries due to
the fact that it is static memory (for obvious reasons).
The variable TABSIZE in the source defines this limit.
An error is printed if this situation occurs.
.PP
Passing pointers to these routines obtained from other routines allocating
memory without these routines causes strange errors to occur.
.PP
Programs using these routines will be slowed considerably due to the
extensive error checking.
.SH AUTHOR
Hewlett-Packard