Chapter 5 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, and 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.

$M

In kmdb only, list the macro files that are cached by kmdb for use with the $< dcmd.

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.

::array type count

Print the address of each element of an array. The type of the array elements should be specified as the first argument, type, and the number of elements to be computed should be specified as the second argument, count. The output of ::array can be pipelined to the ::print dcmd to print the elements of an array data structure.

---

Note –

This dcmd may only be used with objects that contain compressed symbolic debugging information designed for use with mdb. This information is currently only available for certain Solaris kernel modules. The SUNWzlib decompression software must be installed in order to process the symbolic debugging information.

---

[ 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.

::branches [ -v ]

Display the most recent branches taken by the current CPU. This dcmd is currently only available when using kmdb on x86 systems where the appropriate processor-specific feature is enabled. The number and type of branches that can be displayed is determined by the processor architecture. If the -v option is present, the instructions prior to each branch are displayed.

::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 the physical memory pages of the specified user process (as opposed to just kernel pages). The kernel crash dump facility can be configured to dump all pages or the pages of the current user process using dumpadm(1M). The ::status dcmd can be used to display the contents of the current crash dump.

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.

::cpuregs [ -c cpuid ]

Display the current general-purpose register set for the current CPU or the specified cpuid. This command is only available when using kmdb.

::cpustack [ -c cpuid ]

Display a C stack backtrace for the thread executing on the current CPU or the specified cpuid. This command is only available when using kmdb.

::dcmds

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

[ address ] ::dis [ -afw ] [ -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 -f option is enabled by default if the debugger is not currently attached to a live process, core file, or crash dump. 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. If the -a option is present, addresses are printed as numeric values rather than symbolically.

::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.

[address] ::dump [-eqrstu] [-f|-p] [-g bytes] [-w paragraphs]

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. The ::dump dcmd also recognizes the following options:

-e

Adjust for endian-ness. The -e option assumes 4-byte words; the -g option can be used to change the default word size.

-f

Read data from the object file location corresponding to the given virtual address instead of from the target's virtual address space. The -f option is enabled by default if the debugger is not currently attached to a live process, core file, or crash dump.

-g group

Display bytes in groups of bytes. The default group size is 4 bytes. The group size must be a power of two that divides the line width

-p

Interpret address as a physical address location in the target's address space instead of a virtual address.

-q

Do not print an ASCII decoding of the data.

-r

Number lines relative to the start address instead of with the explicit address of each line. This option implies the -u option.

-s

Elide repeated lines.

-t

Only read from and display the contents of the specified addresses, instead of reading and printing entire lines.

-u

Unalign output instead of aligning the output at a paragraph boundary.

-w paragraphs

Display paragraphs 16-byte paragraphs per line. The default number of paragraphs is one. The maximum value accepted for -w is 16.

::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 [object]$f

Print a list of the known source files (symbols of type STT_FILE present in the various target symbol tables). If an object name is specified, the output is restricted to file symbols present in the corresponding object file.

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

Search instruction text for instructions that refer to the specified symbols or addresses. The search list should consist of one or more addresses or symbol names specified as an address preceding the dcmd or one or more symbol names or expressions following the dcmd. If the -g option is specified, the search is restricted to instruction text that is part of a globally visible function in the target's symbol table.

---

Note –

SPARC only. The ::findsym dcmd is only available when debugging a target that uses the SPARC instruction set architecture.

---

::formats

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

[ thread ] ::fpregs [-dqs]
[ thread ] $x, $X, $y, $Y

Print the floating-point register set of the representative thread. If a thread is specified, the floating point registers of that thread are displayed. The thread expression should be one of the thread identifiers described under Thread Support.

---

Note –

SPARC only. The -d, -q, and -s options can be used to display the floating point registers as a collection of double-precision (-d), quad-precision (-q), or single-precision (-s) floating point values.

---

::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.

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

Read and display len bytes from the I/O port specified by address. The value of the -L option, if present, takes precedence over the repeat count specified on the left-hand side. The len must be 1, 2, or 4 bytes and the port address must be aligned according to the length. This command is only available when using kmdb on x86 systems.

[ address ] ::list type member [ variable-name ]

Walk through the elements of a linked list data structure and print the address of each element in the list. The address of the first element in the list can be specified using an optional address; otherwise the list is assumed to start at the current value of dot. The type parameter must name a C struct or union type and is used to describe the type of the list elements so that MDB can read in objects of the appropriate size. The member parameter is used to name the member of type that contains a pointer to the next list element. The ::list dcmd will continue iterating until a NULL pointer is encountered, the first element is reached again (a circular list), or an error occurs while reading an element. 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 a pipeline.

---

Note –

This dcmd may only be used with objects that contain compressed symbolic debugging information designed for use with mdb. This information is currently only available for certain Solaris kernel modules. The SUNWzlib decompression software must be installed in order to process the symbolic debugging information.

---

::load [ -s] 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. If the -s option is present, MDB will remain silent and not issue any error messages if the module is not found or could not be loaded.

::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.

[address] ::nm [ -DPdghnopuvx ] [ - t types ] [ - f format ] [ object]

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

-D

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

-P

Prints the private symbol table instead of .symtab.

-d

Prints value and size fields in decimal.

-f format [,format...]

Print only the specified symbol information. The valid format argument strings are:

ndx

symbol table index

val

symbol table

size

size in bytes

type

symbol type

bind

binding

oth

other

shndx

section index

name

symbol name

ctype

C type for symbol (if known)

obj

object which defines symbol

-g

Prints only global symbols.

-h

Suppresses the header line.

-n

Sorts symbols by name.

-o

Prints value and size fields in octal.

-p

Prints 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 $<.

-t type [,type...]

Prints only symbols of the specified type(s). The valid type argument strings are:

noty

STT_NOTYPE

objt

STT_OBJECT

func

STT_FUNC

sect

STT_SECTION

file

STT_FILE

comm

STT_COMMON

tls

STT_TLS

regi

STT_SPARC_REGISTER

-u

Prints only undefined symbols.

-v

Sorts symbols by value.

-x

Prints 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 [ -v ]

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. If the -v option is present, the command displays the version of each object if version information is know. If no version information is known, a version of Unknown will be displayed in the output.

::offsetof type member

Print the offset of the specified member of the specified type. The type should be the name of a C structure. The offset is printed in bytes, unless the member is a bit-field in which case the offset may be printed in bits. The output is always suffixed with the appropriate units for clarity. The type name may use the backquote (`) scoping operator described in Symbol Name Resolution.

---

Note –

This dcmd may only be used with objects that contain compressed symbolic debugging information designed for use with mdb. This information is currently only available for certain Solaris kernel modules. The SUNWzlib decompression software must be installed in order to process the symbolic debugging information.

---

[ address [ , len ]] ::out [ -L len ]

Write the specified value to the I/O port specified by address. The value of the -L option, if present, takes precedence over the repeat count specified on the left-hand side. The len must be 1, 2, or 4 bytes and the port address must be aligned according to the length. This command is only available when using kmdb on x86 systems.

[address] ::print [-aCdiLptx] [-c lim] [-l lim] [type [member|offset ... ]]

Print the data structure at the specified virtual address using the given type information. The type parameter may name a C struct, union, enum, fundamental integer type, or a pointer to any of these types. If the type name contains whitespace (for example, "struct foo") it must be enclosed in single or double quotes. The type name may use the backquote (`) scoping operator described under Symbol Name Resolution. If the type is a structured type, the ::print dcmd will recursively print each member of the struct or union. If the type argument is not present and a static or global STT_OBJECT symbol matches the address, ::print will infer the appropriate type automatically.

The type argument can be followed by an optional list of member or offset expressions, in which case only those members and submembers of the specified type are displayed. Members can be specified using C syntax that includes the array index operator ([]), the structure member operator (->), and the structure pointer operator (.). Offsets can be specified using the MDB arithmetic expansion syntax ($[]).After displaying the data structure, ::print increments dot by the size of type in bytes.

---

Note –

The ::print dcmd may only be used with objects that contain compressed symbolic debugging information designed for use with MDB. This information is only available at present in certain Solaris kernel modules and user libraries. The SUNWzlib decompression software must be installed in order to process the symbolic debugging information.

---

If the -a option is present, the address of each member is displayed. If the -i option is present, the expression on the left-hand side is interpreted as an immediate value to be displayed using the specified type. If the -p option is present, ::print interprets address as a physical memory address instead of a virtual memory address. If the -t option is present, the type of each member is displayed. If the -d or -x options are present, all integers are displayed in decimal (-d) or hexadecimal (-x); by default a heuristic is used to determine if the value should be displayed in decimal or hexadecimal. The number of characters in a character array that will be read and displayed as a string can be limited with the -c option. If the -C option is present, no limit is enforced. The number of elements in a standard array that will be read and displayed can be limited with the -l option. If the -L option is present, no limit is enforced and all array elements are shown. The default values for -c and -l can be modified using ::set or the -o command-line option as described in Appendix A, Options.

::quit [ -u ]
$q [ -u ]

Quit the debugger. When using kmdb only, the -u option causes the debugger to resume execution of the operating system and unload the debugger. The -u option cannot be used if kmdb was loaded at boot. If the -u option is not present, ::quit causes kmdb to exit to the firmware (on SPARC systems) or causes the system to reboot (on x86 systems).

[ thread ] ::regs
[ thread ] $r

Print the general-purpose register set of the representative thread. If a thread is specified, the general purpose register set of that thread is displayed. The thread expression should be one of the thread identifiers described under Thread Support.

::release [ -a ]
:R [ -a ]

Release the previously attached process or core file. If the -a option is present, the process is released and left stopped and abandoned. It can subsequently be continued by prun(1) or it can be resumed by applying MDB or another debugger. By default, a released process is forcibly terminated if it was created by MDB using ::run, or it is released and set running if it was attached to by MDB using the -p option or using the ::attach or :A dcmds.

::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.

::showrev [ -pv ]

Display revision information for the hardware and software corresponding the current target. If no options are specified, general system information is displayed. If the -p option is present, information for each load object that is part of a patch is displayed. If the -v option is present, information for each load object is displayed. Load objects without version information will be omitted from the output for the -p option. Load objects without version information will report Unknown in the output of the -v option.

::sizeof type

Print the size of the specified type in bytes. The type parameter may name a C struct, union, enum, fundamental integer type, or a pointer to any of these types. The type name may use the backquote (`) scoping operator described in Symbol Name Resolution.

---

Note –

This dcmd may only be used with objects that contain compressed symbolic debugging information designed for use with mdb. This information is currently only available for certain Solaris kernel modules. The SUNWzlib decompression software must be installed in order to process the symbolic debugging information.

---

[ 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.

cpuid ::switch
cpuid :x

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.

::term

Print the name of the terminal type that MDB is using to perform any terminal-dependent input and output operations, such as command-line editing.

thread ::tls symbol

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.

::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 [-a as]

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.

[ 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().