duma: Detect Unintended Memory Access (D.U.M.A.) - A Red-Zone memory allocator https://github.com/johnsonjh/duma

Jeffrey H. Johnson 6ac7caea35 Merge pull request #168 from johnsonjh/README/formatting/X236264 4 days ago
.devbots 6f575d9765 Enable devbots, update README 10 months ago
.github 6be2f5dedf Update codacy/codacy-analysis-cli-action action to v4 1 month ago
Attic 6a03bd83f6 Output adjustments, configuration and documentation updates, linting 3 months ago
confdir a1b3f1894d Update build configuration 3 months ago
debian 1436dc698f Update debian/docs: Switch to Markdown documentation 3 months ago
doc aa0b352fa7 Rename: docs-data -> docs; builddocs.bat to Attic 3 months ago
dumadll 4f3d2f770b multi: Quiet TickGit 3 months ago
examples d2c9d47f3b Restyled by whitespace 3 months ago
prj f48db219f8 move library sources into subdir src/ 3 months ago
src 430c61187e src/duma.c: Cast to void to silence a warning; add config header to install dependency. 3 months ago
stacktrace 6a03bd83f6 Output adjustments, configuration and documentation updates, linting 3 months ago
tests c061049848 Normalize style 3 months ago
win32-devcpp d2c9d47f3b Restyled by whitespace 3 months ago
win32-msvc d2c9d47f3b Restyled by whitespace 3 months ago
win32-msvc.2005 f48db219f8 move library sources into subdir src/ 3 months ago
win32-msvc.net f48db219f8 move library sources into subdir src/ 3 months ago
win32-vide d2c9d47f3b Restyled by whitespace 3 months ago
.deepsource.toml 30291149c6 Update .deepsource.toml: Exclude Attic from checks 3 months ago
.gitattributes f675927921 Add .gitattributes to configure GitHub Linguist. 6 months ago
.gitignore 5d1412bdf5 Ensure CMake builds use C++11 compilation; update documentation. 3 months ago
.gitlab-ci.yml 16b28fa64b Deprecate --ignore-cr-at-eol 8 months ago
.mergify.yml 074829c325 Mergify: configuration update 10 months ago
.whitesource 25a7ebce2a Update .whitesource 9 months ago
CHANGELOG.md dc11234595 Update documentation: Use updated Markdownlint 2 months ago
CMakeLists.txt 28f7cb284c Small build tweaks 3 months ago
COPYING-GPL 2c6762a043 no message 18 years ago
COPYING-LGPL cceb1b2d80 Automatic OS detection and additional reformatting. 1 year ago
GNUmakefile d5055773ec Update GNUmakefile: Use relative paths when linking 3 months ago
LICENSE cceb1b2d80 Automatic OS detection and additional reformatting. 1 year ago
README.md b35dea7433 Update README.md 4 days ago
SECURITY.md 99ae955f03 Normalize spelling and formatting 3 months ago
createconf.c 6a03bd83f6 Output adjustments, configuration and documentation updates, linting 3 months ago
createconf_new.cpp ac7cd406fe multi: process code with `expand`; remove TODO 3 months ago
duma.3 bd6ef1783d Patch for SourceForge bug ID #2831348: 12 years ago
duma.h 22ddb55dfb duma.h: Refer to #82 3 months ago
duma.sh 64ff46c7d6 Reformat scripts to appease shellcheck and shfmt 9 months ago
duma.sh.in e58de00603 Restyled by shfmt 3 months ago
duma_hlp.h 9e7801793a Normalize some code styling with clang-format. 6 months ago
duma_sem.h 9e7801793a Normalize some code styling with clang-format. 6 months ago
dumapp.h f7be600db6 initial cmake support +fixes 3 months ago
gdbinit.rc c2da06f06b suggested ~/.gdbinit 13 years ago
make_git_source_version.sh 945d2e3e45 Minor POSIX portability fixup to script 2 months ago
noduma.h 9e7801793a Normalize some code styling with clang-format. 6 months ago
paging.h aee8697091 Restyled by clang-format 3 months ago
print.h cceb1b2d80 Automatic OS detection and additional reformatting. 1 year ago
renovate.json 06139a1f80 Format code with black, gofmt, yapf, autopep8, isort, standardrb, standardjs, prettier and rubocop 8 months ago
uninstall.cmake 5866db4d0a Restyled by whitespace 3 months ago

README.md

DUMA


license-gplv2 license-lgplv2.1 fossastatus loccount codesize release lgtm languagegrade-c languagegrade-javascript codacy codebeat deepscan deepsource-active deepsource-resolved tickgit


Detect Unintended Memory Access

A Red-Zone memory allocator



Description

DUMA helps you detect two of the most common programming errors:

  1. Software that overruns the boundaries of a malloc() memory allocation,
  2. Software that touches memory allocations already 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.

Electric Fence, the predecessor of DUMA, 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 catch-able bugs of this type, you'll have to read and understand the rest of the documentation.

Besides catching these kind of memory bugs, DUMA also provides a means to detect memory leaks. When using DUMA to pinpoint the source of a memory-leak, some source modification is necessary - at the minimum, adding #include "duma.h" to your source.


Installation

DUMA may be installed from compiled binary packages or built from source code.


Binary Packages

  • [TODO: Binary packages]
  • [TODO: Distro packages]

Building from source

  • The latest release version of DUMA is available to download from GitHub and other mirrors.

  • You can use the Git distributed version control tool to download the latest release version, the current development version, or the entire history, from any of several source code repositories.


GNU Make

DUMA may be built using GNU Make.

GNU Make is available for many operating systems, including SunOS / Solaris, GNU/Hurd, AIX, HP-UX, BSD, GNU/Linux, and Microsoft Windows (using Cygwin or UWIN for POSIX compatibility, or natively with the MSYS / MINGW environment.)

GNU Make is often installed as gmake, but may be installed under a different name, such as mingw32-make, mingw64-gmake, or simply make (especially on GNU systems such as Linux).

Some non-GNU "Make" systems may work, but are untested and not recommended for building DUMA.

  • Inside the unpacked DUMA source directory, create and change to a new build directory
    • mkdir build && cd build
  • (Optionally) review GNUmakefile for configuration, compilation, and installation options
    • Check the OS and OSTYPE options (necessary if automated detection is unsuccessful)
    • Check any other options or variables that may be available
  • Build DUMA
    • gmake -f ../GNUmakefile (for automatic OS detection and defaults)
    • gmake -f ../GNUmakefile OSTYPE=cygwin (for Microsoft Windows with Cygwin)
    • mingw32-make -f ../GNUmakefile OSTYPE=msys (for Microsoft Windows with MSYS / MINGW via Command Prompt (CMD))
    • make -f ../GNUmakefile OS=linux (for most GNU/Linux systems)
  • Test DUMA
    • gmake -f ../GNUmakefile check
  • Install DUMA
    • gmake -f ../GNUmakefile install DESTDIR=/opt/duma
    • It may be necessary to prefix this command with su, sudo, doas, etc. to elevate privileges, depending on the specified DESTDIR or prefix
  • Test DUMA installation
    • gmake -f ../GNUmakefile installcheck

CMake

CMake is a portable suite of tools to automate the configuration, building, testing, packaging, and installation of software.

DUMA may be built using CMake 3.1 (December 2014) or later.

  • Inside the unpacked DUMA source directory, create and change to a new build directory
    • mkdir build && cd build
  • (Optionally) interactively configure compilation and installation options
    • ccmake .. or
    • ccmake-gui ..
  • Generate the necessary build files
    • cmake ..
    • You may also specify options non-interactively, for example
    • cmake -DCMAKE_BUILD_TYPE="Debug" ..
    • cmake -DCMAKE_BUILD_TYPE="Release" ..
    • cmake -DCMAKE_INSTALL_PREFIX="/opt/duma" ..
    • cmake -DCMAKE_TOOLCHAIN_FILE=/opt/gcc/toolchain_gcc-8.cmake ..
    • cmake -G "Visual Studio 16 2019" -A "x64" ..
  • Build DUMA
    • cmake --build .
  • Test DUMA
    • ctest (add -V or -VV for more verbose output)
  • Install DUMA
    • cmake --build . --target "install"
    • It may be necessary to prefix this command with su, sudo, doas, etc. to elevate privileges, depending on the configured CMAKE_INSTALL_PREFIX

Visual Studio
  • Compile and execute createconf
    • Verify the duma_config.h header file generated by createconf
  • Compile dumalib
    • Customize your project's INCLUDE and LIBS variables, as required for your environment

Environment Notes

DUMA should work out of the box on most systems, however, specific environments may require additional configuration or warrant special consideration.


Solaris
  • Both SPARC and Intel processors are supported.

  • DUMA is tested on Solaris using the GNU toolchain (GNU CC, G++, ld, binutils, etc.)

    • Older Solaris systems, such as Solaris 10, using the GNU tools from the Companion CD should add /opt/sfw/bin and /opt/sfw/lib/bin to the PATH.

    • Newer Solaris systems, such as Solaris 11.next or OpenIndiana, require similar configuration.

  • The Solaris Studio toolchain has not been tested.


BSD
  • FreeBSD

    • On FreeBSD 6.2, it is necessary to set DUMA_DISABLE_BANNER=1 before running any program linked with DUMA.

    • NOTE: On FreeBSD 7.0 and later, there appears to be an incompatability with the new libthr, which is currently being investigated.


  • NetBSD

    • On NetBSD 3.1 (HOSTTYPE=i386 / OSTYPE=netbsdelf), one (1) memory leak is always detected.

    • Installation on NetBSD is untested.


ARM CPUs
  • On systems with ARM processors, it may be necessary to set the DUMA_MEMCPY_OVERLAP variable, which allows overlapping of memcpy() regions when the destination address is less than the source address.

MIPS CPUs
  • On systems with 64-bit MIPS processors (MIPS-III / IV / V, MIPS64, КОМДИВ-64, OCTEON, VR43xx, ICE9), it may be necessary to explicitly set the DUMA_ALIGNMENT environment variable to eight (8) bytes.

RISC-V CPUs
  • On systems using RISC-V processors, the base instruction set uses only fixed-length 32-bit instructions that must be aligned on four (4) byte (32-bit) boundaries.

  • However, the standard RISC-V encoding scheme supports compressed and variable-length instructions. These instructions can be any number of 16-bit "instruction parcels" in length, and are always aligned on two (2) byte (16-bit) boundaries.

  • The RISC-V processor will not fault when accessing an invalid (unaligned) address. Instead, it will simply use the next valid address. The DUMA_ALIGNMENT environment variable should be set to a value greater than one (1) on systems using RISC-V processors.


Usage

Static linking

  • Link your program with the library libduma.a. Make sure you are not linking with -lmalloc, -lmallocdebug, or with other malloc() debugger or 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.


Dynamic linking

  • If you're using a Bourne-style shell on most UNIX systems, the statement export LD_PRELOAD=libduma.so will cause DUMA to be loaded to run all dynamic executables.

  • For Darwin-based systems such as macOS X, use export DYLD_INSERT_LIBRARIES=libduma.dylib and export DYLD_FORCE_FLAT_NAMESPACE=1.

  • The included helper command duma <command> will run a single command under DUMA.

  • For more details, review the documentation for the dynamic linking facility provided by your operating system vendor.


Recommended Usage

  • 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 several configuration switches that can be enabled via the shell environment. These switches change what bugs DUMA will detect, so it's important that you know how to use them.

  • You can use the gdb command 'set environment variable value' to set shell environment variables only for the program you are going to debug. This is useful especially if you are using the shared DUMA library.

  • 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 the minimum required alignment specific to your environment by default. The minimum required alignment is detected by createconf and stored in the file duma_config.h.

If your program requires that allocations be aligned to 64-bit boundaries 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. For some architectures the default is defined to even more - x86‑64 uses alignment to 16 bytes by default.

DUMA internally uses a smaller value if the requested memory size is smaller than the alignment value: the next smaller power of 2 is used.

Thus allocating blocks smaller than DUMA_ALIGNMENT may result into smaller alignments - for example when allocating 3 bytes, they would be aligned to 2 byte boundary. This allows better detection of overrun.

For this reason, you will sometimes want to set DUMA_ALIGNMENT to 1 (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 call the macro function DUMA_SET_ALIGNMENT() from your code.

You don't need to change this setting, if you just need bigger alignment for some special buffers. In this case you may use the function memalign(alignment, userSize).

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

To change this value, set DUMA_PROTECT_BELOW in the shell environment to an integer value, or call the macro function DUMA_SET_PROTECT_BELOW() from your code.

  • DUMA_SKIPCOUNT_INIT - DUMA usually does its initialization with the first memory allocation. On some systems this may collide with initialization of pthreads or other libraries and produce a hang. To get DUMA work even in these situations you can control (with this environment variable) after how many allocations the full internal initialization of DUMA is done. Default is 0.

  • DUMA_REPORT_ALL_LEAKS - DUMA usually reports only memory leaks where the source file-name with line number of the allocating instruction is known. Setting this variable to 1 in shell environment reports all memory leaks. The default is 0 to avoid reporting of irrelevant memory leaks from system/compiler environment: there are many standard libraries leaking memory, which by default is no real problem as the system frees up all memory on program exit.

  • 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, DUMA does not initialize memory on allocation, so some memory may filled with zeroes (the operating system default on most systems) and some memory will retain the values written to it during its last use.

Per default, DUMA will initialize all allocated bytes to 255 (0xFF). To change this value, set DUMA_FILL in the shell environment to an integer value, or call the macro function DUMA_SET_FILL() from your code.

  • DUMA_SLACKFILL - As DUMA internally allocates memory in whole pages, there retains an unused and unprotectable piece of memory: the slack or no-mans-land. Per default DUMA will initialize this area to 170 (0xAA), which is 10101010 in binary representation.

To change this value, set DUMA_SLACKFILL in the shell environment to an integer value.

DUMA automatically checks this area, the no-mans-land, at deallocation. You can manually induce a check with the macro function DUMA_CHECK() for one memory block. With the macro function DUMA_CHECKALL() all memory blocks get checked.

  • DUMA_CHECK_FREQ - First see DUMA_SLACKFILL above for definition of no-mans-land. Checking the integrity of theno-mans-land costs performance. This is why this is usually done only at deallocation of a memory block. Set this variable to let DUMA check all memory blocks no-mans-land every *value*th allocation or deallocation. Set this variable to 1, to let DUMA check at each allocation and deallocation.

Per default the value 0 is used, which means to check only at deallocation.

  • DUMA_ALLOW_MALLOC_0 - Memory allocation of size zero is ANSI conforming, but, often this is the result of a software bug. For this reason DUMA may trap such calls to malloc() with size zero. I leave this option disabled by default, but you are free to trap these calls setting the DUMA_ALLOC_MALLOC_0 in the shell environment to an integer value.

  • DUMA_MALLOC_0_STRATEGY - This environment variable controls DUMA's behavior on malloc(0):

    • 0 - abort program with segfault (previously ALLOW_MALLOC_0 = 0)
    • 1 - return NULL pointer
    • 2 - return always the same pointer to some protected page
    • 3 - return mid address of a unique protected page (default)

    ATTENTION: Only 1 and 3 are ANSI conforming. But value 1 will break most programs, and value 3 strategy most system libraries use/implement. All returned pointers can be passed to free().

  • DUMA_NEW_0_STRATEGY - This environment variable controls DUMA's behavior on C++ operator new with size zero:

    • 2 - return always the same pointer to some protected page
    • 3 - return mid address of a unique protected page (default)

    ATTENTION: Only 3 is standard conforming. Value 2 may break some, but will work for most programs. With value 2 you may reduce the memory consumption.

  • DUMA_MALLOC_FAILEXIT - Many programs do not check for allocation failure. This often leads to delayed errors, no more understandable. Set this variable to a positive integer in the shell environment to exit the program immediately when memory allocation fails. This option is set by default.

  • 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 shell environment to -1. This is the default and will cause DUMA not to re-allocate any memory.

For programs with many allocations and de-allocations this may lead to the consumption of the full address space and thus to the failure of malloc(). It is important to discriminate between address space and physical memory; DUMA does free the physical memory; but the address space is not freed. Thus, the address space may be exhausted despite available physical memory. This is especially important on 32-bit systems. To avoid such failures, you may limit the amount of protected de-allocated memory by setting DUMA_PROTECT_FREE to a positive value. This value in kB will be the limit for such protected free memory.

A value of 0 will disable protection of freed memory.

  • DUMA_MAX_ALLOC - This shell environment variable limits the total memory print of a program. This is another way to indirectly limit the sum of freed protected memory (see DUMA_PROTECT_FREE). By default there is no limit (-1). A positive value is interpreted in kB, which stands for the sum of allocated and freed protected memory.

  • DUMA_FREE_ACCESS - This is a debugging enhancer to catch deallocation of a memory block using watch expressions. DUMA does a write access to the first byte, which may lead a debugger to stop on a watch expression. You have to enable this by setting the shell environment variable to non zero. Default is disabled.

  • DUMA_SHOW_ALLOC - Set this shell environment variable to non-zero to let DUMA print all allocations and de-allocations to the console. Although this generates a lot of messages, this option can be useful to detect inefficient code containing many (de)allocations. This is switched off by default.

  • DUMA_SUPPRESS_ATEXIT - Set this shell environment variable to non-zero when DUMA should skip the installation of its exit handler. The exit handler is called at the end of the main program and checks for memory leaks, so the handler's installation should usually not be suppressed. One reason for doing so regardless are some buggy environments, where calls to the standard C library's atexit()-function hangs.

  • DUMA_DISABLE_BANNER - Set this shell environment variable to non-zero to suppress the usual start-up message on console. Default is 0.

  • DUMA_OUTPUT_DEBUG - Set this shell environment variable to non-zero to output all DUMA messages to the debugging console. This option is only available on Windows and is off by default.

  • DUMA_OUTPUT_STDOUT - Set this shell environment variable to non-zero to output all DUMA messages to STDOUT. This option is off by default.

  • DUMA_OUTPUT_STDERR - Set this shell environment variable to non-zero to output all DUMA messages to STDERR. This option is on by default.

  • DUMA_OUTPUT_FILE - Set this shell environment variable to a file-name where all DUMA messages should be written to. This option is off by default.

  • DUMA_OUTPUT_STACKTRACE - Set this shell environment variable to non-zero to output a stacktrace of the allocation that is not freed. This option is available only on Windows and is off by default. This option also requires a map file generated by the linker.

  • DUMA_OUTPUT_STACKTRACE_MAPFILE - Set this shell environment variable to the map file, when it isn't found. This is very useful when using detours version of DUMA. This option is available only on Windows.

  • DUMA_MEMCPY_OVERLAP - Set this shell environment variable to allow overlapping of memcpy regions if the destination address is less than source address. (workaround for ARM memmove/memcpy implementation).


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 1. 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 set less than the system word-size is the strcmp() function and other string functions on SunOS 4, 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.


Catching the Erroneous Line

Using DUMA - and one of the following strategies - you can determine the offending line(s) of your source code responsible for causing an error.

Live (debugger control)

  1. Compile your program with debugging information and statically linked to DUMA. On some systems, including some Linux distributions, the linking order is crucial - DUMA must be the last library passed to the linker.
  2. Start your program from debugger e.g. with gdb <program>
  3. Set program environment variables such as 'set environment DUMA_PROTECT_BELOW 1'
  4. Set your program arguments with 'set args …'
  5. Run and wait for the segmentation fault

Post-mortem (core analysis)

  1. Compile your program (with debugging information).
  2. Set ulimit -c unlimited to get core files
  3. Start your program, choose one of following options
    • Start your program (linked statically with DUMA)
    • Start your program with duma.sh <your_program>
  4. Wait for a segmentation fault. This should have created a core[.<pid>] file, which you can examine (i.e. gdb <program> -c <core file>)

Debugging your Program

General Debugging Instructions

  1. Link with libduma.a as explained above, ensuring proper linking order.
  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 under-runs if they occur.
  6. Quit the debugger.
  7. Optionally, read and install gdbinit.rc as ~/.gdbinit if you are using the gdb debugger

Word-Alignment and Overrun Debugging

  • See if you can set DUMA_ALIGNMENT to 1, 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. It may be necessary to configure a swap file so the system will have enough virtual memory available. Also, the way DUMA manipulates 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 execute slower and use more resources while you are debugging it with DUMA.

    • The Linux kernel may limit the number of page mappings per process. See /proc/sys/vm/max_map_count. You may have to increase this value to allow debugging with DUMA with a command such as: sysctl -w vm.max_map_count=1000000
  • Don't leave libduma.a enabled and linked in production software. Use it only for debugging. See the section 'Compilation Notes for Release / Production' below.


Memory Leak Detection

  • All memory allocation is protocol-ed from DUMA together with the file-name and line number of the calling function. The atexit() function checks if each allocated memory block was freed. To disable leak detection add the preprocessor definition DUMA_SO_NO_LEAKDETECTION or DUMA_LIB_NO_LEAKDETECTION to DUMA_OPTIONS in the Makefile.

    • If a leak is reported without a source file-name or line number, but is reproducible with the same pointer, set a conditional breakpoint on the function void * duma_alloc_return( void * address), for example, using the gdb command 'break duma_alloc_return if address==0x123'

C++ Memory Operators and Leak Detection

  • Macros for "new" and "delete" are defined in dumapp.h. These macros give file-name and line number of the calling functions to DUMA, thus allowing the same leak detection reports as for malloc() and free(). dumapp.h needs to be included from your source file(s).

    • To disable the C++ new, delete, new[], and delete[] operators, add the preprocessor definition DUMA_NO_CPP_SUPPORT to DUMA_OPTIONS in Makefile.

Definition of own member new/delete Operators

  • Definition of own member new/delete operators for a class will fail because the new/delete keywords are defined as macros from DUMA. You will have to un-define DUMA's macros with following line: #include "noduma.h" Then you have to call DUMA's operators directly inside your own definition.

  • For using DUMA's C++ operators without having the preprocessor macros defined, following syntax can be used:

// const char * file  or  __FILE__ macro
// int          line  or  __LINE__ macro

// scalar new throwing bad_alloc() on error
ptr = new(file,line) type;

// scalar new returning 0 on error
ptr = new(std::nothrow,file,line) type;

// scalar delete
operator delete(ptr,file,line);

// vector new throwing bad_alloc() on error
ptr = new(file,line) type[n];

// vector new returning 0 on error
ptr = new(std::nothrow,file,line) type[n];

// vector delete
operator delete[](ptr, file,line);

Compilation Notes for Release/Production

  • Set the preprocessor definition #define DUMA_NO_DUMA in your Makefiles to disable DUMA usage - and don't link with DUMA library. With DUMA_NO_DUMA defined, all DUMA macro functions get defined, but do nothing.

    • This way, you don't have to change your code for release compilation, even when using special DUMA macros.

NO WARRANTY

  • This software has NO WARRANTY.

    • See the license for complete details.
  • Much effort has been expended to ensure the correctness of DUMA, however, it is (in all likelihood) not theoretically possible to make software of this nature bug-free.

    • DUMA may not report all bugs that exist in your code.

    • It may also incorrectly report bugs that do not exist.


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.


Bugs

  • Explanation of alignment issues 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. This is most likely an undocumented "feature" of particular Sun hardware versions, and not an operating system anomaly.

    • On these systems DUMA tests will fail with a bus error unless the Makefile is modified to define PAGE_PROTECTION_VIOLATED_SIGNAL as SIGBUS.

Comparison with other tools

  • [pending]

Availability

Releases

Git Repositories

NOTE: All source repositories are mirrors with identical contents.


Issue Tracking


Security Policy


Authors

 Copyright © 2020‑2021 Jeffrey H. Johnson <trnsz@pobox.com>
 Copyright © 2006 Michael Eddington <meddington@gmail.com>
 Copyright © 2002‑2021 Hayati Ayguen <h_ayguen@web.de>, Procitec GmbH
 Copyright © 1987‑1999 Bruce Perens <bruce@perens.com>

License


Version History