### 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$ 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); /* ... */ } ```