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

Note:

SPARC 64-bit systems: 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. For detailed information about the mdb command-line syntax, see the mdb(1) man page. 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.

::alias [ [ {-a | -A | -e | -l | -m | -r} ]

[ {+/-}o {forceflags | init_usage | noaddrin | readonly | verbose }

[ -D description | +D ] [ -H help | +H ] [ -U usage | +U ]

[ +/-t template [ +/-t template ... ] ] [ -I init | +I ] [ -F fini | +F ] name [ expansion ... ] ]

Create or remove a shorthand term or shortcut for an mdb expression, with different functionality. ::alias assigns the mdb expression (expansion) to the alias.

With no arguments, ::alias lists all the aliases that are currently defined. With one argument, it lists just that alias.

When creating an alias, the ::alias dcmd attempts to generate correct help, usage and descriptions of the alias based on the expansion. You can override these options. When modifying an alias, if the expansion, init, help or fini options start with a '+' sign, then the new value without the '+' sign is appended to the existing entry.

Aliases accept command-line arguments and flags, which are defined by using templates. Templates can then be used within the expansion using shell-like expressions.

Aliases use templates to define their expansions, in a string of the form:

[X]:[help-string]:var[=value]

Where:

X

The option value for the alias. It can be any letter, "+", or no value.

If the option value is "+", then the option is added to the global options. If it is a letter, then that letter becomes a valid option for the alias. If no value is given, then the value is taken from the option's argument.

If no option value is assigned, then the value is set to a string that can be used as a unique variable while the alias is running.

help-string

Help that is displayed by the ::help dcmd for this option.

var

Name of the variable to assign.

value

Value that is assigned to var. Not required.

Expansions can be declared either as $var or ${var}. When the alias is run, the expansions are expanded and the result is then executed.

::alias supports the following expansions:

$$: Substitute a single '$'.
$*: All the positional parameters that have not been used by flags.
$0: The name of this alias.
$1 through $999: The unused positional parameters.
$MDB_ADDRSPEC: Expands to "" if an address was supplied as an argument.
$MDB_LOOP: Expands to "" if the alias was invoked in a loop with the ",cnt" syntax.
$MDB_LOOP_COUNT: Expands to the value of cnt if the alias was invoked in a loop with the ",cnt" syntax.
$MDB_PIPE: Expands to "" if the alias was invoked with the input from a pipe.
$MDB_PIPE_OUT: Expands to "" if the alias was invoked with the output to a pipe.
$MDB_KERNEL: Expands to "" if debugging the kernel.
$MDB_POSTMORTEM: Expands to "" if debugging a postmortem core dump.
$MDB_ARCH_I386: Expands to "" if the target architecture is i386.
$MDB_ARCH_AMD64: Expands to "" if the current architecture is amd64.
$MDB_ARCH_SPARC: Expands to "" if the target architecture is SPARC.
$MDB_ARCH_SPARCV9: Expands to "" if the current target architecture is SPARCV9.
$MDB_KMDB: Expands to "" if in kmdb.
${parameter:-word}: If parameter is set, substitute its value; otherwise substitute word.
${parameter:+word}: If parameter is set, substitute its value; otherwise substitute nothing.
${parameter:?word}: If parameter is set, substitute its value; otherwise print word to standard error and report the usage.
${parameter:@word}: If parameter is set, print word to standard error and report the usage.

Note:

Do not create expansions that begin with 'MDB'. Expansions beginning with MDB aliases are reserved for internal use.

The ::alias dcmd recognizes the following options:

-a

Add an alias.

-A

Add an alias, overwriting an alias of the same name if it already exists.

-e

Export the alias as the series of mdb expressions that can be used to reproduce the alias.

-l

List an alias.

-m

Modify an alias.

-r

Remove an alias.

o

Using -o, set this option. Using +o, unset this option. Possible option values are:

forceflags: Set or unset flag checking for this alias. By default, aliases that have no flags will not consume flags and pass them as positional parameters to the expansion. With flag checking enabled, the alias will treat flags as a usage error.
init_usage: Set or unset checking of dot after any INIT expression is run. If the value is not zero, return a usage message.
noaddrin: Set or unset noaddrin mode.
readonly: Set or unset the alias to readonly. Readonly aliases can not be modified, except to remove the readonly flag or delete the alias.
verbose: Set or unset verbose mode.

-t

Specify a template.

+t

When modifying an alias, delete this template.

-U

Specify a usage string.

+u

When modifying an alias, delete the usage string.

-D

Specify a description string.

+D

When modifying an alias, delete the description.

-H

Specify a help string.

+h

When modifying an alias, delete the help string.

-F

Specify a fini expression. This mdb expression is evaluated after the expansion is run. The value of dot is not updated by this expression.

+F

When modifying an alias, delete the fini expression.

-I

Specify an mdb expression to initialize any state. MDB evaluates the value of -I before the expansion is run and does not update the value of dot.

+I

When modifying an alias, delete the initialization expression.

For more information and examples, see the mdb(1) man page.

addr ::array [ -t member_type | -s member_size | -S array_size ] [-v variable ] [ type ] [ member ] [ count ] [ variable ] [|::dcmd …]

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.

In its first form, ::array treats dot as the start of an array of type type and length count:

::array type count

In its second form, ::array treats dot as the address of a structure or union of type type with a member that is either a pointer to an array or an embedded array:

::array type member count

In this form, count can be an integer, variable or structure/union field, in which case the value of that field is used. You can also specify the size of the array by using an -s, -S, or -t option. This is useful when the array is pointed to using a void * so the correct size cannot be inferred from the type of the pointer.

The output of ::array can be pipelined to the ::print dcmd to print the elements of an array data structure.

[ 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 [ -v variable-name ] 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.

With the -v option, the return value is stored in variable-name.

::cont [ SIG ]

:c [ SIG ]

Suspend the debugger, continue the target program, and wait for it to terminate or stop following a software event of interest. If the target is already running because the debugger was attached to a running program with the -o nostop option enabled, this dcmd waits for the target to terminate or stop after an event of interest. With an optional signal name or number, the signal is immediately delivered to the target as part of resuming its execution. If the SIGINT signal is traced, control can be asynchronously returned to the debugger by typing the interrupt character, usually Ctrl-C. This SIGINT signal is automatically cleared. If no target program is currently running, ::cont starts a new program running as if by ::run.

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(8). 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 [-v] [[-n] [-d] [--] RE]

List all the dcmds that are currently available or provide a regular expression (RE) to limit the list.

The ::dcmds dcmd recognizes the following options:

-v: Verbose. Print the usage output of each dcmd.
-n RE: Name. Search the name for a match.
-d RE: Description. Search the description for a match.

[ address ] ::dis [ -abfw ] [ -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; use the -n option to explicitly specify the number of instructions. If the -a option is present, addresses are printed as numeric values rather than symbolically. The -b option displays both address and symbol names of the disassembled code.

::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 endianness. 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 [-N] [--] [ string | value ...]

Print the arguments. If the first print argument begins with a '-', you must signify the end of option processing with the argument '--'. Expressions enclosed in $[ ] are evaluated to a value and printed in the default base. The -N option places each argument on a new line.

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

[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. The -g option restricts the search to instruction text that is part of a globally visible function in the target's symbol table.

Note:

SPARC: 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 Dcmd Formatting Characters.

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

Note:

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

[ addr ] ::head [ +/- ] num | [ +/- ]n num [ |::dcmd ... ]

Limit the number of elements in the pipe.

-n num
- num: Passes only the first num elements in the pipe.
+n num
+ num: Passes all except the last num elements in the pipe. (num is in decimal).

::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 ] ::if [ -p ] {type member tests | [ type ] [ at off ] test}

Evaluate the tests and then print the old value of dot if the tests are true. With the -p option, use physical rather than virtual addresses.

MDB recognizes two kinds of tests. You can test the value of a member of a structure or union. You can also test an offset from dot. To build more complex tests, join the tests with AND or OR.

The following tests are possible:

&: The values ANDed together are non-zero
%: The left value modulus the right is non-zero
^: The values XORed together are non-zero
streq: The strings exactly match
strneq: The strings don't match
strcaseeq: The strings match case insensitively
strcaseneq: The strings do not match case insensitively
strstr: The string contains the string
strcasestr: The string contains the case insensitive string
strnstr: The string does not contain the string
strcasenstr: The string does not contain the case insensitive string
strleneq: The string is this length
strlenne: The string is not this length
strlengt: The string is longer than this
strlenlt: The string is shorter than this
strlenge: The string is this long or longer
strlenle: The string is this long or shorter

For examples and options to the tests, see the mdb(1) man page.

[ 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 [ -b member [[[-M back_mask ] | [ -I back_inverse_mask] | [ -S back_shift ]] |

[ -E back_evalstr]]] [[[[ -m mask] | [ -i inverse_mask]] [ -s left_shift]] | [ -e evalstr ]]

[ -p] [ -L] [type] member [variable] [|::dcmd ...]

Walk list using member as link pointer. type may be omitted if the C type of address can be inferred. When the -s option is used with -m or -M, the address is masked and then shifted. 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 ::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 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.

The ::list dcmd recognizes the following options:

-b: Verify back pointers in doubly linked lists
-e: Pass the forward pointer through this mdb evaluation
-E: Pass the back pointer through this mdb evaluation
-i: Mask the forward pointer with the inverse of this value
-I: Mask the back pointer with the inverse of this value
-L: Check for loops in the list
-m: Mask the forward pointer with this value
-M: Mask the back pointer with this value
-p: Use physical addresses
-s: Shift left the forward pointer this many bits
-S: Shift left the back pointer this many bits

::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 types. 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 MDB 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 MDB Symbol Name Resolution.

[ 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 structure, 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 quotation marks or double quotation marks. The type name can use the backquote (`) scoping operator described under MDB Symbol Name Resolution. If the type is a structured type, the ::print dcmd recursively prints 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 infers 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.

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 the mdb(1) man page.

address ::printf [ -t format ... ] format [ type ] ...

Print the data structure using the printf format command. Arguments to the command are:

An element in the structure or union
The value from a symbol
An absolute value
The value of the var variable

The optional -t argument is used to specify a title. The title is printed once before any other output is produced. For possible expansions in the format string, see the ::help printf command.

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

::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 the mdb(1) man page.
-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 the mdb(1) man page.
-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 the mdb(1) man page.
-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 the mdb(1) man page.
-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 structure, union, enum, fundamental integer type, or a pointer to any of these types. The type name may use the backquote (`) scoping operator described in MDB Symbol Name Resolution.

... | ::sort [ -u [ -c ] [ -v var ]] [ type ] [ -s [ -i ]] [ -r ] [ at ] offset | member

[[ -s [ -i ]] [ -r ] [ -u ] member]… [ | dcmd …]

Sort the addresses based on the rules given.

With no arguments, ::sort sorts the address based on its numeric values.
If a type is given, then ::sort sorts based on the member of structure or union given.
If an n offset is given, then the sort is based on the value of the simple type at that value.
Multiple sort keys can be given and each sort key can have its own options. See SORT KEY OPTIONS.

::sort recognizes the following simple types:

addr
int
uint
char
char
uchar
short
ushort
long
ulong
longlong
ulonglong
pointer

::sort recognizes the following options:

-u: Unique. Only prints addresses that match according to the sort criteria once.
-R: Not unique. Suppresses lines that do not have matches according to the sort.
-U: Really unique. Only prints entries that are unique according to the sort.
-c: If not outputting to a pipe and using the unique flag, then print a count of matches before each address.
-v: Stores the count of unique entries in variable var.

SORT KEY OPTIONS

-r: Reverse the order of this test.
-s: Treat this item as a string.
-i: If sorting strings, ignore case.
-u: Unique for this key. Sort using the remaining keys but only output the last entry that matches on this key. See ::help sort for examples.
-l len: If sorting pointers, dereference the pointer and compare len bytes.

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

Note:

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

[address] ::stackinfo [-h|-a]

Display kthread_t stack usage.

Shows the real utilization of the kernel stack if the /etc/system kmem_stackinfo tunable (an unsigned integer) is nonzero at kthread creation time. For example:

          THREAD            STACK   SIZE  CUR  MAX CMD/LWPID
ffffff014f5f2c20 ffffff0004153000   4f00   4%  43% init/1

The current stack size utilization for this kthread is 4% of its maximum size. The stack size utilization for this kthread has been up to 43% of its maximum size. Stack size is 4f00 bytes.

The MAX value can be shown as n/a (not available) in the following cases:

For the very first kthread (sched/1)
If kmem_stackinfo was zero at kthread creation time
If the kthread has not yet run

The -a option shows TS_FREE kthreads (interrupt kthreads). The -h option shows history (dead kthreads that used their kernel stack the most).

If the /etc/system kmem_stackinfo tunable is nonzero, then the DTrace probe sdt:genunix:stkinfo_end:stack-usage is activated for dead kthreads as follows:

arg0	`kthread_t *`	A dead kthread
arg1	`size_t`	The kernel stack size of the dead kthread
arg2	`size_t`	A percentage that is the maximum use of the kernel stack for this dead kthread

If the /etc/system kmem_stackinfo tunable is nonzero, then the performance of creating and deleting kthreads is decreased.

::status

Print a summary of information related to the current target.

[ addr ] ::sum [ type [ member ]]

Add up list of numbers from pipe. These can be read directly or acquired from a member in a structure specified by addr.

[ addr ] ::strlen

Print the length of a string.

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.

[ addr ] ::tail [ +/- ] num | [ +/- ]n num [ |::dcmd ... ]

Print the last elements in the pipe.

-n num
- num: Passes only the last num elements in the pipe.
+n num
+ num: Passes all except the first num elements in the pipe. (num is in decimal).

::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 in MDB. The symbol name may use any of the scoping operators described under MDB 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 variables 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 [[ -n ] [ -d ] [--] RE ]

List all the walkers that are currently available or provide a regular expression (RE) to limit the list.

The ::walkers dcmd recognizes the following options:

-n RE: Name. Search the name for a match.
-d RE: Description. Search the description for a match.

... | ::wc [ -x ]

Count the elements in a pipe. With the -x option, output the value in hexadecimal.

::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 about global name resolution. The -v option causes the dcmd to print the alternate definitions of each dcmd, dcmd alias, 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() Function.