agentleFS
hellyguohellyguo/self-ai-spec/skills/gdb-heap-analysis/SKILL.md

gdb-heap-analysis

Skill8 starsChanged 17 days agoApache-2.0View on GitHub

使用 GDB 分析 core dump 中的 glibc ptmalloc 堆与 arena,定位内存泄漏、内存占用异常与堆损坏。触发场景:内存泄漏分析、core dump 排查、arena 与 malloc_state 分析、glibc 堆调试、malloc 内部结构问题。

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 3 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Read references/glibc-offsets.md for known offsets by version.

    line 36
  2. Distinctive:

    Look for anonymous mappings not covered by subheaps.

    line 104
  3. Distinctive:

    heap_info undefined: Use fixed offset (sizeof=32B, ar_ptr=0, prev=8, size=16)

    line 137
  4. Very specific:

    Memory access errors: Use Python helper with gdb.MemoryError exception handling

    line 138

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

GDB 堆内存分析(glibc ptmalloc)

Analyze glibc ptmalloc heap structures in core dumps. Human judgment required at each decision point.

Workflow

Load core → Confirm symbols → Walk arenas → Analyze malloc_state → Check distribution → Locate allocations

Step 1: Confirm Debug Symbols

ptype struct malloc_state
ptype struct malloc_chunk
  • Struct definition output → Has symbols, use struct access
  • "No symbol table" → No symbols, need manual offsets

No Symbols

ldd --version
info sharedlibrary libc

Read references/glibc-offsets.md for known offsets by version.

Step 2: Walk All Arenas

With Symbols

p &main_arena
p main_arena.system_mem
set $a = main_arena.next
while $a != &main_arena && $a != 0
  printf "Arena @ %p, sys_mem=%lu MB\n", $a, $a->system_mem / 1024 / 1024
  set $a = $a->next
end

Without Symbols

set $arena = 0xfffd8c000020
x/gx $arena+0x888    # system_mem (glibc 2.28)
x/gx $arena+0x870    # next

Judgment: Arena size thresholds — typical <100MB, suspicious >500MB, abnormal >1GB. Record largest arena address.

Step 3: Analyze malloc_state

p *(struct malloc_state *)$arena_addr

Key fields: top, system_mem, bins[], fastbinsY

Top Chunk Location

set $top = ((struct malloc_state *)$arena)->top
  • $top near $arena_addr (within 64MB) → Subheap mode
  • $top in different address range → Direct mmap mode

Step 4: Check Memory Distribution

Subheap Chain

set $heap = $arena_addr - 32
while $heap != 0
  set $ar = *(void**)$heap
  if $ar != $arena_addr
    break
  end
  set $size = *(size_t*)($heap+16)
  printf "Subheap @ %p, size=%lu MB\n", $heap, $size/1024/1024
  set $heap = *(void**)($heap+8)
end

Judgment: Sum subheap sizes, compare with system_mem. Gap >1GB → large direct mmap allocations.

Mmap Mode

info proc mappings

Look for anonymous mappings not covered by subheaps.

Step 5: Locate Specific Allocations

Chunk Header

set $chunk = 0xfffcab6d86b0
x/gx $chunk-8   # prev_size + size with flags

Size field flags (lowest 3 bits): PREV_INUSE(bit 0), IS_MMAPPED(bit 1), NON_MAIN_ARENA(bit 2)

Bins

p ((struct malloc_state *)$arena)->bins[0]@10
p ((struct malloc_state *)$arena)->fastbinsY

Judgment Summary

StepCheckDecision
1Symbols?Struct access vs manual offset
2Arena size>1GB = abnormal
3Top locationFar from arena = mmap mode
4Subheap vs sys_mem>1GB gap = direct mmap
5Chunk flagsIS_MMAPPED = mmap alloc

Common Issues

  • main_arena not accessible: info variables main_arena; trace backwards from any arena's next chain
  • heap_info undefined: Use fixed offset (sizeof=32B, ar_ptr=0, prev=8, size=16)
  • Memory access errors: Use Python helper with gdb.MemoryError exception handling

Output Templates

  • templates/arena-walk-output.md - Arena walk and chunk analysis output format
  • templates/diagnostic-decision.md - Pattern match and diagnosis result format

Resources

  • references/glibc-offsets.md - Known offsets by glibc version
  • references/heap-structures.md - Detailed struct layouts
  • references/diagnostic-patterns.md - Real case studies

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.