| name | linux-gdb-debugger |
| description | Use for Linux C/C++ GDB crash, core dump, and hang debugging. |
Linux GDB Debugger
Use GDB evidence before editing Linux user-space C/C++ crash or hang bugs.
Scope
Use for local Linux executables, native tests, Linux core files, and user-provided Linux PIDs. This includes SIGSEGV, SIGABRT, bad pointers, memory corruption, deadlocks, infinite loops, JNI/native-extension crashes, and logic bugs that need bounded stepping.
Do not use for Windows, macOS/LLDB, MCU/OpenOCD/pyOCD/J-Link, RTOS targets, Linux kernel/module debugging, or remote gdbserver workflows.
Workflow
- Identify the exact executable and reproduction command.
- Build with debug symbols when possible.
- Run the matching script from this skill's
scripts/ directory.
- Read the generated
.debug/ GDB log.
- Identify the failure, crashing frame, first application frame, arguments, locals, thread state, and suspicious value or pointer.
- Make the smallest code change consistent with the evidence.
- Rebuild and rerun the original command.
- Rerun GDB or the test to verify the failure is gone.
If symbols are missing or values show <optimized out>, say so and prefer Debug or RelWithDebInfo builds.
Build
For direct C/C++ builds, prefer:
CFLAGS="-g -O0" CXXFLAGS="-g -O0"
For CMake:
cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug
cmake --build build
If optimization is required to reproduce:
cmake -S . -B build -DCMAKE_BUILD_TYPE=RelWithDebInfo
cmake --build build
Scripts
- Crash or native test crash:
scripts/gdb-crash.sh <executable> [args...]
- Stdin-driven crash:
STDIN=input.txt scripts/gdb-crash.sh <executable> [args...]
- Core file:
scripts/gdb-core.sh <executable> <core-file>
- Hang/deadlock:
scripts/gdb-hang.sh <executable> [args...]
- Existing process hang:
PID=<pid> scripts/gdb-hang.sh [matching-executable]
- Bounded stepping:
BREAK=main STEPS=30 MODE=next scripts/gdb-step.sh <executable> [args...]
For noisy hang logs, use BT_COMMAND="thread apply all bt 30" or FRAME_ARGS=scalars.
References
Load only what is needed:
references/diagnosis-playbook.md for root-cause workflow.
references/gdb-command-patterns.md for breakpoints, watchpoints, and stepping.
references/common-native-bugs.md for failure signatures.
Safety
- Do not use
sudo or destructive commands.
- Do not attach to arbitrary PIDs unless the user provided the PID or this session launched it.
- Keep GDB logs and command files under
.debug/.
- Bound stepping with
STEPS; prefer breakpoints/watchpoints over long step runs.
- Do not continue indefinitely on hangs.
- Do not delete core files or logs unless asked.