gdb and rr Debugging

Start a new GDB debug session. Returns session_id required by all other tools.

For time-travel (record/replay) debugging use rr_record + start_replay_session instead.

binary: path to the executable (can also be set later via exec_command("file /path")) args: command-line arguments passed to the inferior when run is called cwd: working directory for GDB (defaults to current directory)

Stop and clean up a GDB session (kills the GDB process).

List all active sessions. Each entry includes id, kind ("gdb" or "rr-replay"), and alive status.

Record a full program execution with rr for time-travel debugging. Step 1 of the rr workflow.

Runs the program to completion and captures a deterministic trace. Returns trace_dir, which is passed to start_replay_session to begin debugging. Crashes and non-zero exit codes are normal and recorded as part of the trace — they do not indicate failure. The program's stdin is not available during recording.

binary: path to the executable to record args: command-line arguments for the binary cwd: working directory (defaults to current directory) timeout: maximum seconds to wait for the program to finish (default 5 min)

Start an rr replay session for time-travel debugging. Step 2 of the rr workflow.

Call rr_record first to produce a trace, then call this tool. The returned session_id works with all standard tools (breakpoint, run, continue_exec, step, backtrace, print, …). In addition, four reverse-execution tools let you run the program backwards: reverse-continue — run backwards to the previous breakpoint or watchpoint reverse-step — step backwards one source line or instruction (enters calls) reverse-next — step backwards one source line or instruction (skips calls) reverse-finish — run backwards to where the current function was called Breakpoints and watchpoints trigger in both directions.

trace_dir: trace directory from rr_record; omit to replay the most recent recording cwd: working directory for rr (defaults to current directory)

Execute any GDB command and return its output. Escape hatch for commands without a dedicated tool.

Useful examples: info breakpoints — list all breakpoints set var x = 5 — modify a variable thread apply all bt — backtrace every thread catch syscall / catch throw advance location — run to a specific location in the current frame source /path/to/script.gdb attach PID core-file /path/to/core

IMPORTANT — any command that resumes the inferior (run, continue, step, next, finish, until, advance, jump, signal, return, and the rr reverse-* variants) will BLOCK until the inferior stops again. Output includes the stop reason, e.g.: [Stopped: breakpoint-hit, in main, at foo.c:10] Use the interrupt tool to unblock a running session.

Execute a list of GDB commands sequentially and return each output.

Useful to avoid multiple round-trips, e.g.: ["file /bin/ls", "break main", "run -la"] stop_on_error: halt the batch on the first GdbError (default: continue).

Start or restart the inferior program. Blocks until it stops (breakpoint, signal, or exit).

In an rr replay session, run restarts from the very beginning of the recording. Pass args to override arguments set at session creation.

Continue forward execution from the current stop. Blocks until the program stops again.

rr replay sessions: use reverse-continue to run backwards instead.

Step forward into the next source line or machine instruction. Enters called functions.

Use next to step over calls instead. count: number of steps (default 1) instruction: if True, step one machine instruction instead of one source line rr replay sessions: use reverse-step to step backwards.

Step forward over the next source line or machine instruction. Does not enter called functions.

Use step to enter calls instead. count: number of steps (default 1) instruction: if True, step over one machine instruction instead of one source line rr replay sessions: use reverse-next to step backwards.

Run forward until the current function returns, then show the return value. Blocks until stopped.

rr replay sessions: use reverse-finish to run backwards to the call site instead.

Run forward until a specific location is reached. Blocks until stopped.

Skips over loops and blocks of code without setting a temporary breakpoint. location: file:line, function name, or *address — e.g. "foo.c:42", "cleanup", "*0x401234"

Interrupt a running inferior by sending SIGINT.

Use when run, continue_exec, or a reverse-* tool is blocking because the program has not stopped yet. The blocked call returns with the stop output.

[rr only] Run backwards until a breakpoint or watchpoint is hit. Blocks until stopped.

Requires an rr replay session created with start_replay_session. The reverse counterpart of continue_exec: resumes execution in reverse through previously executed code.

[rr only] Step backwards into the previous source line or machine instruction. Blocks until stopped.

Requires an rr replay session created with start_replay_session. The reverse counterpart of step: enters called functions when going backwards. Use reverse-next to step backwards without entering calls. count: number of steps (default 1) instruction: if True, step back one machine instruction instead of one source line

[rr only] Step backwards over the previous source line or machine instruction. Blocks until stopped.

Requires an rr replay session created with start_replay_session. The reverse counterpart of next: does not enter called functions when going backwards. Use reverse-step to step backwards into calls. count: number of steps (default 1) instruction: if True, step back one machine instruction instead of one source line

[rr only] Run backwards until just before the current function was called. Blocks until stopped.

Requires an rr replay session created with start_replay_session. The reverse counterpart of finish: where finish runs forward to the return, reverse-finish runs backward to the call site.

Set a breakpoint at a location. Triggers in both directions in rr replay sessions.

location: function name, file:line, or *address e.g. "main", "foo.c:42", "*0x401234", "MyClass::method" condition: optional expression that must be true to trigger — e.g. "x > 5" temporary: if True, the breakpoint auto-deletes after its first hit

Delete one breakpoint or all breakpoints (GDB 'delete').

number: breakpoint number to delete; omit to delete all breakpoints.

Set a watchpoint that stops execution when an expression changes (GDB 'watch').

Watchpoints detect when data changes, not where execution reaches. Useful for tracking memory corruption, unexpected variable mutations, etc.

expression: any GDB expression — variable, memory location, dereferenced pointer e.g. "x", "buf[4]", "*0x601020", "obj->field" mode: "write" — stop when expression is written (default, GDB 'watch') "read" — stop when expression is read (GDB 'rwatch') "access" — stop on any read or write (GDB 'awatch')

List all threads in the inferior with their current location (GDB 'info threads').

Switch to a specific thread (GDB 'thread N').

Use list_threads to see thread IDs. After switching, stack and local variable commands operate on the selected thread.

Show the call stack (GDB 'backtrace' / 'bt').

limit: maximum number of frames to show (omit for full stack).

Select a stack frame by number (GDB 'frame N').

Frame 0 is the innermost (current) frame; use backtrace to see frame numbers. After selecting a frame, inspection commands (print, info locals, list_source) operate in that frame's context.

Move up the call stack toward the caller (GDB 'up').

count: number of frames to move up (default 1).

Move down the call stack toward the innermost frame (GDB 'down').

count: number of frames to move down (default 1).

Return a full snapshot of the current debugging context.

Combines the most commonly needed post-stop information into one call:

• Current frame: function, file, and line number

• Function arguments

• Local variables

• Source listing around the current line

Call this immediately after any stop event (breakpoint hit, step, interrupt) to orient yourself before deciding on the next action.

Note: this resets GDB's internal source-listing position to the current PC, which cancels any forward scrolling done by previous list_source calls.

Show variables in the current stack frame (GDB 'info locals' / 'info args').

scope: "locals" — local variables only (default) "args" — function arguments only "all" — both locals and arguments

Print/evaluate a GDB expression (GDB 'print' / 'p').

expression: any GDB expression — variable, cast, function call, etc. fmt: optional output format: x=hex, d=decimal, o=octal, t=binary, f=float, s=string, c=char, a=address e.g. fmt="x" → "print /x expression"

Examine memory at an address (GDB 'x').

address: GDB expression for the target address: "&var", "0x601020", "$rsp" count: number of units to display fmt: x=hex, d=decimal, i=instruction, s=string, c=char, o=octal, t=binary unit: b=byte(1B), h=halfword(2B), w=word(4B), g=giant(8B)

Example: examine("$rsp", count=8, fmt="x", unit="g") → x/8xg $rsp (8 giant-word hex dump of the stack)

Show CPU register values (GDB 'info registers').

register: specific register name (e.g. "rax", "eip"), or omit for all general-purpose registers.

List source code (GDB 'list' / 'l').

location: function name, file:line, or omit to list around the current position. Call repeatedly with no location to scroll forward.

Disassemble code (GDB 'disassemble').

location: function name, *address, or "start,end" address range. Omit to disassemble the current function. with_source: if True, interleave C source lines with assembly (/s flag).