{"id":16164643,"url":"https://github.com/johnsonjh/duma","last_synced_at":"2025-04-05T09:06:18.278Z","repository":{"id":37830205,"uuid":"290107677","full_name":"johnsonjh/duma","owner":"johnsonjh","description":"duma: Detect Unintended Memory Access (D.U.M.A.) - A Red-Zone memory allocator","archived":false,"fork":false,"pushed_at":"2025-03-07T07:49:44.000Z","size":10719,"stargazers_count":108,"open_issues_count":52,"forks_count":12,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-03-29T08:05:39.067Z","etag":null,"topics":["allocator","c","duma","leak-detection","malloc"],"latest_commit_sha":null,"homepage":"https://github.com/johnsonjh/duma","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/johnsonjh.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"COPYING-GPL","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-08-25T03:57:59.000Z","updated_at":"2025-03-11T12:51:14.000Z","dependencies_parsed_at":"2024-01-17T18:31:50.472Z","dependency_job_id":"7c48ed86-02fc-496d-bf94-a8c37d9fd3a0","html_url":"https://github.com/johnsonjh/duma","commit_stats":null,"previous_names":[],"tags_count":51,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnsonjh%2Fduma","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnsonjh%2Fduma/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnsonjh%2Fduma/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnsonjh%2Fduma/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/johnsonjh","download_url":"https://codeload.github.com/johnsonjh/duma/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247312077,"owners_count":20918344,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["allocator","c","duma","leak-detection","malloc"],"created_at":"2024-10-10T02:47:19.688Z","updated_at":"2025-04-05T09:06:18.227Z","avatar_url":"https://github.com/johnsonjh.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DUMA\n\n---\n\n[![license-gplv2](https://img.shields.io/badge/license-GPL%20v2-blue.svg)](https://github.com/johnsonjh/duma/blob/master/COPYING-GPL)\n[![license-lgplv2.1](https://img.shields.io/badge/license-LGPL%20v2.1-blue.svg)](https://github.com/johnsonjh/duma/blob/master/COPYING-LGPL)\n[![fossastatus](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fjohnsonjh%2Fduma.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2Fjohnsonjh%2Fduma?ref=badge_shield)\n[![codesize](https://img.shields.io/github/languages/code-size/johnsonjh/duma.svg)](https://github.com/johnsonjh/duma)\n[![release](https://img.shields.io/github/release/johnsonjh/duma.svg)](https://github.com/johnsonjh/duma/releases/)\n[![codacy](https://api.codacy.com/project/badge/Grade/f777934d666b4a6a9672d89b404c4953)](https://app.codacy.com/gh/johnsonjh/duma?utm_source=github.com\u0026utm_medium=referral\u0026utm_content=johnsonjh/duma\u0026utm_campaign=Badge_Grade)\n[![codebeat](https://codebeat.co/badges/a0be6809-acda-41a7-96a8-0d46698dc42c)](https://codebeat.co/projects/github-com-johnsonjh-duma-master)\n[![deepscan](https://deepscan.io/api/teams/12184/projects/15170/branches/299583/badge/grade.svg)](https://deepscan.io/dashboard#view=project\u0026tid=12184\u0026pid=15170\u0026bid=299583)\n\n---\n\n## Detect Unintended Memory Access\n\nA Red-Zone memory allocator\n\n---\n\n\u003c!-- toc --\u003e\n\n- [DUMA](#duma)\n  - [Detect Unintended Memory Access](#detect-unintended-memory-access)\n    - [Description](#description)\n    - [Installation](#installation)\n      - [Binary Packages](#binary-packages)\n      - [Building from source](#building-from-source)\n        - [GNU Make](#gnu-make)\n        - [CMake](#cmake)\n        - [Visual Studio](#visual-studio)\n      - [Environment Notes](#environment-notes)\n        - [Solaris](#solaris)\n        - [BSD](#bsd)\n        - [ARM CPUs](#arm-cpus)\n        - [MIPS CPUs](#mips-cpus)\n        - [RISC-V CPUs](#risc-v-cpus)\n    - [Usage](#usage)\n      - [Static linking](#static-linking)\n      - [Dynamic linking](#dynamic-linking)\n      - [Recommended Usage](#recommended-usage)\n      - [Global and Environment Variables](#global-and-environment-variables)\n      - [Word-Alignment and Overrun Detection](#word-alignment-and-overrun-detection)\n    - [Catching the Erroneous Line](#catching-the-erroneous-line)\n      - [Live (debugger control)](#live-debugger-control)\n      - [Post-mortem (core analysis)](#post-mortem-core-analysis)\n    - [Debugging your Program](#debugging-your-program)\n      - [General Debugging Instructions](#general-debugging-instructions)\n      - [Word-Alignment and Overrun Debugging](#word-alignment-and-overrun-debugging)\n    - [Memory Usage and Execution Speed](#memory-usage-and-execution-speed)\n    - [Memory Leak Detection](#memory-leak-detection)\n    - [C++ Memory Operators and Leak Detection](#c-memory-operators-and-leak-detection)\n      - [Definition of own member new/delete Operators](#definition-of-own-member-newdelete-operators)\n    - [Compilation Notes for Release/Production](#compilation-notes-for-releaseproduction)\n    - [NO WARRANTY](#no-warranty)\n    - [Diagnostics](#diagnostics)\n      - [Bugs](#bugs)\n    - [Comparison with other tools](#comparison-with-other-tools)\n    - [Availability](#availability)\n      - [Releases](#releases)\n      - [Git Repositories](#git-repositories)\n    - [Issue Tracking](#issue-tracking)\n    - [Security Policy](#security-policy)\n    - [Authors](#authors)\n    - [License](#license)\n    - [Version History](#version-history)\n\n\u003c!-- tocstop --\u003e\n\n---\n\n### Description\n\n**DUMA** helps you detect two of the most common programming errors:\n\n1. Software that overruns the boundaries of a `malloc()` memory allocation,\n2. Software that touches memory allocations already released by `free()`.\n\nUnlike other `malloc()` debuggers, **DUMA** will detect read accesses as well as\nwrites, and it will pinpoint the exact instruction that causes an error.\n\n**Electric Fence**, the predecessor of **DUMA**, has been in use at _Pixar_\nsince 1987, and at many other sites for years.\n\n**DUMA** uses the virtual memory hardware of your computer to place an\ninaccessible memory page immediately after (_or before, at the user's option_)\neach memory allocation. When software reads or writes this inaccessible page,\nthe hardware issues a segmentation fault, stopping the program at the offending\ninstruction. It is then trivial to find the erroneous statement using your\nfavorite debugger. In a similar manner, memory that has been released by\n`free()` is made inaccessible, and any code that touches it will get a\nsegmentation fault.\n\nSimply linking your application with `libduma.a` will allow you to detect most,\nbut not all, `malloc()` buffer overruns and accesses of free memory. If you want\nto be reasonably sure that you've found all catch-able bugs of this type, you'll\nhave to read and understand the rest of the documentation.\n\nBesides catching these kind of memory bugs, **DUMA** also provides a means to\ndetect memory leaks. When using **DUMA** to pinpoint the source of a\nmemory-leak, some source modification is necessary - at the minimum, adding\n`#include \"duma.h\"` to your source.\n\n---\n\n### Installation\n\n**DUMA** may be installed from compiled binary packages or built\nfrom source code.\n\n---\n\n#### Binary Packages\n\n- [***TODO: Binary packages***]\n\n- Packages available for installation via the distribution's package manager:\\\n  [![Available distro packages](https://repology.org/badge/vertical-allrepos/duma.svg?header=)](https://repology.org/project/duma/packages)\n\n---\n\n#### Building from source\n\n- The latest release version of **DUMA** is available to download from\n  [GitHub](https://github.com/johnsonjh/duma/releases/latest)\n  and [other mirrors](https://github.com/johnsonjh/duma#releases).\n\n  - _NOTE_: If the latest release version is more than a few dozen commits\n    behind the master branch, you may wish to try the master branch instead\n    of the last release. While there are no guarantees made (for any release\n    of **DUMA**), best efforts are put forth to ensure the master branch\n    is functional and passes tests on Linux and Solaris.\n  - Pre-release versions are also available from\n    [GitHub](https://github.com/johnsonjh/duma/releases) and others mirrors.\n\n- You can use the _Git_ distributed version control tool to download\n  the latest release version, the current development version, or the\n  entire history, from any of several\n  [source code repositories](https://github.com/johnsonjh/duma#git-repositories).\n\n---\n\n##### GNU Make\n\n**DUMA** may be built using **_GNU_** **Make**.\n\n**_GNU_** **Make** is available for many operating systems, including\n_SunOS_ / _Solaris_, _GNU/Hurd_, _AIX_, _HP-UX_, _BSD_, _GNU/Linux_, and\n_Microsoft Windows_ (using _Cygwin_ or _UWIN_ for POSIX compatibility, or\nnatively with the _MSYS_ / _MINGW_ environment.)\n\n**_GNU_** **Make** is often installed as `gmake`, but may be installed under\na different name, such as `mingw32-make`, `mingw64-gmake`, or simply `make`\n(_especially on_ **_GNU_** _systems such as Linux_).\n\nSome **_non_**-**_GNU_** \"**Make**\" systems **_may_** work, but are\n**_untested_** and **not** **recommended** for building **DUMA**.\n\n- Inside the unpacked **DUMA** source directory, create and change to a\n  new `build` directory\n  - `mkdir build \u0026\u0026 cd build`\n- (_Optionally_) review `GNUmakefile` for configuration, compilation,\n  and installation options\n  - Check the `OS` and `OSTYPE` options\n    (_necessary if automated detection is unsuccessful_)\n  - Check any other options or variables that may be available\n- Build **DUMA**\n  - `gmake -f ../GNUmakefile srcdir=../`\n    (_for automatic OS detection and defaults; assumes gmake is GNU Make_)\n  - `make -f ../GNUmakefile srcdir=../ OSTYPE=cygwin`\n    (_for Microsoft Windows with Cygwin_)\n  - `mingw32-make -f ../GNUmakefile srcdir=../ OSTYPE=msys`\n    (_for Microsoft Windows with MSYS / MINGW via Command Prompt (CMD)_)\n  - `make -f ../GNUmakefile srcdir=../ OS=linux`\n    (_for most GNU/Linux systems_)\n- Test **DUMA**\n  - `gmake -f ../GNUmakefile check`\n- Install **DUMA**\n  - `gmake -f ../GNUmakefile install DESTDIR=/opt/duma`\n    - It may be necessary to prefix this command with\n      **_su_**, **_sudo_**, **_doas_**, _etc._ to elevate privileges,\n      depending on the specified `DESTDIR` or `prefix`\n- Test **DUMA** installation\n  - `gmake -f ../GNUmakefile installcheck`\n\n---\n\n##### CMake\n\n**CMake** is a portable suite of tools to automate the configuration,\nbuilding, testing, packaging, and installation of software.\n\n**DUMA** may be built using **CMake** 3.1 (_December 2014_) or later.\n\n- Inside the unpacked **DUMA** source directory, create and change to a\n  new `build` directory\n  - `mkdir build \u0026\u0026 cd build`\n- (_Optionally_) interactively configure compilation and installation options\n  - `ccmake ..` _or_\n  - `ccmake-gui ..`\n- Generate the necessary build files\n  - `cmake ..`\n    - You may also specify options non-interactively, for example\n    - `cmake -DCMAKE_BUILD_TYPE=\"Debug\" ..`\n    - `cmake -DCMAKE_BUILD_TYPE=\"Release\" ..`\n    - `cmake -DCMAKE_INSTALL_PREFIX=\"/opt/duma\" ..`\n    - `cmake -DCMAKE_TOOLCHAIN_FILE=/opt/gcc/toolchain_gcc-8.cmake ..`\n    - `cmake -G \"Visual Studio 16 2019\" -A \"x64\" ..`\n      - _Refer to the\n        [CMake Manual](https://cmake.org/cmake/help/latest/manual)\n        for full details_\n- Build **DUMA**\n  - `cmake --build .`\n- Test **DUMA**\n  - `ctest` (_add_ `-V` _or_ `-VV` _for more verbose output_)\n- Install **DUMA**\n  - `cmake --build . --target \"install\"`\n    - It may be necessary to prefix this command with\n      **_su_**, **_sudo_**, **_doas_**, _etc._ to elevate privileges,\n      depending on the configured `CMAKE_INSTALL_PREFIX`\n\n---\n\n##### Visual Studio\n\n- Compile and execute `createconf`\n  - Verify the `duma_config.h` header file generated by `createconf`\n- Compile `dumalib`\n  - Customize your project's `INCLUDE` and `LIBS` variables, as required\n    for your environment\n\n---\n\n#### Environment Notes\n\n**DUMA** should work out of the box on most systems, however, specific\nenvironments may require additional configuration or warrant special\nconsideration.\n\n---\n\n##### Solaris\n\n- Both _SPARC_ and _Intel_ processors are supported.\n\n- **DUMA** is tested on _Solaris_ using the GNU toolchain\n  (_GNU CC, G++, ld, binutils, etc._)\n\n  - Older _Solaris_ systems, such as _Solaris 10_, using the GNU tools from\n    the _Companion CD_ should add `/opt/sfw/bin` and `/opt/sfw/lib/bin` to\n    the `PATH`.\n\n  - Newer _Solaris_ systems, such as _Solaris 11.next_ or _OpenIndiana_,\n    require similar configuration.\n\n- The _Solaris Studio_ toolchain has not been tested.\n\n---\n\n##### BSD\n\n- **FreeBSD**\n\n  - On _FreeBSD_ 6.2, it is necessary to set `DUMA_DISABLE_BANNER=1`\n    before running any program linked with **DUMA**.\n  - NOTE: On _FreeBSD_ 7.0 and later, there appears to be an\n    incompatability with the new libthr, which is currently being\n    investigated.\n\n---\n\n- **NetBSD**\n\n  - On _NetBSD_ 3.1 (`HOSTTYPE=i386` / `OSTYPE=netbsdelf`), one (`1`)\n    memory leak is always detected.\n\n  - Installation on _NetBSD_ is untested.\n\n---\n\n##### ARM CPUs\n\n- On systems with _ARM_ processors, it may be necessary to set the\n  `DUMA_MEMCPY_OVERLAP` variable, which allows overlapping of `memcpy()`\n  regions when the destination address is less than the source address.\n\n---\n\n##### MIPS CPUs\n\n- On systems with 64-bit _MIPS_ processors (_MIPS_-_III_ / _IV_ / _V_, _MIPS64_,\n  _КОМДИВ-64_, _OCTEON_, _VR43xx_, _ICE9_), it may be necessary to explicitly\n  set the `DUMA_ALIGNMENT` environment variable to eight (`8`) bytes.\n\n---\n\n##### RISC-V CPUs\n\n- On systems using _RISC-V_ processors, the base instruction set uses only\n  fixed-length 32-bit instructions that must be aligned on four (`4`) byte\n  (_32-bit_) boundaries.\n\n- However, the standard _RISC-V_ encoding scheme supports _compressed_\n  and _variable-length_ instructions. These instructions can be any\n  number of 16-bit _\"instruction parcels\"_ in length, and are always\n  aligned on two (`2`) byte (_16-bit_) boundaries.\n\n- The _RISC-V_ processor will not fault when accessing an invalid (_unaligned_)\n  address. Instead, it will simply use the next valid address. The `DUMA_ALIGNMENT`\n  environment variable should be set to a value greater than one (`1`)\n  on systems using _RISC-V_ processors.\n\n---\n\n### Usage\n\n#### Static linking\n\n- Link your program with the library `libduma.a`. Make sure you are not linking\n  with `-lmalloc`, `-lmallocdebug`, or with other `malloc()` debugger or\n  enhancer libraries. You can only use one at a time.\n\n- If your system administrator has installed **DUMA** for public use, you'll be\n  able to use the `-lduma` argument to the linker, otherwise you'll have to put\n  the path-name for `libduma.a` in the linker's command line.\n\n---\n\n#### Dynamic linking\n\n- If you're using a Bourne-style shell on\n  most _UNIX_ systems, the statement `export LD_PRELOAD=libduma.so` will cause\n  **DUMA** to be loaded to run all dynamic executables.\n\n- For _Darwin_-based\n  systems such as macOS X, use `export DYLD_INSERT_LIBRARIES=libduma.dylib`\n  and `export DYLD_FORCE_FLAT_NAMESPACE=1`.\n\n- The included helper command `duma \u003ccommand\u003e` will run a single command\n  under **DUMA**.\n\n- For more details, review the documentation for the dynamic linking\n  facility provided by your operating system vendor.\n\n---\n\n#### Recommended Usage\n\n- Some systems will require special arguments to the linker to assure that you\n  are using the **DUMA** `malloc()` and not the one from your C library.\n\n- Run your program using a debugger. It's easier to work this way than to create\n  a core file and post-mortem debug it. **DUMA** can create huge core files, and\n  some operating systems will thus take minutes simply to dump core! Some\n  operating systems will not create usable core files from programs that are\n  linked with **DUMA**.\n\n- If your program has one of the errors detected by **DUMA**, it will get a\n  segmentation fault (`SIGSEGV`) at the offending instruction. Use the debugger\n  to locate the erroneous statement, and repair it.\n\n---\n\n#### Global and Environment Variables\n\n**DUMA** has several configuration switches that can be enabled via the shell\nenvironment. These switches change what bugs **DUMA** will detect, so it's\nimportant that you know how to use them.\n\n- You can use the `gdb` command `'set environment variable value'` to set shell\n  environment variables only for the program you are going to debug. This is\n  useful especially if you are using the shared **DUMA** library.\n\n- `DUMA_ALIGNMENT` - This is an integer that specifies the alignment for any\n  memory allocations that will be returned by malloc(), calloc(), and realloc().\n  The value is specified in bytes, thus a value of 4 will cause memory to be\n  aligned to 32-bit boundaries unless your system doesn't have a 8-bit\n  characters. `DUMA_ALIGNMENT` is set to the minimum required alignment specific\n  to your environment by default. The minimum required alignment is detected by\n  `createconf` and stored in the file `duma_config.h`.\n\n  If your program requires that allocations be aligned to 64-bit boundaries\n  you'll have to set this value to 8. This is the case when compiling with the\n  `-mips2` flag on _MIPS_-based systems such as those from _SGI_. For some\n  architectures the default is defined to even more - x86‑64 uses alignment to\n  16 bytes by default.\n\n  **DUMA** internally uses a smaller value if the requested memory size is\n  smaller than the alignment value: the next smaller power of 2 is used.\n\n  Thus allocating blocks smaller than `DUMA_ALIGNMENT` may result into smaller\n  alignments - for example when allocating 3 bytes, they would be aligned to 2\n  byte boundary. This allows better detection of overrun.\n\n  For this reason, you will sometimes want to set `DUMA_ALIGNMENT` to `1` (no\n  alignment), so that you can detect overruns of less than your CPU's word size.\n  Be sure to read the section '_Word-Alignment and Overrun Detection_' in this\n  manual page before you try this.\n\n  To change this value, set `DUMA_ALIGNMENT` in the shell environment to an\n  integer value, or call the macro function `DUMA_SET_ALIGNMENT()` from your\n  code.\n\n  You don't need to change this setting, if you just need bigger alignment for\n  some special buffers. In this case you may use the function\n  `memalign(alignment, userSize)`.\n\n- `DUMA_PROTECT_BELOW` - **DUMA** usually places an inaccessible page\n  immediately after each memory allocation, so that software that runs past the\n  end of the allocation will be detected. Setting `DUMA_PROTECT_BELOW` to `1`\n  causes **DUMA** to place the inaccessible page before the allocation in the\n  address space, so that under-runs will be detected instead of over-runs.\n\n  To change this value, set `DUMA_PROTECT_BELOW` in the shell environment to an\n  integer value, or call the macro function `DUMA_SET_PROTECT_BELOW()` from your\n  code.\n\n- `DUMA_SKIPCOUNT_INIT` - **DUMA** usually does its initialization with the\n  first memory allocation. On some systems this may collide with initialization\n  of pthreads or other libraries and produce a hang. To get **DUMA** work even in\n  these situations you can control (with this environment variable) after how\n  many allocations the full internal initialization of **DUMA** is done. Default\n  is `0`.\n\n- `DUMA_REPORT_ALL_LEAKS` - **DUMA** usually reports only memory leaks where the\n  source file-name with line number of the allocating instruction is known.\n  Setting this variable to `1` in shell environment reports all memory leaks.\n  The default is `0` to avoid reporting of irrelevant memory leaks from\n  system/compiler environment: there are many standard libraries leaking memory,\n  which by default is no real problem as the system frees up all memory on\n  program exit.\n\n- `DUMA_FILL` - When set to a value between `0` and `255`, every byte of\n  allocated memory is initialized to that value. This can help detect reads of\n  uninitialized memory. When set to `-1`, **DUMA** does not initialize memory on\n  allocation, so some memory may filled with zeroes (the operating system\n  default on most systems) and some memory will retain the values written to it\n  during its last use.\n\n  Per default, **DUMA** will initialize all allocated bytes to `255` (`0xFF`).\n  To change this value, set `DUMA_FILL` in the shell environment to an integer\n  value, or call the macro function `DUMA_SET_FILL()` from your code.\n\n- `DUMA_SLACKFILL` - As **DUMA** internally allocates memory in whole pages,\n  there retains an unused and unprotectable piece of memory: the slack or\n  _no-mans-land_. Per default **DUMA** will initialize this area to `170`\n  (`0xAA`), which is `10101010` in binary representation.\n\n  To change this value, set `DUMA_SLACKFILL` in the shell environment to an\n  integer value.\n\n  **DUMA** automatically checks this area, the _no-mans-land_, at deallocation.\n  You can manually induce a check with the macro function `DUMA_CHECK()` for one\n  memory block. With the macro function `DUMA_CHECKALL()` all memory blocks get\n  checked.\n\n- `DUMA_CHECK_FREQ` - First see `DUMA_SLACKFILL` above for definition of\n  _no-mans-land_. Checking the integrity of the*no-mans-land* costs\n  performance. This is why this is usually done only at deallocation of a memory\n  block. Set this variable to let **DUMA** check all memory blocks\n  _no-mans-land_ every *value*th allocation or deallocation. Set this variable\n  to 1, to let **DUMA** check at each allocation and deallocation.\n\n  Per default the value `0` is used, which means to check only at deallocation.\n\n- `DUMA_ALLOW_MALLOC_0` - Memory allocation of size zero is _ANSI_ conforming,\n  but, often this is the result of a software bug. For this reason **DUMA** may\n  trap such calls to malloc() with size zero. I leave this option disabled by\n  default, but you are free to trap these calls setting the\n  `DUMA_ALLOC_MALLOC_0` in the shell environment to an integer value.\n\n- `DUMA_MALLOC_0_STRATEGY` - This environment variable controls **DUMA**'s\n  behavior on `malloc(0)`:\n\n  - `0` - abort program with segfault (previously `ALLOW_MALLOC_0 = 0`)\n  - `1` - return NULL pointer\n  - `2` - return always the same pointer to some protected page\n  - `3` - return mid address of a unique protected page (**_default_**)\n\n    **_ATTENTION_**: Only `1` and `3` are _ANSI_ conforming. But value `1`\n    will break most programs, and value `3` strategy most system libraries\n    use/implement. All returned pointers can be passed to `free()`.\n\n- `DUMA_NEW_0_STRATEGY` - This environment variable controls **DUMA**'s\n  behavior on C++ operator new with size zero:\n\n  - `2` - return always the same pointer to some protected page\n  - `3` - return mid address of a unique protected page (**_default_**)\n\n    **_ATTENTION_**: Only `3` is standard conforming. Value `2` may break\n    some, but will work for most programs. With value `2` you may reduce the\n    memory consumption.\n\n- `DUMA_MALLOC_FAILEXIT` - Many programs do not check for allocation failure.\n  This often leads to delayed errors, no more understandable. Set this variable\n  to a positive integer in the shell environment to exit the program immediately\n  when memory allocation fails. This option is set by default.\n\n- `DUMA_PROTECT_FREE` - **DUMA** usually returns free memory to a pool from\n  which it may be re-allocated. If you suspect that a program may be touching\n  free memory, set `DUMA_PROTECT_FREE` shell environment to `-1`. This is the\n  default and will cause **DUMA** not to re-allocate any memory.\n\n  For programs with many allocations and de-allocations this may lead to the\n  consumption of the full address space and thus to the failure of `malloc()`.\n  It is important to discriminate between _address space_ and _physical memory_;\n  **DUMA** does free the _physical memory_; but the _address space_ is not\n  freed. Thus, the _address space_ may be exhausted despite available _physical\n  memory_. This is especially important on 32-bit systems. To avoid such\n  failures, you may limit the amount of protected de-allocated memory by setting\n  `DUMA_PROTECT_FREE` to a positive value. This value in **kB** will be the\n  limit for such protected free memory.\n\n  A value of `0` will disable protection of freed memory.\n\n- `DUMA_MAX_ALLOC` - This shell environment variable limits the total memory\n  print of a program. This is another way to indirectly limit the sum of freed\n  protected memory (see `DUMA_PROTECT_FREE`). By default there is no limit\n  (`-1`). A positive value is interpreted in **kB**, which stands for the sum of\n  allocated and freed protected memory.\n\n- `DUMA_FREE_ACCESS` - This is a debugging enhancer to catch deallocation of a\n  memory block using watch expressions. **DUMA** does a write access to the\n  first byte, which may lead a debugger to stop on a watch expression. You have\n  to enable this by setting the shell environment variable to non zero. Default\n  is disabled.\n\n- `DUMA_SHOW_ALLOC` - Set this shell environment variable to non-zero to let\n  DUMA print all allocations and de-allocations to the console. Although this\n  generates a lot of messages, this option can be useful to detect inefficient\n  code containing many (de)allocations. This is switched off by default.\n\n- `DUMA_SUPPRESS_ATEXIT` - Set this shell environment variable to non-zero when\n  DUMA should skip the installation of its exit handler. The exit handler is\n  called at the end of the main program and checks for memory leaks, so the\n  handler's installation should **_usually_** not be suppressed. One reason for\n  doing so regardless are some buggy environments, where calls to the standard C\n  library's `atexit()`-function hangs.\n\n- `DUMA_DISABLE_BANNER` - Set this shell environment variable to non-zero to\n  suppress the usual start-up message on console. Default is `0`.\n\n- `DUMA_OUTPUT_DEBUG` - Set this shell environment variable to non-zero to\n  output all DUMA messages to the debugging console. This option is only\n  available on Windows and is off by default.\n\n- `DUMA_OUTPUT_STDOUT` - Set this shell environment variable to non-zero to\n  output all DUMA messages to _STDOUT_. This option is off by default.\n\n- `DUMA_OUTPUT_STDERR` - Set this shell environment variable to non-zero to\n  output all DUMA messages to _STDERR_. This option is on by default.\n\n- `DUMA_OUTPUT_FILE` - Set this shell environment variable to a file-name where\n  all DUMA messages should be written to. This option is off by default.\n\n- `DUMA_OUTPUT_STACKTRACE` - Set this shell environment variable to non-zero to\n  output a stacktrace of the allocation that is not freed. This option is\n  available only on Windows and is off by default. This option also requires a\n  map file generated by the linker.\n\n- `DUMA_OUTPUT_STACKTRACE_MAPFILE` - Set this shell environment variable to the\n  map file, when it isn't found. This is very useful when using detours version\n  of DUMA. This option is available only on Windows.\n\n- `DUMA_MEMCPY_OVERLAP` - Set this shell environment variable to allow\n  overlapping of memcpy regions if the destination address is less than source\n  address. (workaround for _ARM_ `memmove`/`memcpy` implementation).\n\n---\n\n#### Word-Alignment and Overrun Detection\n\nThere is a conflict between the alignment restrictions that `malloc()` operates\nunder and the debugging strategy used by **DUMA**. When detecting overruns,\n**DUMA** `malloc()` allocates two or more virtual memory pages for each\nallocation. The last page is made inaccessible in such a way that any read,\nwrite, or execute access will cause a segmentation fault. Then, **DUMA**\n`malloc()` will return an address such that the first byte after the end of the\nallocation is on the inaccessible page. Thus, any overrun of the allocation will\ncause a segmentation fault.\n\nIt follows that the address returned by `malloc()` is the address of the\ninaccessible page minus the size of the memory allocation. Unfortunately,\n`malloc()` is required to return _word-aligned_ allocations, since many CPUs can\nonly access a word when its address is aligned. The conflict happens when\nsoftware makes a memory allocation using a size that is not a multiple of the\nword size, and expects to do word accesses to that allocation. The location of\nthe inaccessible page is fixed by hardware at a _word-aligned_ address. If\n**DUMA** `malloc()` is to return an aligned address, it must increase the size\nof the allocation to a multiple of the word size.\n\nIn addition, the functions `memalign()` and `valloc()` must honor explicit\nspecifications on the alignment of the memory allocation, and this, as well can\nonly be implemented by increasing the size of the allocation. Thus, there will\nbe situations in which the end of a memory allocation contains some padding\nspace, and accesses of that padding space will not be detected, even if they are\noverruns.\n\n**DUMA** provides the variable `DUMA_ALIGNMENT` so that the user can control the\ndefault alignment used by `malloc()`, `calloc()`, and `realloc()`. To debug\noverruns as small as a single byte, you can set `DUMA_ALIGNMENT` to `1`. This\nwill result in **DUMA** `malloc()` returning unaligned addresses for allocations\nwith sizes that are not a multiple of the word size. This is not a problem in\nmost cases, because compilers must pad the size of objects so that alignment\nrestrictions are honored when storing those objects in arrays. The problem\nsurfaces when software allocates odd-sized buffers for objects that must be\n_word-aligned_. One case of this is software that allocates a buffer to contain\na structure and a string, and the string has an odd size (this example was in a\npopular _TIFF_ library).\n\nIf word references are made to un-aligned buffers, you will see a bus error\n(`SIGBUS`) instead of a segmentation fault. The only way to fix this is to\nre-write the offending code to make byte references or not make odd-sized\nallocations, or to set `DUMA_ALIGNMENT` to the word size.\n\nAnother example of software incompatible with `DUMA_ALIGNMENT` set less than\nthe system _word-size_ is the `strcmp()` function and other string functions\non _SunOS_ 4, which make _word-sized_ accesses to character strings, and may\nattempt to access up to three bytes **_beyond_** the end of a string. These\nresult in a segmentation fault (`SIGSEGV`). The only way around this is to use\nversions of the string functions that perform _byte references_ instead of\n_word references_.\n\n---\n\n### Catching the Erroneous Line\n\nUsing **DUMA** - and one of the following strategies - you can determine the\noffending line(s) of your source code responsible for causing an error.\n\n#### Live (debugger control)\n\n1. Compile your program with debugging information and statically linked to\n   DUMA. On some systems, including some Linux distributions, the linking order\n   is crucial - **DUMA** must be the last library passed to the linker.\n2. Start your program from debugger e.g. with `gdb \u003cprogram\u003e`\n3. Set program environment variables such as\n   `'set environment DUMA_PROTECT_BELOW 1'`\n4. Set your program arguments with `'set args …'`\n5. Run and wait for the segmentation fault\n\n#### Post-mortem (core analysis)\n\n1. Compile your program (**_with_** debugging information).\n2. Set `ulimit -c unlimited` to get core files\n3. Start your program, choose one of following options\n   - Start your program (linked **_statically_** with **DUMA**)\n   - Start your program with `duma.sh \u003cyour_program\u003e`\n4. Wait for a segmentation fault. This should have created a `core[.\u003cpid\u003e]`\n   file, which you can examine (i.e. `gdb \u003cprogram\u003e -c \u003ccore file\u003e`)\n\n---\n\n### Debugging your Program\n\n#### General Debugging Instructions\n\n1. Link with `libduma.a` as explained above, ensuring proper linking order.\n2. Run your program in a debugger and fix any overruns or accesses to free\n   memory.\n3. Quit the debugger.\n4. Set `DUMA_PROTECT_BELOW = 1` in the shell environment.\n5. Repeat step 2, this time repairing under-runs if they occur.\n6. Quit the debugger.\n7. Optionally, read and install `gdbinit.rc` as `~/.gdbinit` if you are using\n   the `gdb` debugger\n\n#### Word-Alignment and Overrun Debugging\n\n- See if you can set `DUMA_ALIGNMENT` to `1`, and repeat step 2.\n  - Sometimes this will be too much work, or there will be problems with library\n    routines for which you don't have the source, that will prevent you from\n    doing this.\n\n---\n\n### Memory Usage and Execution Speed\n\n- Since **DUMA** uses at least two virtual memory pages for each of its\n  allocations, it's a terrible memory hog. It may be necessary to configure a\n  swap file so the system will have enough virtual memory available. Also, the\n  way **DUMA** manipulates memory results in various cache and translation\n  buffer entries being flushed with each call to `malloc()` or `free()`. The end\n  result is that your program will execute slower and use more resources while\n  you are debugging it with **DUMA**.\n\n  - The Linux kernel may limit the number of page mappings per process. See\n    `/proc/sys/vm/max_map_count`. You may have to increase this value to allow\n    debugging with **DUMA** with a command such as:\n    `sysctl -w vm.max_map_count=1000000`\n\n- **Don't** leave `libduma.a` enabled and linked in production software. Use it\n  only for debugging. See the section '_Compilation Notes for\n  Release / Production_' below.\n\n---\n\n### Memory Leak Detection\n\n- All memory allocation is protocol-ed from **DUMA** together with the file-name\n  and line number of the calling function. The `atexit()` function checks if each\n  allocated memory block was freed. To disable leak detection add the\n  preprocessor definition `DUMA_SO_NO_LEAKDETECTION` or\n  `DUMA_LIB_NO_LEAKDETECTION` to `DUMA_OPTIONS` in the Makefile.\n\n  - If a leak is reported without a source file-name or line number, but is\n    reproducible with the same pointer, set a conditional breakpoint on the\n    function `void * duma_alloc_return( void * address)`, for example, using the\n    **gdb** command `'break duma_alloc_return if address==0x123'`\n\n---\n\n### C++ Memory Operators and Leak Detection\n\n- Macros for \"`new`\" and \"`delete`\" are defined in `dumapp.h`. These macros give\n  file-name and line number of the calling functions to **DUMA**, thus allowing\n  the same leak detection reports as for `malloc()` and `free()`. `dumapp.h` needs to be\n  included from your source file(s).\n\n  - To disable the C++ `new`, `delete`, `new[]`, and `delete[]` operators, add\n    the preprocessor definition `DUMA_NO_CPP_SUPPORT` to `DUMA_OPTIONS` in\n    Makefile.\n\n---\n\n#### Definition of own member new/delete Operators\n\n- Definition of own member `new`/`delete` operators for a class will fail\n  because the `new`/`delete` keywords are defined as macros from **DUMA**. You\n  will have to un-define **DUMA**'s macros with following line:\n  `#include \"noduma.h\"` Then you have to call **DUMA**'s operators directly\n  inside your own definition.\n\n- For using **DUMA**'s C++ operators without having the preprocessor macros\n  defined, following syntax can be used:\n\n```c++\n// const char * file  or  __FILE__ macro\n// int          line  or  __LINE__ macro\n\n// scalar new throwing bad_alloc() on error\nptr = new(file,line) type;\n\n// scalar new returning 0 on error\nptr = new(std::nothrow,file,line) type;\n\n// scalar delete\noperator delete(ptr,file,line);\n\n// vector new throwing bad_alloc() on error\nptr = new(file,line) type[n];\n\n// vector new returning 0 on error\nptr = new(std::nothrow,file,line) type[n];\n\n// vector delete\noperator delete[](ptr, file,line);\n```\n\n---\n\n### Compilation Notes for Release/Production\n\n- Set the preprocessor definition `#define DUMA_NO_DUMA` in your Makefiles to\n  disable **DUMA** usage - and don't link with **DUMA** library. With\n  `DUMA_NO_DUMA` defined, all **DUMA** macro functions get defined, but do\n  nothing.\n\n  - This way, you don't have to change your code for release compilation, even\n    when using special **DUMA** macros.\n\n---\n\n### NO WARRANTY\n\n- This software has **_NO WARRANTY_**.\n\n  - **_See the [license](#license) for complete details._**\n\n- Much effort has been expended to ensure the correctness of **DUMA**,\n  however, it is (in all likelihood) not theoretically possible to make\n  software of this nature **_bug-free_**.\n\n  - **DUMA** **_may not_** report all bugs that exist in your code.\n\n  - It may also **_incorrectly_** report bugs that do not exist.\n\n---\n\n### Diagnostics\n\n- **_Segmentation Fault_**: Examine the offending statement for violation of the\n  boundaries of a memory allocation.\n\n- **_Bus Error_**: See the section on _'Word-Alignment and Overrun Detection'_\n  in this manual.\n\n---\n\n#### Bugs\n\n- Explanation of alignment issues could be improved.\n\n- Some **Sun** systems running **SunOS** **4.1** were reported to signal an\n  access to a protected page with `SIGBUS` rather than `SIGSEGV`. This is\n  most likely an undocumented \"_feature_\" of particular _Sun_ hardware\n  versions, and not an operating system anomaly.\n  - On these systems **DUMA** tests will fail with a _bus error_ unless the\n    `Makefile` is modified to define `PAGE_PROTECTION_VIOLATED_SIGNAL`\n    as `SIGBUS`.\n\n---\n\n### Comparison with other tools\n\n- **_[pending]_**\n\n---\n\n### Availability\n\n#### Releases\n\n- [GitHub Releases](https://github.com/johnsonjh/duma/releases)\n\n#### Git Repositories\n\n**_NOTE_**: _All source repositories are mirrors with identical contents._\n\n- [GitHub](https://github.com/johnsonjh/duma)\n- [GitLab](https://gitlab.com/johnsonjh/duma)\n- [SourceHut](https://sr.ht/~trn/duma)\n- [NotABug](https://notabug.org/trn/duma)\n\n---\n\n### Issue Tracking\n\n- [GitHub Issue Tracker](https://github.com/johnsonjh/duma/issues)\n\n---\n\n### Security Policy\n\n- [Security Policy and Vulnerability Reporting](https://github.com/johnsonjh/duma/security/policy)\n\n---\n\n### Authors\n\n```text\n Copyright © 2020‑2022 Jeffrey H. Johnson \u003ctrnsz@pobox.com\u003e\n Copyright © 2006 Michael Eddington \u003cmeddington@gmail.com\u003e\n Copyright © 2002‑2021 Hayati Ayguen \u003ch_ayguen@web.de\u003e, Procitec GmbH\n Copyright © 1987‑1999 Bruce Perens \u003cbruce@perens.com\u003e\n```\n\n---\n\n### License\n\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;[![FOSSASmallStatus](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fjohnsonjh%2Fduma.svg?type=small)](https://app.fossa.com/projects/git%2Bgithub.com%2Fjohnsonjh%2Fduma?ref=badge_small)\n\n- [GNU General Public License v2.0 (GPLv2)](https://tldrlegal.com/license/gnu-general-public-license-v2)\n\n- [GNU Lesser General Public License v2.1 (LGPLv2.1)](\u003chttps://tldrlegal.com/license/gnu-lesser-general-public-license-v2.1-(lgpl-2.1)\u003e)\n\n---\n\n### Version History\n\n- [Version History](https://github.com/johnsonjh/duma/blob/master/CHANGELOG.md)\n\n---\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohnsonjh%2Fduma","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjohnsonjh%2Fduma","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohnsonjh%2Fduma/lists"}