Modular Debugger

https://illumos.org/books/mdb/
Admin
MDB is a highly extensible, general-purpose debugging tool for the illumos operating system used to...
Tokens:48,784
Snippets:462
Trust Score:9.5
Update:7 months ago
Show doc for...
Tokens:
Raw
### Inspect memory buffer patterns

Source: https://illumos.org/books/mdb/kmem-1.html

Example of inspecting a memory dump to identify freed buffers marked with 0xdeadbeef and redzones marked with 0xfeedface.

```MDB
0x70a9add8:     deadbeef        deadbeef
0x70a9ade0:     deadbeef        deadbeef
0x70a9ade8:     deadbeef        deadbeef
0x70a9adf0:     feedface        feedface
0x70a9adf8:     70ae3260        8440c68e
0x70a9ae00:     5               4ef83
0x70a9ae08:     0               0
0x70a9ae10:     1               bbddcafe
0x70a9ae18:     feedface        139d
0x70a9ae20:     70ae3200        d1befaed
0x70a9ae28:     deadbeef        deadbeef
0x70a9ae30:     deadbeef        deadbeef
0x70a9ae38:     deadbeef        deadbeef
0x70a9ae40:     feedface        feedface
0x70a9ae48:     70ae31a0        8440c54e
```

--------------------------------

### Initiate Local Walk with Callback - mdb_pwalk

Source: https://illumos.org/books/mdb/api-5.html

The mdb_pwalk function initiates a local walk starting at a specified address, invoking a callback function for each step. If the address is NULL, it performs a global walk. It returns 0 on success and -1 on error, failing if the walker is unknown or returns a fatal error.

```c
int mdb_pwalk(const char *name, mdb_walk_cb_t func, void *data,
              uintptr_t addr);
```

--------------------------------

### Initiate Local Walk with Dcmd - mdb_pwalk_dcmd

Source: https://illumos.org/books/mdb/api-5.html

The mdb_pwalk_dcmd function initiates a local walk starting at a specified address, invoking a specified dcmd at each step with provided arguments. It returns 0 on success and -1 on error, failing if the walker or dcmd is unknown, or if the dcmd returns DCMD_ABORT or DCMD_USAGE.

```c
int mdb_pwalk_dcmd(const char *wname, const char *dcname, int argc,
                   const mdb_arg_t *argv, uintptr_t addr);
```

--------------------------------

### ::walk

Source: https://illumos.org/books/mdb/commands-1.html

Walks through the elements of a data structure using the specified walker. The available walkers can be listed using the ::walkers dcmd. Some walkers operate on a global data structure and do not require a starting address. For example, walk the list of proc structures in the kernel. Other walkers operate on a specific data structure whose address must be specified explicitly. For example, given a pointer to an address space, walk the list of segments. When used interactively, the ::walk dcmd will print the address of each element of the data structure in the default base. The dcmd can also be used to provide a list of addresses for a pipeline. The walker name can use the backquote “ ` ` ” scoping operator described in Dcmd and Walker Name Resolution. If the optional _variable-name_ is specified, the specified variable will be assigned the value returned at each step of the walk when MDB invokes the next stage of the pipeline.

```APIDOC
## [ _address_ ] `::walk` _walker-name_ [ _variable-name_ ]

### Description
Walk through the elements of a data structure using the specified walker. The available walkers can be listed using the `::walkers` dcmd. Some walkers operate on a global data structure and do not require a starting address. For example, walk the list of `proc` structures in the kernel. Other walkers operate on a specific data structure whose address must be specified explicitly. For example, given a pointer to an address space, walk the list of segments. When used interactively, the `::walk` dcmd will print the address of each element of the data structure in the default base. The dcmd can also be used to provide a list of addresses for a pipeline. The walker name can use the backquote “ ``` ” scoping operator described in Dcmd and Walker Name Resolution. If the optional `_variable-name_` is specified, the specified variable will be assigned the value returned at each step of the walk when MDB invokes the next stage of the pipeline.

### Method
N/A (MDB Command)

### Endpoint
N/A (MDB Command)

### Parameters
#### Path Parameters
- **_address_** (hexadecimal) - Optional - The starting address for the walk (if required by the walker).
- **_walker-name_** (string) - Required - The name of the walker to use.
- **_variable-name_** (string) - Optional - A variable to store the value at each step.

### Request Example
```
::walk proc
0x12345678 ::walk segment_list my_segment
```

### Response
#### Success Response (N/A)
- **Output**: Addresses of elements in the data structure, or values assigned to the specified variable.

#### Response Example
```
0x1000
0x2000
0x3000
```
```

--------------------------------

### Walk and Inspect Kernel Memory Caches

Source: https://illumos.org/books/mdb/kmem-1.html

Demonstrates how to iterate through all kmem cache pointers using the walker and how to apply the kmem_cache macro to a specific address to view detailed structure information.

```MDB
> ::walk kmem_cache
> 0x70039928$<kmem_cache
```

--------------------------------

### Convert adb watchpoint syntax to MDB

Source: https://illumos.org/books/mdb/adb-trans-1.html

Shows the migration of legacy adb watchpoint commands to the MDB repeat count syntax.

```text
# adb syntax
123:456w
123:456a
123:456p

# MDB syntax
123,456:w
123,456:a
123,456:p
```

--------------------------------

### Dot Variable Functions

Source: https://illumos.org/books/mdb/api-5.html

Functions to set or get the current value of the MDB 'dot' variable, which represents the current address.

```APIDOC
## mdb_set_dot and mdb_get_dot

### Description
Set or get the current value of dot (the "." variable). Module developers might want to reposition dot so that, for example, it refers to the address following the last address read by the dcmd.

### Method
N/A (Function calls within a dcmd)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```c
// Get the current value of dot
uintmax_t current_dot = mdb_get_dot();

// Set dot to a new address
uintmax_t new_address = 0x1000;
mdb_set_dot(new_address);
```

### Response
#### Success Response (200)
`mdb_get_dot` returns the current value of the dot variable as a `uintmax_t`. `mdb_set_dot` returns void.

#### Response Example
```
// For mdb_get_dot, returns a uintmax_t value like 0x1000
```
```

--------------------------------

### Walk kmem_cache buffers using MDB

Source: https://illumos.org/books/mdb/kmem-1.html

Demonstrates how to iterate over allocated and freed buffers within a specific kernel memory cache using the MDB walker syntax.

```MDB
> 0x70039928::walk kmem
704ba010
702ba008
704ba038
702ba030

> 0x70039928::walk freemem
70a9ae50
70a9ae28
704bb730
704bb2f8
```

--------------------------------

### Manage MDB 'dot' Variable

Source: https://illumos.org/books/mdb/api-5.html

Allows setting or retrieving the current value of the 'dot' variable, which typically represents an address. This is useful for module developers to reposition 'dot', for example, to the address following the last read address.

```c
void mdb_set_dot(uintmax_t dot);
ulluintmax_t mdb_get_dot(void);
```

--------------------------------

### Thread Information

Source: https://illumos.org/books/mdb/chp-exec.html

Commands to display LWPIDs (Lightweight Process IDs) for the target process.

```APIDOC
## Thread Information

### Description
Commands to display LWPIDs (Lightweight Process IDs) for the target process.

### Methods
- `$l` (Print Representative LWPID)
- `$L` (Print All LWPIDs)

### Endpoints
- `/$l`
- `/$L`

### Parameters
- None

### Request Example
```
$l
$L
```

### Response
#### Success Response (200)
- Prints the LWPID(s) to the console.

#### Response Example
```
12345
12345 12346 12347
```
```

--------------------------------

### ::in

Source: https://illumos.org/books/mdb/commands-1.html

Read and display bytes from an I/O port.

```APIDOC
## [DCMD] ::in

### Description
Read and display bytes from the I/O port specified by address. Only available in kmdb on x86.

### Method
DCMD

### Endpoint
[address [, len]] ::in [-L len]

### Parameters
#### Query Parameters
- **-L** (integer) - Optional - Number of bytes to read (1, 2, or 4).

### Request Example
0x3f8 ::in -L 1

### Response
#### Success Response (200)
- **value** (hex) - The data read from the I/O port.
```

--------------------------------

### Walk kmem_cache by name shortcut

Source: https://illumos.org/books/mdb/kmem-1.html

Uses the MDB shortcut command to walk specific kernel memory caches by their assigned name rather than their memory address.

```MDB
> ::walk kmem_alloc_24
704ba010
702ba008
704ba038
702ba030

> ::walk thread_cache
70b38080
70aac060
705c4020
70aac1e0
```

--------------------------------

### Compare operator precedence between adb and MDB

Source: https://illumos.org/books/mdb/adb-trans-1.html

Demonstrates how MDB follows ANSI C operator precedence compared to the left-to-right evaluation used in adb, resulting in different output for the same expression.

```shell
echo "4-1*3=X" | adb
echo "4-1*3=X" | mdb
```

--------------------------------

### ::version

Source: https://illumos.org/books/mdb/commands-1.html

Prints the debugger version number.

```APIDOC
## ::version

### Description
Print the debugger version number.

### Method
N/A (MDB Command)

### Endpoint
N/A (MDB Command)

### Parameters
None

### Request Example
```
::version
```

### Response
#### Success Response (N/A)
- **version** (string) - The version number of the MDB debugger.

#### Response Example
```json
{
  "version": "MDB 1.2.3"
}
```
```

--------------------------------

### Function: _mdb_init

Source: https://illumos.org/books/mdb/api-5.html

Initializes the debugger module, providing linkage information and API version verification.

```APIDOC
## FUNCTION _mdb_init

### Description
Each debugger module is required to provide an `_mdb_init` function for linkage and identification. It returns a pointer to an `mdb_modinfo_t` structure containing the API version and lists of dcmds and walkers.

### Method
N/A (C Function)

### Endpoint
`_mdb_init`

### Parameters
- **None**

### Request Example
```c
const mdb_modinfo_t *_mdb_init(void);
```

### Response
#### Success Response
- **mdb_modinfo_t** (struct) - A persistent structure containing `mi_dvers`, `mi_dcmds`, and `mi_walkers`.

#### Error Handling
- Returns `NULL` if the module determines it is inappropriate to load (e.g., missing symbols), causing the debugger to refuse loading.
```

--------------------------------

### ::vtop

Source: https://illumos.org/books/mdb/commands-1.html

Prints the physical address mapping for the specified virtual address, if possible. The ::vtop dcmd is only available when examining a kernel target, or when examining a user process inside a kernel crash dump (after a ::context dcmd has been issued). When examining a kernel target from the kernel context, the -a option can be used to specify the address (_as_) of an alternate address space structure that should be used for the virtual to physical translation. By default, the kernel's address space is used for translation. This option is available for active address spaces even when the dump content only contains kernel pages.

```APIDOC
## _address_ ::vtop [`-a` _as_]

### Description
Print the physical address mapping for the specified virtual address, if possible. The `::vtop` dcmd is only available when examining a kernel target, or when examining a user process inside a kernel crash dump (after a `::context` dcmd has been issued). When examining a kernel target from the kernel context, the `-a` option can be used to specify the address (`_as_`) of an alternate address space structure that should be used for the virtual to physical translation. By default, the kernel's address space is used for translation. This option is available for active address spaces even when the dump content only contains kernel pages.

### Method
N/A (MDB Command)

### Endpoint
N/A (MDB Command)

### Parameters
#### Path Parameters
- **_address_** (hexadecimal) - Required - The virtual address to translate.

#### Query Parameters
- **-a** (flag) - Optional - Use an alternate address space structure.
- **_as_** (address) - Optional - The address of the alternate address space structure.

### Request Example
```
0x1000 ::vtop
0x2000 ::vtop -a 0xdeadbeef
```

### Response
#### Success Response (N/A)
- **physical_address** (hexadecimal) - The corresponding physical address.
- **flags** (string) - Memory mapping flags.

#### Response Example
```json
{
  "physical_address": "0x12345678",
  "flags": "rwx"
}
```
```

--------------------------------

### ::walkers

Source: https://illumos.org/books/mdb/commands-1.html

Lists the available walkers and prints a brief description for each one.

```APIDOC
## ::walkers

### Description
List the available walkers and print a brief description for each one.

### Method
N/A (MDB Command)

### Endpoint
N/A (MDB Command)

### Parameters
None

### Request Example
```
::walkers
```

### Response
#### Success Response (N/A)
- **Output**: A list of available walkers and their descriptions.

#### Response Example
```
proc - Walk the list of process structures
segment_list - Walk the list of segments in an address space
```
```

--------------------------------

### ::findsym

Source: https://illumos.org/books/mdb/commands-1.html

Search instruction text for instructions that refer to specific symbols or addresses.

```APIDOC
## [DCMD] ::findsym

### Description
Search instruction text for instructions that refer to the specified symbols or addresses. SPARC only.

### Method
DCMD

### Endpoint
[address] ::findsym [-g] [address | symbol ...]

### Parameters
#### Query Parameters
- **-g** (flag) - Optional - Restrict search to globally visible functions.

### Request Example
::findsym my_function

### Response
#### Success Response (200)
- **results** (list) - List of instructions referencing the symbol.
```

--------------------------------

### Signal Handling

Source: https://illumos.org/books/mdb/chp-exec.html

Commands for ignoring signals, displaying ignored signals, and setting signal breakpoints.

```APIDOC
## Signal Handling

### Description
Commands for ignoring signals, displaying ignored signals, and setting signal breakpoints.

### Methods
- `:i` (Ignore Signal)
- `$i` (Display Ignored Signals)
- `::sigbp` (Set Signal Breakpoint)
- `:t` (Trace Signal Delivery)

### Endpoints
- `/_signal_/:i`
- `/$i`
- `/::sigbp`
- `/_signal_/:t`

### Parameters
#### `:i` Parameters
- `_signal_` - The signal to ignore.

#### `::sigbp` / `:t` Parameters
- `+/-dDestT` - Options for tracing signal delivery.
- `-c _cmd_` - Execute `_cmd_` string when signal is traced.
- `-n _count_` - Set hit limit for signal tracing.
- `_SIG_` - The signal name or number to trace.

### Request Example
```
SIGINT:i
$i
::sigbp SIGSEGV
:t SIGUSR1
```

### Response
#### Success Response (200)
- Output varies based on the command; `$i` displays a list of ignored signals.

#### Response Example
```
(No specific response example provided for general signal handling)
```
```

--------------------------------

### Process Control

Source: https://illumos.org/books/mdb/chp-exec.html

Commands for terminating the target process, stepping through instructions, and running a new process.

```APIDOC
## Process Control

### Description
Commands for terminating the target process, stepping through instructions, and running a new process.

### Methods
- `::kill` / `:k` (Terminate Process)
- `::next` / `:e` (Step Over Calls)
- `::run` / `:r` (Run Process)
- `::step` / `:s` / `:u` (Step Instruction)

### Endpoints
- `/::kill`
- `/::next [_SIG_]`
- `/::run [_args_ ...]`
- `/::step [branch | over | out] [_SIG_]`

### Parameters
#### `::kill` / `:k` Parameters
- None (forcibly terminates the target).

#### `::next` / `:e` Parameters
- `_SIG_` (Optional) - Signal to deliver immediately.

#### `::run` / `:r` Parameters
- `_args_ ...` - Arguments for the new target program.

#### `::step` Parameters
- `branch` | `over` | `out` (Optional) - Specifies the stepping mode.
- `_SIG_` (Optional) - Signal to deliver immediately.

### Request Example
```
::kill
::next
::run my_program arg1 arg2
::step over SIGTRAP
```

### Response
#### Success Response (200)
- Process termination, stepping, or execution initiation.

#### Response Example
```
(No specific response example provided for general process control)
```
```

--------------------------------

### ::status

Source: https://illumos.org/books/mdb/commands-1.html

Prints a summary of information related to the current target.

```APIDOC
## ::status

### Description
Print a summary of information related to the current target.

### Method
N/A (MDB Command)

### Endpoint
N/A (MDB Command)

### Parameters
None

### Request Example
```
::status
```

### Response
#### Success Response (N/A)
- **Output**: Summary of target information.

#### Response Example
(Output varies based on target state)
```

--------------------------------

### ::dump

Source: https://illumos.org/books/mdb/commands-1.html

Prints a hexadecimal and ASCII memory dump of the specified virtual memory region.

```APIDOC
## [DCMD] ::dump

### Description
Prints a hexadecimal and ASCII memory dump of the 16-byte aligned region of virtual memory containing the address specified by dot.

### Method
DCMD

### Endpoint
::dump [-efgpqrst] [-g group] [-w paragraphs] [address]

### Parameters
#### Query Parameters
- **-e** (flag) - Optional - Adjust for endianness (assumes 4-byte words).
- **-f** (flag) - Optional - Read from object file instead of virtual address space.
- **-g** (integer) - Optional - Display bytes in groups of size (power of two).
- **-p** (flag) - Optional - Interpret address as physical address.
- **-q** (flag) - Optional - Do not print ASCII decoding.
- **-r** (flag) - Optional - Number lines relative to start address.
- **-s** (flag) - Optional - Elide repeated lines.
- **-t** (flag) - Optional - Only display contents of specified addresses.
- **-u** (flag) - Optional - Unalign output.
- **-w** (integer) - Optional - Display paragraphs per line (max 16).

### Request Example
::dump -g 4 0x1000

### Response
#### Success Response (200)
- **output** (string) - Formatted hex/ASCII memory dump.
```

--------------------------------

### ::switch

Source: https://illumos.org/books/mdb/commands-1.html

When using kmdb only, switch to the CPU indicated by the specified _cpuid_ and use this CPU's current register state as the representative for debugging.

```APIDOC
## _cpuid_ ::switch

### Description
When using `kmdb` only, switch to the CPU indicated by the specified `_cpuid_` and use this CPU's current register state as the representative for debugging.

### Method
N/A (MDB Command)

### Endpoint
N/A (MDB Command)

### Parameters
#### Path Parameters
- **_cpuid_** (integer) - Required - The ID of the CPU to switch to.

### Request Example
```
1 ::switch
```

### Response
#### Success Response (N/A)
- **Output**: Register state updated for the specified CPU.

#### Response Example
(No direct output, state change)
```

--------------------------------

### ::whence

Source: https://illumos.org/books/mdb/commands-1.html

Resolves a name to an address.

```APIDOC
## ::whence [`-v`] _name_ ...

### Description
Resolve a name to an address. The `-v` option provides verbose output.

### Method
N/A (MDB Command)

### Endpoint
N/A (MDB Command)

### Parameters
#### Query Parameters
- **-v** (flag) - Optional - Enable verbose output.

#### Path Parameters
- **_name_** (string) - Required - The name to resolve.

### Request Example
```
::whence my_function
::whence -v my_variable
```

### Response
#### Success Response (N/A)
- **address** (hexadecimal) - The address of the resolved name.
- **name** (string) - The name that was resolved.

#### Response Example
```json
{
  "address": "0x12345",
  "name": "my_function"
}
```
```

--------------------------------

### Initiate Global Walk with Callback - mdb_walk

Source: https://illumos.org/books/mdb/api-5.html

The mdb_walk function initiates a global walk, invoking a callback function for each step. It returns 0 on success and -1 on error. The function fails if the specified walker name is not known to the debugger or if the walker returns a fatal error.

```c
int mdb_walk(const char *name, mdb_walk_cb_t func, void *data);
```

--------------------------------

### Format string construction with mdb_snprintf

Source: https://illumos.org/books/mdb/api-5.html

Constructs a formatted string into a buffer using specified format specifiers. It returns the number of bytes required for the complete string, allowing for dynamic buffer sizing when called with a NULL buffer.

```C
size_t mdb_snprintf(char *buf, size_t len, const char *format, ...);
```

--------------------------------

### ::tls

Source: https://illumos.org/books/mdb/commands-1.html

Prints the address of the storage for the specified thread-local storage (TLS) symbol in the context of the specified thread.

```APIDOC
## _thread_ ::tls _symbol_

### Description
Print the address of the storage for the specified thread-local storage (TLS) symbol in the context of the specified thread. The thread expression should be one of the thread identifiers described under Thread Support. The symbol name may use any of the scoping operators described under Symbol Name Resolution.

### Method
N/A (MDB Command)

### Endpoint
N/A (MDB Command)

### Parameters
#### Path Parameters
- **_thread_** (thread_identifier) - Required - The thread context for the lookup.
- **_symbol_** (string) - Required - The name of the TLS symbol.

### Request Example
```
(current thread) ::tls my_tls_variable
```

### Response
#### Success Response (N/A)
- **address** (hexadecimal) - The memory address of the TLS symbol for the given thread.

#### Response Example
```json
{
  "address": "0x7ffc12345678"
}
```
```

--------------------------------

### Execute global walk with mdb_walk_dcmd

Source: https://illumos.org/books/mdb/api-5.html

Initiates a global walk using a specified walker and invokes a dcmd at each step. Returns 0 on success or -1 on failure, handling potential naming conflicts via backquote scoping.

```C
int mdb_walk_dcmd(const char *wname, const char *dcname, int argc,
                  const mdb_arg_t *argv);
```

--------------------------------

### Print Address Symbolically (%a, %#a)

Source: https://illumos.org/books/mdb/api-5.html

The '%a' specifier prints an address in symbolic form. If address-to-symbol conversion is enabled, it shows the symbol name and offset. The '%#a' variant adds a ':' suffix. If conversion fails, nothing is printed for '%a' and '?' for '%#A'.

```mdb
%a
%#a
```

--------------------------------

### Dump Data with mdb_dumpptr and mdb_dump64

Source: https://illumos.org/books/mdb/api-5.html

These functions generate formatted hexadecimal and ASCII data dumps. They accept an address, byte count, flags, a callback function for reading data, and user data. mdb_dumpptr uses uintptr_t for addresses, while mdb_dump64 uses uint64_t. Flags control output formatting like relative line numbering, alignment, pedantic display, ASCII representation, headers, trimming, squishing repeated lines, updating 'dot', endianness adjustment, and line width/group size.

```c
int mdb_dumpptr(uintptr_t addr, size_t nbytes, uint_t flags,
                mdb_dumpptr_cb_t func, void *data);
int mdb_dump64(uint64_t addr, uint64_t nbytes, uint_t flags,
mdb_dump64_cb_t func, void *data);
```

--------------------------------

### Parse command-line options with mdb_getopts

Source: https://illumos.org/books/mdb/api-5.html

The mdb_getopts function parses and processes options from an argument array. It supports various types including bit flags, strings, and integers, automatically handling error reporting and memory cleanup.

```C
int mdb_getopts(int argc, const mdb_arg_t *argv, ...);

int
dcmd(uintptr_t addr, uint_t flags, int argc, const mdb_arg_t *argv)
{
        uint_t opt_v = FALSE;
        const char *opt_s = NULL;

        if (mdb_getopts(argc, argv,
            'v', MDB_OPT_SETBITS, TRUE, &opt_v,
            's', MDB_OPT_STR, &opt_s, NULL) != argc)
                return (DCMD_USAGE);

        /* ... */
}
```
Tokens:
Raw