libdlmalloc

libdlmalloc is a python script designed for use with GDB that can be used to analyse the Doug Lea's allocator, aka dlmalloc. It currently supports dlmalloc 2.8.x versions. Note that some parts can also be used independently GDB, for instance to do offline analysis of some snapshotted heap memory.

libdlmalloc was inspired by other gdb python scripts for analyzing heaps like libtalloc, unmask_jemalloc and libheap. Some basic functionality is almost identical to these projects.

Supported versions

libdlmalloc has been tested predominately on 32-bit and 64-bit Cisco ASA devices which use dlmalloc 2.8.3. It should work with other 2.8.x versions, however due to significant differences it will not work on earlier releases, such as <= 2.7.x.

If you successfully test libdlmalloc on some specific 2.8.x release or some specific device, please let the authors know and we will update the documents.

Installation

The script just requires a relatively modern version of GDB with python3 support. We have primarily tested on python3, so we expect it will break on python2.7 atm.

If you want to use the gdb commands you can use:

    (gdb) source libdlmalloc_28x.py

A bunch of the core logic is broken out into the dl_helper class, which allows you to directly import libdlmalloc and access certain important structures outside of a GDB session. This is useful if you want to analyze offline chunk/heap snapshots.

Usage

Most of the functionality is modelled after the approach in unmask_jemalloc and libtalloc where a separate GDB command is provided. Though we do also use a fair number of switches.

To see a full list of currently supported commands you can use the dlhelp command:

dlhelp

This is the main function to view the available commands. Each of the commands supports the -h option which allows you to obtain more detailed usage instructions.

(gdb) dlhelp
[libdlmalloc] dlmalloc commands for gdb
[libdlmalloc] dlchunk    : show one or more chunks metadata and contents
[libdlmalloc] dlmstate   : print mstate structure information. caches address after first use
[libdlmalloc] dlcallback : register a callback or query/modify callback status
[libdlmalloc] dlhelp     : this help message
[libdlmalloc] NOTE: Pass -h to any of these commands for more extensive usage. Eg: dlchunk -h

Chunk analysis

dlchunk can provide you with a summary of a chunk, or more verbose information of every field. You can also use it to list information about multiple chunks, search chunks, etc. Usage for dlchunk can be seen below:

(gdb) dlchunk -h
[libdlmalloc] usage: dlchunk [-v] [-f] [-x] [-c <count>] <addr>
[libdlmalloc]  <addr>  a dlmalloc chunk header
[libdlmalloc]  -v      use verbose output (multiples for more verbosity)
[libdlmalloc]  -f      use <addr> explicitly, rather than be smart
[libdlmalloc]  -x      hexdump the chunk contents
[libdlmalloc]  -m      max bytes to dump with -x
[libdlmalloc]  -c      number of chunks to print
[libdlmalloc]  -s      search pattern when print chunks
[libdlmalloc]  --depth depth to search inside chunk
[libdlmalloc]  -d      debug and force printing stuff
[libdlmalloc] Flag legend: C=CINUSE, P=PINUSE

Basic output looks like this:

(gdb) dlchunk 0xacff59d0
0xacff59d0 M sz:0x000f8 fl:CP

As you can see you want to give it the address of the actual dlmalloc metadata itself. To get more verbose output you can use -v.

(gdb) dlchunk -v 0xacff59d0
struct malloc_chunk @ 0xacff59d0 {
prev_foot   = 0x8140d4d0
size        = 0xf8 (CINUSE|PINUSE)

You can also list multiple adjacent chunks by using the -c <count> switch.

(gdb) dlchunk -c 2 0xacff59d0
0xacff59d0 M sz:0x000f8 fl:CP
0xacff5ac8 M sz:0x00270 fl:CP
(gdb) dlchunk -v -c 2 0xacff59d0
struct malloc_chunk @ 0xacff59d0 {
prev_foot   = 0x8140d4d0
size        = 0xf8 (CINUSE|PINUSE)
--
struct malloc_chunk @ 0xacff5ac8 {
prev_foot   = 0x8140d4d0
size        = 0x270 (CINUSE|PINUSE)

You can dump the hex contents of a chunk with -x and control how many bytes you want to dump with -m.

(gdb) dlchunk -v -x -m 16 -c 2 0xacff59d0
struct malloc_chunk @ 0xacff59d0 {
prev_foot   = 0x8140d4d0
size        = 0xf8 (CINUSE|PINUSE)
0x10 bytes of chunk data:
0xacff59d8:	0xa11c0123	0x000000cc	0x00000000	0x00000000
--
struct malloc_chunk @ 0xacff5ac8 {
prev_foot   = 0x8140d4d0
size        = 0x270 (CINUSE|PINUSE)
0x10 bytes of chunk data:
0xacff5ad0:	0xa11c0123	0x00000244	0x00000000	0x00000000

You can also search inside the chunks. Let's search 2 chunks for the value 0x00000244, which we see above is only in the second chunk.

(gdb) dlchunk -s 0x00000244 -c 2 0xacff59d0
0xacff59d0 M sz:0x000f8 fl:CP [NO MATCH]
0xacff5ac8 M sz:0x00270 fl:CP [MATCH]

All matches inside the number of chunks searched will be shown. Let's search for 0xa11c01123 which we saw above is present in both chunks:

(gdb) dlchunk -s 0xa11c0123 -c 2 0xacff59d0
0xacff59d0 M sz:0x000f8 fl:CP [MATCH]
0xacff5ac8 M sz:0x00270 fl:CP [MATCH]

dlmstate

The dlmstate command can be used for analyzing the mstate structure used to manage a discrete dlmalloc heap (aka mspace if compiled with MSPACES). You can see the usage of the command with the -h switch.

(gdb) dlmstate -h
[libdlmalloc] usage: dlmstate [-v] [-f] [-x] [-c <count>] <addr>
[libdlmalloc]  <addr>  a mstate struct addr. Optional if mstate cached
[libdlmalloc]  -v      use verbose output (multiples for more verbosity)
[libdlmalloc]  -c      print bin counts
[libdlmalloc]  --depth how deep to count each bin (default 10)
[libdlmalloc]  NOTE: Last defined mstate will be cached for future use

If you know the address holding the mstate, which is usually the first chunk inside of the first malloc asegment, you can pass it to dlmstate: