Public API reference

This page documents the public Python API exported by the sdb package. Everything listed here is part of sdb.__all__ and is considered stable.

Exit codes

These constants represent the exit codes used by sdb -e and returned by REPL.eval_cmd(). Agents and scripts can use them to detect failures without parsing output.

sdb.EXIT_SUCCESS

Value 0. The command completed successfully.

sdb.EXIT_ERROR

Value 1. A command-level error occurred (unknown command, invalid input, runtime fault, etc.).

sdb.EXIT_BAD_ARGS

Value 2. The arguments passed to a command were invalid (e.g. head -n notanumber). Also used by argparse when the CLI flags themselves are wrong.

Programmatic API

These functions are the recommended way for scripts, notebooks, and AI agents to use sdb without an interactive REPL.

sdb.open_dump(object_file, core_file, symbol_search=None, command_paths=None, quiet=False)

Open a crash/core dump for programmatic analysis in one call.

This is a convenience wrapper that creates a drgn.Program, loads the core dump and debug info, and initialises the sdb runtime. After calling this function you can immediately use sdb.run() and sdb.invoke().

Parameters:

  • object_file – Path to the namelist (vmlinux or userland binary).

  • core_file – Path to the crash dump or core dump file.

  • symbol_search – Optional list of additional paths to search for debug info (.ko, .debug, shared objects).

  • command_paths – Optional list of filesystem paths from which to load additional sdb commands.

  • quiet – If True, suppress warnings about missing debug info.

Returns:

The initialised drgn.Program.

Raises:

FileNotFoundError – If object_file or core_file does not exist.

Example:

import sdb

prog = sdb.open_dump("vmlinux", "vmcore")
pools = sdb.run("spa | member spa_name")
for p in pools:
    print(p.string_().decode())
sdb.connect(prog, command_paths=None)

Set up the sdb runtime for programmatic use without starting a REPL.

This is the recommended entry point for scripts, notebooks, and AI agents that want to call sdb.run() or sdb.invoke() without an interactive session.

Parameters:

  • prog – A fully initialised drgn.Program.

  • command_paths – Optional list of filesystem paths (files or directories) from which to load additional sdb commands.

Returns:

The same prog that was passed in (for chaining convenience).

Example:

import drgn, sdb

prog = drgn.Program()
prog.set_core_dump("vmcore")
prog.load_debug_info(["vmlinux"])

sdb.connect(prog)
for obj in sdb.run("spa | member spa_name"):
    print(obj.string_().decode())
sdb.run(cmd, input_objs=None)

Execute an sdb pipeline and return the results as a Python list.

Unlike sdb.invoke() (which returns a lazy generator), run() eagerly evaluates the pipeline and returns a concrete list of drgn.Object values. The sdb runtime must be initialised first via sdb.connect() or sdb.start().

Parameters:

  • cmd – An sdb pipeline string, e.g. "spa | member spa_name".

  • input_objs – Optional iterable of drgn.Object to feed as initial input. Defaults to [].

Returns:

A list of drgn.Object results.

Raises:

Example:

import sdb

# After sdb.connect(prog):
tasks = sdb.run("threads")
print(f"Found {len(tasks)} threads")

names = sdb.run("threads | member comm")
for name in names:
    print(name.string_().decode())

Entry point (REPL)

sdb.start(prog, command_paths=None, prompt='sdb> ', pre_cmd_hook=None, eval_cmd=None, history_file='~/.sdb_history')

High-level entry point for using sdb as a library.

Accepts a pre-configured drgn.Program and starts the sdb REPL (or evaluates a single command if eval_cmd is given).

Parameters:

  • prog – A fully initialised drgn.Program.

  • command_paths – Optional list of filesystem paths (files or directories) from which to load additional sdb commands.

  • prompt – REPL prompt string, or an object whose __str__ is called each time the prompt is displayed.

  • pre_cmd_hook – Optional callable (no arguments) invoked before every command evaluation.

  • eval_cmd – If provided, evaluate this single command string and return instead of starting the interactive REPL.

  • history_file – Path for readline history persistence.

Example:

import drgn, sdb

prog = drgn.Program()
prog.set_kernel()
prog.load_default_debug_info()

sdb.start(prog, prompt="mydb> ")

Pipeline execution

sdb.invoke(first_input, line)

Parse and execute an sdb pipeline string.

Parameters:

  • first_input – An iterable of drgn.Object to feed as initial input (pass [] to start from scratch).

  • line – The pipeline string, e.g. "stacks -t D | count".

Returns:

A generator yielding drgn.Object results.

Example:

for obj in sdb.invoke([], "spa | member spa_name"):
    print(obj.string_().decode())
sdb.execute_pipeline(first_input, pipeline)

Execute a pre-built list of Command objects.

Parameters:

  • first_input – Iterable of drgn.Object.

  • pipeline – A list of instantiated Command objects.

Returns:

Generator of drgn.Object.

sdb.get_first_type(objs)

Peek at the type of the first object in an iterable without consuming it.

Parameters:

objs – An iterable of drgn.Object.

Returns:

A tuple (drgn.Type, iterable) where the iterable contains the same objects (including the first one).

Example:

first_type, objs = sdb.get_first_type(objs)

External command loading

sdb.load_external_commands(path)

Import sdb commands from a .py file or a directory of them.

Parameters:

path – Filesystem path. If a directory, all .py files are imported recursively (files starting with __ are skipped).

Returns:

A list of command name strings that were newly discovered.

Raises:

After loading, call sdb.register_commands() to make the new commands available in the REPL.

Command registration

sdb.register_commands()

Register all known command classes that are appropriate for the current runtime (kernel vs. userland). This is called automatically by sdb.start(); call it manually only when setting up sdb without start().

sdb.get_registered_commands()

Return a dict mapping command name strings to Command subclasses.

Target helpers

These functions access the drgn.Program and its state. They are available after sdb.start() has been called or after manually calling sdb.target.set_prog().

sdb.get_prog()

Return the current drgn.Program.

sdb.get_object(name)

Look up a global variable or symbol by name and return it as a drgn.Object.

sdb.create_object(type, value)

Create a drgn.Object of the given type with the given value.

Parameters:

  • type – A type string (e.g. "void *", "int").

  • value – An integer value.

sdb.get_type(name)

Look up a C type by name and return a drgn.Type.

sdb.get_symbol(obj)

Return the drgn.Symbol for an object or address.

sdb.get_pointer_type(type)

Given a drgn.Type, return the corresponding pointer type.

sdb.is_null(obj)

Return True if obj is a null pointer.

sdb.get_target_flags()

Return the drgn.ProgramFlags for the current program.

Thread and frame state

sdb.set_thread(thread)

Set the current thread context.

sdb.get_thread()

Return the current thread object.

sdb.set_frame(frame)

Set the current stack frame index (-1 for the topmost frame).

sdb.get_frame()

Return the current stack frame index.

Type utilities

sdb.type_canonical_name(type)

Return the canonical name for a drgn.Type (resolves typedefs).

sdb.type_canonicalize(type)

Resolve all typedefs and return the underlying drgn.Type.

sdb.type_canonicalize_name(name)

Like type_canonical_name but accepts a type name string.

sdb.type_canonicalize_size(type)

Return the size of a type after resolving typedefs.

sdb.type_equals(a, b)

Return True if two drgn.Type objects refer to the same type (after canonicalization).

Command base classes

class sdb.Command

Base class for all sdb commands. See Developer notes for how to subclass it.

class sdb.SingleInputCommand

Processes each input object independently; a FaultError on one object does not abort the pipeline.

class sdb.Walker

Iterates over a container data structure. Implement walk(self, obj).

class sdb.PrettyPrinter

Human-readable formatter. Implement pretty_print(self, objs).

class sdb.Locator

Finds objects of a given type. Implement no_input(self) and optionally @InputHandler-decorated methods.

class sdb.InputHandler(typename)

Decorator for methods on Locator subclasses. Registers the method as the handler for input objects of the given C type.

class sdb.Address

Built-in command that resolves symbols and hex addresses.

class sdb.Cast

Built-in command that casts objects to a specified type.

class sdb.Walk

Built-in dispatch command that selects the appropriate Walker.

Runtime markers

class sdb.All

Load the command for all target types.

class sdb.Kernel

Load the command only for kernel targets.

class sdb.Userland

Load the command only for userland targets.

class sdb.Module(name)

Load for a specific kernel module (currently equivalent to Kernel).

class sdb.Library(name)

Load for a specific shared library (currently equivalent to Userland).

Error hierarchy

All sdb-specific exceptions inherit from sdb.Error.

class sdb.Error

Base exception.

class sdb.CommandError

A command encountered a runtime error (e.g. type mismatch, invalid memory).

class sdb.CommandNotFoundError

The user typed a command name that is not registered.

class sdb.CommandInvalidInputError

A command received input of an unexpected type.

class sdb.SymbolNotFoundError

A symbol name could not be resolved.

class sdb.CommandArgumentsError

The arguments passed to a command were invalid (raised by argparse).

class sdb.CommandEvalSyntaxError

A syntax error in a filter expression.

class sdb.ParserError

A parse error in the pipeline syntax.