NAME¶
DUMA - DUMA Malloc Debugger
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);
extern int DUMA_ALIGNMENT;
extern int DUMA_PROTECT_BELOW;
extern int DUMA_PROTECT_FREE;
extern int DUMA_ALLOW_MALLOC_0;
extern int DUMA_FILL;
DESCRIPTION¶
DUMA helps you detect two common programming bugs: software that overruns
the boundaries of a malloc() memory allocation, and software that touches a
memory allocation that has been released by free(). Unlike other malloc()
debuggers, DUMA will detect
read accesses as well as writes, and it
will pinpoint the exact instruction that causes an error. It has been in use
at Pixar since 1987, and at many other sites for years.
DUMA uses the virtual memory hardware of your computer to place an inaccessible
memory page immediately after (or before, at the user's option) each memory
allocation. When software reads or writes this inaccessible page, the hardware
issues a segmentation fault, stopping the program at the offending
instruction. It is then trivial to find the erroneous statement using your
favorite debugger. In a similar manner, memory that has been released by
free() is made inaccessible, and any code that touches it will get a
segmentation fault.
Simply linking your application with libduma.a will allow you to detect most,
but not all, malloc buffer overruns and accesses of free memory. If you want
to be reasonably sure that you've found
all bugs of this type, you'll
have to read and understand the rest of this man page.
USAGE¶
Link your program with the library
libduma.a . Make sure you are
not linking with
-lmalloc, -lmallocdebug, or with other
malloc-debugger or malloc-enhancer libraries. You can only use one at a time.
If your system administrator has installed DUMA for public use, you'll be able
to use the
-lduma argument to the linker, otherwise you'll have to put
the path-name for
libduma.a in the linker's command line. You can also
use dynamic linking. If you're using a Bourne shell, the statement
export
LD_PRELOAD=libduma.so.0.0 will cause DUMA to be loaded to run all dynamic
executables. The command
duma command runs a single command
under DUMA.
Some systems will require special arguments to the linker to assure that you are
using the DUMA malloc() and not the one from your C library.
Run your program
using a debugger. It's easier to work this way than to
create a
core file and post-mortem debug it. DUMA can create
huge core files, and some operating systems will thus take minutes
simply to dump core! Some operating systems will not create usable core files
from programs that are linked with DUMA. If your program has one of the errors
detected by DUMA, it will get a segmentation fault (SIGSEGV) at the offending
instruction. Use the debugger to locate the erroneous statement, and repair
it.
GLOBAL AND ENVIRONMENT VARIABLES¶
DUMA has four configuration switches that can be enabled via the shell
environment, or by setting the value of global integer variables using a
debugger. These switches change what bugs DUMA will detect, so it's important
that you know how to use them.
- DUMA_ALIGNMENT
- This is an integer that specifies the alignment for any
memory allocations that will be returned by malloc(), calloc(), and
realloc(). The value is specified in bytes, thus a value of 4 will cause
memory to be aligned to 32-bit boundaries unless your system doesn't have
a 8-bit characters. DUMA_ALIGNMENT is set to sizeof(int) by default, since
that is generally the word-size of your CPU. If your program requires that
allocations be aligned to 64-bit boundaries and you have a 32-bit
int you'll have to set this value to 8. This is the case when
compiling with the -mips2 flag on MIPS-based systems such as those
from SGI. The memory allocation that is returned by DUMA malloc() is
aligned using the value in DUMA_ALIGNMENT, and its size the multiple
of that value that is greater than or equal to the requested
size. For this reason, you will sometimes want to set DUMA_ALIGNMENT to 0
(no alignment), so that you can detect overruns of less than your CPU's
word size. Be sure to read the section WORD-ALIGNMENT AND OVERRUN
DETECTION in this manual page before you try this. To change this
value, set DUMA_ALIGNMENT in the shell environment to an integer value, or
assign to the global integer variable DUMA_ALIGNMENT using a
debugger.
- DUMA_PROTECT_BELOW
- DUMA usually places an inaccessible page immediately after
each memory allocation, so that software that runs past the end of the
allocation will be detected. Setting DUMA_PROTECT_BELOW to 1 causes DUMA
to place the inaccessible page before the allocation in the address
space, so that under-runs will be detected instead of over-runs. When
DUMA_PROTECT_BELOW is set, the DUMA_ALIGNMENT parameter is ignored. All
allocations will be aligned to virtual-memory-page boundaries, and their
size will be the exact size that was requested. To change this value, set
DUMA_PROTECT_BELOW in the shell environment to an integer value, or assign
to the global integer variable DUMA_PROTECT_BELOW using a debugger.
- DUMA_PROTECT_FREE
- DUMA usually returns free memory to a pool from which it
may be re-allocated. If you suspect that a program may be touching free
memory, set DUMA_PROTECT_FREE to 1. This will cause DUMA to never
re-allocate memory once it has been freed, so that any access to free
memory will be detected. Some programs will use tremendous amounts of
memory when this parameter is set. To change this value, set
DUMA_PROTECT_FREE in the shell environment to an integer value, or assign
to the global integer variable DUMA_PROTECT_FREE using a debugger.
- DUMA_ALLOW_MALLOC_0
- By default, DUMA traps calls to malloc() with a size of
zero, because they are often the result of a software bug. If
DUMA_ALLOW_MALLOC_0 is non-zero, the software will not trap calls to
malloc() with a size of zero. To change this value, set
DUMA_ALLOC_MALLOC_0 in the shell environment to an integer value, or
assign to the global integer variable DUMA_ALLOC_MALLOC_0 using a
debugger.
- DUMA_FILL
- When set to a value between 0 and 255, every byte of
allocated memory is initialized to that value. This can help detect reads
of uninitialized memory. When set to -1, some memory is filled with zeroes
(the operating system default on most systems) and some memory will retain
the values written to it during its last use.
WORD-ALIGNMENT AND OVERRUN DETECTION¶
There is a conflict between the alignment restrictions that malloc() operates
under and the debugging strategy used by DUMA. When detecting overruns, DUMA
malloc() allocates two or more virtual memory pages for each allocation. The
last page is made inaccessible in such a way that any read, write, or execute
access will cause a segmentation fault. Then, DUMA malloc() will return an
address such that the first byte after the end of the allocation is on the
inaccessible page. Thus, any overrun of the allocation will cause a
segmentation fault.
It follows that the address returned by malloc() is the address of the
inaccessible page minus the size of the memory allocation. Unfortunately,
malloc() is required to return
word-aligned allocations, since many
CPUs can only access a word when its address is aligned. The conflict happens
when software makes a memory allocation using a size that is not a multiple of
the word size, and expects to do word accesses to that allocation. The
location of the inaccessible page is fixed by hardware at a word-aligned
address. If DUMA malloc() is to return an aligned address, it must increase
the size of the allocation to a multiple of the word size. In addition, the
functions memalign() and valloc() must honor explicit specifications on the
alignment of the memory allocation, and this, as well can only be implemented
by increasing the size of the allocation. Thus, there will be situations in
which the end of a memory allocation contains some padding space, and accesses
of that padding space will not be detected, even if they are overruns.
DUMA provides the variable DUMA_ALIGNMENT so that the user can control the
default alignment used by malloc(), calloc(), and realloc(). To debug overruns
as small as a single byte, you can set DUMA_ALIGNMENT to zero. This will
result in DUMA malloc() returning unaligned addresses for allocations with
sizes that are not a multiple of the word size. This is not a problem in most
cases, because compilers must pad the size of objects so that alignment
restrictions are honored when storing those objects in arrays. The problem
surfaces when software allocates odd-sized buffers for objects that must be
word-aligned. One case of this is software that allocates a buffer to contain
a structure and a string, and the string has an odd size (this example was in
a popular TIFF library). If word references are made to un-aligned buffers,
you will see a bus error (SIGBUS) instead of a segmentation fault. The only
way to fix this is to re-write the offending code to make byte references or
not make odd-sized allocations, or to set DUMA_ALIGNMENT to the word size.
Another example of software incompatible with DUMA_ALIGNMENT < word-size is
the strcmp() function and other string functions on SunOS (and probably
Solaris), which make word-sized accesses to character strings, and may attempt
to access up to three bytes beyond the end of a string. These result in a
segmentation fault (SIGSEGV). The only way around this is to use versions of
the string functions that perform byte references instead of word references.
INSTRUCTIONS FOR DEBUGGING YOUR PROGRAM¶
- 1.
- Link with libduma.a as explained above.
- 2.
- Run your program in a debugger and fix any overruns or
accesses to free memory.
- 3.
- Quit the debugger.
- 4.
- Set DUMA_PROTECT_BELOW = 1 in the shell environment.
- 5.
- Repeat step 2, this time repairing underruns if they
occur.
- 6.
- Quit the debugger.
- 7.
- Read the restrictions in the section on WORD-ALIGNMENT
AND OVERRUN DETECTION. See if you can set DUMA_ALIGNMENT to 0 and
repeat step 2. Sometimes this will be too much work, or there will be
problems with library routines for which you don't have the source, that
will prevent you from doing this.
MEMORY USAGE AND EXECUTION SPEED¶
Since DUMA uses at least two virtual memory pages for each of its allocations,
it's a terrible memory hog. I've sometimes found it necessary to add a swap
file using
swapon(8) so that the system would have enough virtual memory to
debug my program. Also, the way we manipulate memory results in various cache
and translation buffer entries being flushed with each call to malloc or free.
The end result is that your program will be much slower and use more resources
while you are debugging it with DUMA.
Don't leave libduma.a linked into production software! Use it only for
debugging.
AUTHOR¶
Hayati Ayguen
WARNINGS¶
I have tried to do as good a job as I can on this software, but I doubt that it
is even theoretically possible to make it bug-free. This software has no
warranty. It will not detect some bugs that you might expect it to detect, and
will indicate that some non-bugs are bugs.
LICENSE¶
Copyright 1987-1999 Bruce Perens. All rights reserved.
This program is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License, Version 2, as published by the
Free Software Foundation. A copy of this license is distributed with this
software in the file "COPYING".
This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
A PARTICULAR PURPOSE. Read the file "COPYING" for more details.
Bruce Perens
1563 Solano Ave. #349
Berkeley, CA 94707
Telephone: 510-526-1165
Internet: bruce@perens.com
FILES¶
/dev/zero: Source of memory pages (via
mmap(2)).
SEE ALSO¶
malloc(3),
mmap(2),
mprotect(2),
swapon(8)
DIAGNOSTICS¶
Segmentation Fault: Examine the offending statement for violation of the
boundaries of a memory allocation.
Bus Error: See the section on
WORD-ALIGNMENT AND OVERRUN DETECTION. in
this manual page.
BUGS¶
My explanation of the alignment issue could be improved.
Some Sun systems running SunOS 4.1 were reported to signal an access to a
protected page with
SIGBUS rather than
SIGSEGV, I suspect this
is an undocumented feature of a particular Sun hardware version, not just the
operating system. On these systems, dumatest will fail with a bus error until
you modify the Makefile to define
PAGE_PROTECTION_VIOLATED_SIGNAL as
SIGBUS.
There are, without doubt, other bugs and porting issues. Please contact me via
e-mail if you have any bug reports, ideas, etc.
WHAT'S BETTER¶
Purify does a much more thorough job than DUMA, and does not have the
huge memory overhead.
Checkergcc, a modified version of the GNU C
Compiler that instruments all memory references, is available on Linux systems
and where GCC is used. It performs some of the same tasks as Purify, but only
on code that it has compiled.