Chapter 4 Built-in Commands

MDB provides a set of built-in dcmds that are always defined. Some of these dcmds are applicable only to certain targets: if a dcmd is not applicable to the current target, it fails and prints a message indicating "command is not supported by current target".

In many cases, MDB provides a mnemonic equivalent (::identifier) for the legacy adb(1) dcmd names. For example, ::quit is provided as the equivalent of $q. Programmers who are experienced with adb(1) or who appreciate brevity or arcana might prefer the $ or : forms of the built-ins. Programmers who are new to mdb might prefer the more verbose :: form. The built-ins are shown in alphabetical order. If a $ or : form has a ::identifier equivalent, it is shown under the ::identifier form.

Built-in dcmds

> variable-name
> /modifier/ variable-name

Assign the value of dot to the specified named variable. Some variables are read-only and cannot be modified. If the > is followed by a modifier character surrounded by //, then the value is modified as part of the assignment. The modifier characters are:

c

Unsigned char quantity (1-byte)

s

Unsigned short quantity (2-byte)

i

Unsigned int quantity (4-byte)

l

Unsigned long quantity (4-byte in 32-bit, 8-byte in 64-bit)

Notice that these operators do not perform a cast; they instead fetch the specified number of low-order bytes (on little-endian architectures) or high-order bytes (big-endian architectures). These modifiers are provided for backward compatibility; the MDB */modifier/ and %/modifier/ syntax should be used instead.

$< macro-name

Read and execute commands from the specified macro file. The file name can be given as an absolute or relative path. If the file name is a simple name (that is, if it does not contain a '/'), MDB searches for it in the macro file include path. If another macro file is currently being processed, this file is closed and replaced with the new file.

$<< macro-name

Read and execute commands from the specified macro file (as with $<), but do not close the current open macro file.

$?

Print the process-ID and current signal of the target if it is a user process or core file, then print the general register set of the representative thread.

[ address ] $C [ count ]

Print a C stack backtrace, including stack frame pointer information. If the dcmd is preceded by an explicit address, a backtrace beginning at this virtual memory address is displayed. Otherwise, the stack of the representative thread is displayed. If an optional count value is given as an argument, no more than count arguments are displayed for each stack frame in the output.

---

64-bit SPARC only -

The biased frame pointer value (that is, the virtual address minus 0x7ff) should be used as the address when requesting a stack trace.

---

[ base ] $d

Get or set the default output radix. If the dcmd is preceded by an explicit expression, the default output radix is set to the given base; otherwise, the current radix is printed in base 10 (decimal). The default radix is base 16 (hexadecimal).

$e

Print a list of all known external (global) symbols of type object or function, the value of the symbol, and the first 4 (32-bit mdb) or 8 (64-bit mdb) bytes stored at this location in the target's virtual address space. The ::nm dcmd provides more flexible options for displaying symbol tables.

$P prompt-string

Set the prompt to the specified prompt-string. The default prompt is ' > '. The prompt can also be set using ::set -P or the -P command-line option.

distance $s

Get or set the symbol matching distance for address-to-symbol-name conversions. The symbol matching distance modes are discussed along with the -s command-line option in Appendix A, Options. The symbol matching distance can also be modified using the ::set -s option. If no distance is specified, the current setting is displayed.

$v

Print a list of the named variables that have non-zero values. The ::vars dcmd provides other options for listing variables.

width $w

Set the output page width to the specified value. Typically, this command is not necessary, as mdb queries the terminal for its width and handles resize events.

$W

Reopen the target for writing, as if mdb had been executed with the -w option on the command line. Write mode can also be enabled with the ::set -w option.

[ pid ] ::attach [ core | pid ]
[ pid ] :A [ core | pid ]

If the user process target is active, attach to and debug the specified process-ID or core file. The core file path name should be specified as a string argument. The process-ID can be specified as the string argument, or as the value of the expression preceding the dcmd. Recall that the default base is hexadecimal, so decimal PIDs obtained using pgrep(1) or ps(1) should be preceded with "0t" when specified as expressions.

::cat filename ...

Concatenate and display files. Each file name can be specified as a relative or absolute path name. The file contents will print to standard output, but will not pass through the output pager. This dcmd is intended to be used with the | operator; the programmer can initiate a pipeline using a list of addresses stored in an external file.

address ::context
address $p

Context switch to the specified process. A context switch operation is valid only when using the kernel target. The process context is specified using the address of its proc structure in the kernel's virtual address space. The special context address "0" is used to denote the context of the kernel itself. MDB can only perform a context switch when examining a crash dump if the dump contains all physical memory pages (as opposed to just kernel pages). The kernel crash dump facility can be configured to dump all pages using dumpadm(1M).

When the user requests a context switch from the kernel target, MDB constructs a new target representing the specified user process. After the switch occurs, the new target interposes its dcmds at the global level: thus the / dcmd can now format and display data from the virtual address space of the user process, the ::mappings dcmd can display the mappings in the address space of the user process, and so on. The kernel target can be restored by executing 0::context.

::dcmds

List the available dcmds and print a brief description for each one.

[ address ] ::dis [ -fw ] [ -n count ] [ address ]

Disassemble starting at or around the address specified by the final argument, or the current value of dot. If the address matches the start of a known function, the entire function is disassembled; otherwise, a "window" of instructions before and after the specified address is printed in order to provide context. By default, instructions are read from the target's virtual address space; if the -f option is present, instructions are read from the target's object file instead. The -w option can be used to force window-mode, even if the address is the start of a known function. The size of the window defaults to ten instructions; the number of instructions can be specified explicitly using the -n option.

::disasms

List the available disassembler modes. When a target is initialized, MDB attempts to select the appropriate disassembler mode. The user can change the mode to any of the modes listed using the ::dismode dcmd.

::dismode [ mode ]
$V [ mode ]

Get or set the disassembler mode. If no argument is specified, print the current disassembler mode. If a mode argument is specified, switch the disassembler to the specified mode. The list of available disassemblers can be displayed using the ::disasms dcmd.

::dmods [ -l ] [ module-name ]

List the loaded debugger modules. If the -l option is specified, the list of the dcmds and walkers associated with each dmod is printed below its name. The output can be restricted to a particular dmod by specifying its name as an additional argument.

::dump

Print a hexadecimal and ASCII memory dump of the 16-byte aligned region of virtual memory containing the address specified by dot. If a repeat count is specified for ::dump, this is interpreted as a number of bytes to dump rather than a number of iterations.

::echo [ string | value ... ]

Print the arguments separated by blanks and terminated by a NEWLINE to standard output. Expressions enclosed in $[ ] will be evaluated to a value and printed in the default base.

::eval command

Evaluate and execute the specified string as a command. If the command contains metacharacters or white space, it should be enclosed in double or single quotes.

::files$f

Print a list of the known source files (symbols of type STT_FILE present in the various target symbol tables).

::fpregs
$x, $X, $y, $Y

Print the floating-point register set of the representative thread.

::formats

List the available output format characters for use with the /, \, ?, and = formatting dcmds. The formats and their use is described in "Formatting dcmds".

::grep command

Evaluate the specified command string, then print the old value of dot if the new value of dot is non-zero. If the command contains white space or metacharacters, it must be quoted. The ::grep dcmd can be used in pipelines to filter a list of addresses.

::help [ dcmd-name ]

With no arguments, the ::help dcmd prints a brief overview of the help facilities available in mdb. If a dcmd-name is specified, MDB prints a usage summary for that dcmd.

::load module-name

Load the specified dmod. The module name can be given as an absolute or relative path. If module-name is a simple name (that is, does not contain a '/'), MDB searches for it in the module library path. Modules with conflicting names cannot be loaded; the existing module must be unloaded first.

::log [ -d | [ -e ] filename ]
$> [ filename ]

Enable or disable the output log. MDB provides an interactive logging facility where both the input commands and standard output can be logged to a file while still interacting with the user. The -e option enables logging to the specified file, or re-enables logging to the previous log file if no file name is given. The -d option disables logging. If the $> dcmd is used, logging is enabled if a file name argument is specified; otherwise, logging is disabled. If the specified log file already exists, MDB appends any new log output to the file.

::map command

Map the value of dot to a corresponding value using the command specified as a string argument, then print the new value of dot. If the command contains white space or metacharacters, it must be quoted. The ::map dcmd can be used in pipelines to transform the list of addresses into a new list of addresses.

[ address ] ::mappings [ name ]
[ address ] $m [ name ]

Print a list of each mapping in the target's virtual address space, including the address, size, and description of each mapping. If the dcmd is preceded by an address, MDB shows only the mapping that contains the given address. If a string name argument is given, MDB shows only the mapping that matched the description.

::nm [ -DPdghnopuvx ] [ object ]

Print the symbol tables associated with the current target. If an object name argument is specified, only the symbol table for this load object is displayed. The ::nm dcmd also recognizes the following options:

-D

Print .dynsym (dynamic symbol table) instead of .symtab.

-P

Print the private symbol table instead of .symtab.

-d

Print value and size fields in decimal.

-g

Print only global symbols.

-h

Suppress the header line.

-n

Sort symbols by name.

-o

Print value and size fields in octal.

-p

Print symbols as a series of ::nmadd commands. This option can be used with -P to produce a macro file that can be subsequently read into the debugger with $<.

-u

Print only undefined symbols.

-v

Sort symbols by value.

-x

Print value and size fields in hexadecimal.

value ::nmadd [ -fo ] [ -e end ] [ -s size ] name

Add the specified symbol name to the private symbol table. MDB provides a private, configurable symbol table that can be used to interpose on the target's symbol table, as described in "Symbol Name Resolution". The ::nmadd dcmd also recognizes the following options:

-e

Set the size of the symbol to end - value.

-f

Set the type of the symbol to STT_FUNC.

-o

Set the type of the symbol to STT_OBJECT.

-s

Set the size of the symbol to size.

::nmdel name

Delete the specified symbol name from the private symbol table.

::objects

Print a map of the target's virtual address space, showing only those mappings that correspond to the primary mapping (usually the text section) of each of the known load objects.

::quit
$q

Quit the debugger.

::regs
$r

Print the general-purpose register set of the representative thread.

::release
:R

Release the previously attached process or core file.

::set [ -wF ] [ +/-o option ] [ -s distance ] [ -I path ] [ -L path ] [ -P prompt ]

Get or set miscellaneous debugger properties. If no options are specified, the current set of debugger properties is displayed. The ::set dcmd recognizes the following options:

-F

Forcibly take over the next user process that ::attach is applied to, as if mdb had been executed with the -F option on the command line.

-I

Set the default path for locating macro files. The path argument can contain any of the special tokens described for the -I command-line option in Appendix A, Options.

-L

Set the default path for locating debugger modules. The path argument can contain any of the special tokens described for the -I command-line option in Appendix A, Options.

-o

Enable the specified debugger option. If the +o form is used, the option is disabled. The option strings are described along with the -o command-line option in Appendix A, Options.

-P

Set the command prompt to the specified prompt string.

-s

Set the symbol matching distance to the specified distance. Refer to the description of the -s command-line option in Appendix A, Options for more information.

-w

Re-open the target for writing, as if mdb had been executed with the -w option on the command line.

[ address ] ::stack [ count ]
[ address ] $c [ count ]

Print a C stack back trace. If the dcmd is preceded by an explicit address, a back trace beginning at this virtual memory address is displayed. Otherwise, the stack of the representative thread is displayed. If an optional count value is given as an argument, no more than count arguments are displayed for each stack frame in the output.

---

64-bit SPARC only -

The biased frame pointer value (that is, the virtual address minus 0x7ff) should be used as the address when requesting a stack trace.

---

::status

Print a summary of information related to the current target.

::typeset [+/-t] variable-name ...

Set attributes for named variables. If one or more variable names are specified, they are defined and set to the value of dot. If the -t option is present, the user-defined tag associated with each variable is set. If the +t option is present, the tag is cleared. If no variable names are specified, the list of variables and their values is printed.

::unload module-name

Unload the specified dmod. The list of active dmods can be printed using the ::dmods dcmd. Built-in modules cannot be unloaded. Modules that are busy (that is, provide dcmds that are currently executing) cannot be unloaded.

::unset variable-name ...

Unset (remove) the specified variable(s) from the list of defined variables. Some variables are exported by MDB are marked as persistent, and cannot be unset by the user.

::vars [-npt]

Print a listing of named variables. If the -n option is present, the output is restricted to variables that currently have non-zero values. If the -p option is present, the variables are printed in a form suitable for re-processing by the debugger using the $< dcmd. This option can be used to record the variables to a macro file, then restore these values later. If the -t option is present, only the tagged variables are printed. Variables can be tagged using the -t option of the ::typeset dcmd.

::version

Print the debugger version number.

address ::vtop

Print the physical address mapping for the specified virtual address, if possible. The ::vtop dcmd is available only when examining a kernel target, or when examining a user process inside a kernel crash dump (after a ::context dcmd has been issued).

[ address ] ::walk walker-name [ variable-name ]

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.

::walkers

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

::whence [-v] name ...
::which [-v] name ...

Print the dmod that exports the specified dcmds and walkers. These dcmds can be used to determine which dmod is currently providing the global definition of the given dcmd or walker. Refer to "dcmd and Walker Name Resolution" for more information on global name resolution. The -v option causes the dcmd to print the alternate definitions of each dcmd and walker in order of precedence.

::xdata

List the external data buffers exported by the current target. External data buffers represent information associated with the target that cannot be accessed through standard target facilities (that is, an address space, symbol table, or register set). These buffers can be consumed by dcmds; for more information, refer to "mdb_get_xdata()".