Zxdb is an asynchronous debugger that allows the user to interact with the
debugger while processes or threads are running or stopped.

Zxdb uses a noun, verb, and command model for typed commands. This document
highlights the main functionality of the zxdb debugger.

## Debugger model

When working with zxdb, you can perform most actions by combining a `noun` and
a `verb`.

- [Noun](https://fuchsia.dev/fuchsia-src/development/debugger/commands.md.txt#noun)
- [Verbs](https://fuchsia.dev/fuchsia-src/development/debugger/commands.md.txt#verbs)

## Noun

The possible nouns (and their abbreviations) are:

- `breakpoint` (`bp`)

  Select or list breakpoints.
- `filter`

  Select or list process filters.
- `frame` (`f`)

  Select or list stack frames.
- `global` (`gl`)

  Global override for commands.
- `process` (`pr`)

  Select or list process contexts.
- `sym-server`

  Select or list symbol servers.
- `thread` (`t`)

  Select or list threads.
- `tracepoint` (`tp`)

  Select or list non-stopping tracepoints.

### Listing nouns

If you type a noun by itself, it lists the available objects of that type. For
example:

### breakpoint

List all of the breakpoints in the session:

    breakpoint
    # scope  stop enabled type     Condition                       #addrs hit-count location
    1 global all  true    software command_line.has_argv0 == false      1         0 ../../src/cobalt/bin/app/cobalt_main.cc:352

### frame

List stack frames in the current thread:

> [!NOTE]
> **Note:** You must `pause` the thread before you can list the stack frames.

    frame
    ▶ 0 fxl::CommandLineFromIterators<const char *const *>() • command_line.h:203
      1 fxl::CommandLineFromArgcArgv() • command_line.h:224
      2 main() • main.cc:174

### process

List attached processes:

    process
      # State       Koid Name
    ▶ 1 Not running 3471 debug_agent_unit_tests.cm

### thread

List threads in the current process:

    thread
      # State   Koid Name
    ▶ 1 Blocked 1348 initial-thread
      2 Blocked 1356 some-other-thread

### tracepoint

List all tracepoints in the session:

    tracepoint
      # State   Hits Location   Expressions
    ▶ 1 enabled 0/10 MyFunction x, y

### Selecting active nouns

You can select a noun and its respective index to make it the active noun for
subsequent commands. When you set a new active noun, it returns information
about the new active noun. For example:

### thread

Select thread 3 to be the active noun for future commands:

    thread 3
    Thread 3 Blocked koid=9940 worker-thread

### breakpoint

Select breakpoint 2 to be the active noun:

    breakpoint 2
    Breakpoint 2 (Software) on Global, Enabled, stop=All, @ MyFunction

### tracepoint

Select tracepoint 1 to be the active noun:

    tracepoint 1
    Tracepoint 1 state=enabled hits=0/10 location=MyFunction condition=x > 0 capture=[locals] exprs=[x, y]

## Verbs

In zxdb, verbs are used in conjunction with nouns, which specify a zxdb object,
to perform debugging actions. For a full list of zxdb verbs, see
[`verbs.h`](https://cs.opensource.google/fuchsia/fuchsia/+/main:src/developer/debug/zxdb/console/verbs.h;l=36).

By default, a verb such as `run`, `next`, `print`, etc... applies to the
current active nouns (for more information on active nouns, see
[Selecting active nouns](https://fuchsia.dev/fuchsia-src/development/debugger/commands.md.txt#selecting-active-nouns)).

### Data display verbs

- Memory display verbs are covered in [memory](https://fuchsia.dev/fuchsia-src/development/debugger/memory.md.txt).
- Register display verbs are covered in [assembly](https://fuchsia.dev/fuchsia-src/development/debugger/assembly.md.txt).

## Help

The zxdb debugger has a built-in help system:

    help

You can also get help on a specific command. For example, to see the help of the
`step` command:

    help step

## Attributes and settings

zxdb debugger objects have settings associated with them. You can specify some
of these settings to personalize zxdb.

### Retrieve

You can use the `get` verb to list the settings for a given object.

For example, you can get the attributes of the active `process`:

> [!NOTE]
> **Note:** The `get` command can be used on all zxdb nouns. When using `get`, you can also specify a specific process such as `process 1 get`.

    process get
      debug-stepping false
      display        <empty>
      show-stdout    true
      source-map     • /b/s/w/ir/x/w/fuchsia-third_party-rust=/usr/local/home/user/fuchsia/out/default/host_x64/../../../prebuilt/third_party/rust/linux-x64/lib/rustlib/src/rust
      vector-format  double

You can also use the `get` verb with a specific attribute to list the attribute
and help associated with it.

For example, to get the help of the `debug-stepping` attribute:

    process get debug-stepping
    debug-stepping (bool)

      Enable very verbose debug logging for thread stepping.

      This is used by developers working on the debugger's internal thread
      controllers.

    debug-stepping = false

### Set

You can use the `set` verb to set the settings or attributes of a given object.

For example, you can set the `show-stdout` attribute of the active `process` to
`true`:

    process set show-stdout true
    Set process 1 show-stdout = true

Some settings are hierarchical. A thread inherits settings from its process,
which in turn inherits settings from the global scope. If you use the `get` verb
without context or parameters, it lists the global settings and the specific
settings for the current process and thread.

You can set a global setting to apply to all threads and processes without
specific overrides, or override a specific context.

For example, you can set the `show-stdout` global setting to `false`:

    set show-stdout false       # Applies to all processes with no override.
    Set global show-stdout = false

Some settings are stored as lists. For example, you can use any of these
examples to set your `symbol-paths`:

> [!NOTE]
> **Note:** Elements in a list are space-separated. You can use double quotes to specify a path that contains a space.

- Use `=` to specify a new value:

      set symbol-paths = /tmp/symbols /fuchsia-settings/symbols "/fuchsia settings/symbols"
      Set global symbol-paths =
        • /tmp/symbols
        • /fuchsia-settings/symbols
        • "/fuchsia settings/symbols"

- Use `+=` to append to the existing values:

      set symbol-paths += /tmp/symbols2
      Set global symbol-paths =
        • /tmp/symbols
        • /fuchsia-settings/symbols
        • "/fuchsia settings/symbols"
        • /tmp/symbols2

### Languages

> [!NOTE]
> **Note:** C++ and Rust are supported.

zxdb evaluates expressions based on the programming language from the current
stack frame. If the current frame's language is different, zxdb defaults to C++.

By default zxdb uses a language of `auto`. You can overwrite the default
language with the `set` verb.

> [!NOTE]
> **Note:** You should rarely need to set the language.

For example, to set the default language to `rust`:

    set language rust
    Set global language = rust

[](https://issues.fuchsia.dev/issues/new?component=1439230&template=1881640&description=Issue+on:+https://fuchsia.dev/docs/development/debugger/commands.md "Report a bug or suggest improvements on this page") [](https://cs.opensource.google/fuchsia/fuchsia/+/main:docs/development/debugger/commands.md "View the source code of this page") [](https://ci.android.com/edit?repo=fuchsia/fuchsia/main&file=docs/development/debugger/commands.md&cloneRepo=fuchsia/fuchsia:refs/heads/main&fullPath=fuchsia/docs/development/debugger/commands.md "Edit the source code of this page")