MDB(1) User Commands MDB(1)

NAME


mdb - modular debugger

SYNOPSIS


mdb [-fkmuwyAFKMSUW] [+-o option] [-b VM] [-p pid] [-s distance]
[-I path] [-L path] [-P prompt] [-R root]
[-V dis-version] [-e expr] [object [core] | core | suffix]


DESCRIPTION


Introduction


The mdb utility is an extensible utility for low-level debugging and
editing of the live operating system, operating system crash dumps, user
processes, user process core dumps, and object files. For a more detailed
description of mdb features, refer to the Modular Debugger Guide.


Debugging is the process of analyzing the execution and state of a
software program in order to remove defects. Traditional debugging tools
provide facilities for execution control so that programmers can re-
execute programs in a controlled environment and display the current
state of program data or evaluate expressions in the source language used
to develop the program.


Unfortunately, these techniques are often inappropriate for debugging
complex software systems such as an operating system, where bugs might
not be reproducible and program state is massive and distributed, for
programs that are highly optimized, have had their debug information
removed, or are themselves low-level debugging tools, or for customer
situations where the developer can only access post-mortem information.


mdb provides a completely customizable environment for debugging these
programs and scenarios, including a dynamic module facility that
programmers can use to implement their own debugging commands to perform
program-specific analysis. Each mdb module can be used to examine the
program in several different contexts, including live and post-mortem.

Definitions


The target is the program being inspected by the debugger. mdb currently
provides support for the following types of targets: user processes, user
process core files, live bhyve VMs, the live operating system (via
/dev/kmem and /dev/ksyms), operating system crash dumps, user process
images recorded inside an operating system crash dump, ELF object files,
and raw binary files. Each target exports a standard set of properties,
including one or more address spaces, one or more symbol tables, a set of
load objects, and a set of threads that can be examined using the
debugger commands described below.


A debugger command, or dcmd (pronounced dee-command) in mdb terminology,
is a routine in the debugger that can access any of the properties of the
current target. mdb parses commands from standard input, and then
executes the corresponding dcmds. Each dcmd can also accept a list of
string or numerical arguments, as shown in the syntax description below.
mdb contains a set of built-in dcmds, described below, that are always
available. You can also extend the capabilities of mdb itself by writing
your own dcmds, as described in the Modular Debugger Guide.


A walker is a set of routines that describe how to walk, or iterate,
through the elements of a particular program data structure. A walker
encapsulates the data structure's implementation from dcmds and from mdb
itself. You can use walkers interactively, or use them as a primitive to
build other dcmds or walkers. As with dcmds, you can extend mdb by
implementing your own walkers as part of a debugger module.


A debugger module, or dmod (pronounced dee-mod), is a dynamically loaded
library containing a set of dcmds and walkers. During initialization, mdb
attempts to load dmods corresponding to the load objects present in the
target. You can subsequently load or unload dmods at any time while
running mdb. mdb ships with a set of standard dmods for debugging the
kernel. The Modular Debugger Guide contains more information on
developing your own debugger modules.


A macro file is a text file containing a set of commands to execute.
Macro files are typically used to automate the process of displaying a
simple data structure. mdb provides complete backward compatibility for
the execution of macro files written for adb(1), and illumos includes a
set of macro files for debugging the kernel that can be used with either
tool.

Syntax


The debugger processes commands from standard input. If standard input is
a terminal, mdb provides terminal editing capabilities. mdb can also
process commands from macro files and from dcmd pipelines, described
below. The language syntax is designed around the concept of computing
the value of an expression (typically a memory address in the target),
and then applying a dcmd to that address. The current address location is
referred to as dot, and its value is referenced using ``.''.


A metacharacter is one of the following characters:

[ ] | ! / \ ? = > $ : ;
NEWLINE SPACE TAB


A blank is a TAB or a SPACE. A word is a sequence of characters separated
by one or more non-quoted metacharacters. Some of the metacharacters only
function as delimiters in certain contexts, as described below. An
identifier is a sequence of letters, digits, underscores, periods, or
backquotes beginning with a letter, underscore, or period. Identifiers
are used as the names of symbols, variables, dcmds, and walkers.
Commands are delimited by a NEWLINE or semicolon ( ; ).


A dcmd is denoted by one of the following words or metacharacters:

/ \ ? = > $character :character ::identifier


dcmds named by metacharacters or prefixed by a single $ or : are provided
as built-in operators, and implement complete compatibility with the
command set of the legacy adb(1) utility. Once a dcmd has been parsed,
the /, \, ?, =, >, $, and : characters are no longer recognized as
metacharacters until the termination of the argument list.


A simple-command is a dcmd followed by a sequence of zero or more blank-
separated words. The words are passed as arguments to the invoked dcmd,
except as specified under Quoting and Arithmetic Expansion below. Each
dcmd returns an exit status that indicates it was either successful,
failed, or was invoked with invalid arguments.


A pipeline is a sequence of one or more simple commands separated by |.
Unlike the shell, dcmds in mdb pipelines are not executed as separate
processes. After the pipeline has been parsed, each dcmd is invoked in
order from left to right. Each dcmd's output is processed and stored as
described under dcmd Pipelines below. Once the left-hand dcmd is
complete, its processed output is used as input for the next dcmd in the
pipeline. If any dcmd does not return a successful exit status, the
pipeline is aborted.


An expression is a sequence of words that is evaluated to compute a
64-bit unsigned integer value. The words are evaluated using the rules
described under Arithmetic Expansion below.

Commands


A command is one of the following:

pipeline [! word ...] [ ; ]

A simple-command or pipeline can be optionally suffixed with the !
character, indicating that the debugger should open a pipe(2) and
send the standard output of the last dcmd in the mdb pipeline to an
external process created by executing $SHELL -c followed by the
string formed by concatenating the words after the ! character. For
more details, refer to Shell Escapes below.


expression pipeline [! word ...] [ ; ]

A simple-command or pipeline can be prefixed with an expression.
Before execution of the pipeline, the value of dot (the variable
denoted by ``.'') is set to the value of the expression.


expression , expression pipeline [! word ...] [ ; ]

A simple-command or pipeline can be prefixed with two expressions.
The first is evaluated to determine the new value of dot, and the
second is evaluated to determine a repeat count for the first dcmd in
the pipeline. This dcmd is executed count times before the next dcmd
in the pipeline is executed. The repeat count only applies to the
first dcmd in the pipeline.


, expression pipeline [! word ...] [ ; ]

If the initial expression is omitted, dot is not modified but the
first dcmd in the pipeline is repeated according to the value of the
expression.


expression [! word ...] [ ; ]

A command can consist only of an arithmetic expression. The
expression is evaluated and the dot variable is set to its value, and
then the previous dcmd and arguments are executed using the new value
of dot.


expression, expression [! word ...] [ ; ]

A command can consist only of a dot expression and repeat count
expression. After dot is set to the value of the first expression,
the previous dcmd and arguments are repeatedly executed the number of
times specified by the value of the second expression.


, expression [! word ...] [ ; ]

If the initial expression is omitted, dot is not modified but the
previous dcmd and arguments are repeatedly executed the number of
times specified by the value of the count expression.


! word ... [ ; ]

If the command begins with the ! character, no dcmds are executed and
the debugger simply executes $SHELL -c followed by the string formed
by concatenating the words after the ! character.


Comments


A word beginning with // causes that word and all the subsequent
characters up to a NEWLINE to be ignored.

Arithmetic Expansion


Arithmetic expansion is performed when an mdb command is preceded by an
optional expression representing a start address, or a start address and
a repeat count. Arithmetic expansion can also be performed to compute a
numerical argument for a dcmd. An arithmetic expression can appear in an
argument list enclosed in square brackets preceded by a dollar sign ($[
expression ]), and is replaced by the value of the expression.


Expressions can contain any of the following special words:

integer
The specified integer value. Integer values can be
prefixed with 0i or 0I to indicate binary values,
0o or 0O to indicate octal values, 0t or 0T to
indicate decimal values, and 0x or 0X to indicate
hexadecimal values (the default).


0[tT][0-9]+.[0-9]+
The specified decimal floating point value,
converted to its IEEE double-precision floating
point representation.


'cccccccc'
The integer value computed by converting each
character to a byte equal to its ASCII value. Up to
eight characters can be specified in a character
constant. Characters are packed into the integer in
reverse order (right-to-left) beginning at the
least significant byte.


<identifier
The value of the variable named by identifier.


identifier
The value of the symbol named by identifier.


(expression)
The value of expression.


.
The value of dot.


&
The most recent value of dot used to execute a
dcmd.


+
The value of dot incremented by the current
increment.


^
The value of dot decremented by the current
increment.


The increment is a global variable that stores the total bytes read by
the last formatting dcmd. For more information on the increment, refer to
the discussion of Formatting dcmds below.


Unary operators are right associative and have higher precedence than
binary operators. The unary operators are:

#expression
Logical negation.


~expression
Bitwise complement.


-expression
Integer negation.


%expression
The value of a pointer-sized quantity at the
object file location corresponding to virtual
address expression in the target's virtual address
space.


%/[csil]/expression
The value of a char, short, int, or long-sized
quantity at the object file location corresponding
to virtual address expression in the target's
virtual address space.


%/[1248]/expression
The value of a one, two, four, or eight-byte
quantity at the object file location corresponding
to virtual address expression in the target's
virtual address space.


*expression
The value of a pointer-sized quantity at virtual
address expression in the target's virtual address
space.


*/[csil]/expression
The value of a char, short, int, or long-sized
quantity at virtual address expression in the
target's virtual address space.


*/[1248]/expression
The value of a one, two, four, or eight-byte
quantity at virtual address expression in the
target's virtual address space.


Binary operators are left associative and have lower precedence than
unary operators. The binary operators, in order of precedence from
highest to lowest, are:

*
Integer multiplication.


%
Integer division.


#
Left-hand side rounded up to next multiple of right-hand side.


+
Integer addition.


-
Integer subtraction.


<<
Bitwise shift left.


>>
Bitwise shift right.


==
Logical equality.


!=
Logical inequality.


&
Bitwise AND.


^
Bitwise exclusive OR.


|
Bitwise inclusive OR.


Quoting


Each metacharacter described above (see Syntax) terminates a word unless
quoted. Characters can be quoted (forcing mdb to interpret each character
as itself without any special significance) by enclosing them in a pair
of single (' ') or double (" ") quote marks. A single quote cannot appear
within single quotes. Inside double quotes, mdb recognizes the C
programming language character escape sequences.

Shell Escapes


The ! character can be used to create a pipeline between an mdb command
and the user's shell. If the $SHELL environment variable is set, mdb
forks and execs this program for shell escapes; otherwise /bin/sh is
used. The shell is invoked with the -c option followed by a string formed
by concatenating the words after the ! character. The ! character takes
precedence over all other metacharacters, except semicolon (;) and
NEWLINE. Once a shell escape is detected, the remaining characters up to
the next semicolon or NEWLINE are passed as is to the shell. The output
of shell commands can not be piped to mdb dcmds. Commands executed by a
shell escape have their output sent directly to the terminal, not to mdb.

Variables


A variable is a variable name, a corresponding integer value, and a set
of attributes. A variable name is a sequence of letters, digits,
underscores, or periods. A variable can be assigned a value using the >
dcmd or ::typeset dcmd, and its attributes can be manipulated using the
::typeset dcmd. Each variable's value is represented as a 64-bit unsigned
integer. A variable can have one or more of the following attributes:
read-only (cannot be modified by the user), persistent (cannot be unset
by the user), and tagged (user-defined indicator).


The following variables are defined as persistent:

0
The most recent value printed using the /, \, ?, or = dcmd.


9
The most recent count used with the $< dcmd.


b
The virtual address of the base of the data section.


d
The size of the data section in bytes.


e
The virtual address of the entry point.


m
The initial bytes (magic number) of the target's primary object
file, or zero if no object file has been read yet.


t
The size of the text section in bytes.


hits
The count of the number of times the matched software event
specifier has been matched. See Event Callbacks, below.


thread
The thread identifier of the current representative thread. The
value of the identifier depends on the threading model used by
the current target. See Thread Support, below.


In addition, the mdb kernel and process targets export the current values
of the representative thread's register set as named variables. The names
of these variables depend on the target's platform and instruction set
architecture.

Symbol Name Resolution


As explained in the Syntax description above, a symbol identifier present
in an expression context evaluates to the value of this symbol. The value
typically denotes the virtual address of the storage associated with the
symbol in the target's virtual address space. A target can support
multiple symbol tables including, but not limited to, a primary
executable symbol table, a primary dynamic symbol table, a run-time link-
editor symbol table, and standard and dynamic symbol tables for each of a
number of load objects (such as shared libraries in a user process, or
kernel modules in the kernel). The target typically searches the primary
executable's symbol tables first, and then one or more of the other
symbol tables. Notice that ELF symbol tables only contain entries for
external, global, and static symbols; automatic symbols do not appear in
the symbol tables processed by mdb.


Additionally, mdb provides a private user-defined symbol table that is
searched prior to any of the target symbol tables. The private symbol
table is initially empty, and can be manipulated using the ::nmadd and
::nmdel dcmds. The ::nm -P option can be used to display the contents of
the private symbol table. The private symbol table allows the user to
create symbol definitions for program functions or data that were either
missing from the original program or stripped out. These definitions are
then used whenever mdb converts a symbolic name to an address, or an
address to the nearest symbol.


As targets contain multiple symbol tables, and each symbol table can
include symbols from multiple object files, different symbols with the
same name can exist. mdb uses the backquote (`) character as a symbol
name scoping operator to allow the programmer to obtain the value of the
desired symbol in this situation. The programmer can specify the scope
used to resolve a symbol name as either: object`name, or file`name, or
object`file`name. The object identifier refers to the name of a load
object. The file identifier refers to the basename of a source file that
has a symbol of type STT_FILE in the specified object's symbol table. The
object identifier's interpretation depends on the target type.


The mdb kernel target expects object to specify the basename of a loaded
kernel module. For example, the symbol name

specfs`_init


evaluates to the value of the _init symbol in the specfs kernel module.


The mdb process target expects object to specify the name of the
executable or of a loaded shared library. It can take any of the
following forms:

1. An exact match (that is, a full pathname): /usr/lib/libc.so.1

2. An exact basename match: libc.so.1

3. An initial basename match up to a ``.'' suffix: libc.so or
libc

4. The literal string a.out is accepted as an alias for the
executable.


The process target also accepts any of the four forms described above
preceded by an optional link-map id (lmid). The lmid prefix is specified
by an initial "LM" followed by the link-map id in hexadecimal followed by
an additional backquote. For example, the symbol name

LM0`libc.so.1`_init


evaluates to the value of the _init symbol in the libc.so.1 library that
is loaded on link-map 0 (LM_ID_BASE). The link-map specifier can be
necessary to resolve symbol naming conflicts in the event that the same
library is loaded on more than one link map. For more information on link
maps, refer to the Linker and Libraries Guide and dlopen(3C). Link-map
identifiers are displayed when symbols are printed according to the
setting of the showlmid option, as described under OPTIONS.


In the case of a naming conflict between symbols and hexadecimal integer
values, mdb attempts to evaluate an ambiguous token as a symbol first,
before evaluating it as an integer value. For example, the token f can
either refer to the decimal integer value 15 specified in hexadecimal
(the default base), or to a global variable named f in the target's
symbol table. If a symbol with an ambiguous name is present, the integer
value can be specified by using an explicit 0x or 0X prefix.

dcmd and Walker Name Resolution
As described earlier, each mdb dmod provides a set of dcmds and walkers.
dcmds and walkers are tracked in two distinct, global namespaces. mdb
also keeps track of a dcmd and walker namespace associated with each
dmod. Identically named dcmds or walkers within a given dmod are not
allowed: a dmod with this type of naming conflict fails to load. Name
conflicts between dcmds or walkers from different dmods are allowed in
the global namespace. In the case of a conflict, the first dcmd or walker
with that particular name to be loaded is given precedence in the global
namespace. Alternate definitions are kept in a list in load order. The
backquote character (`) can be used in a dcmd or walker name as a scoping
operator to select an alternate definition. For example, if dmods m1 and
m2 each provide a dcmd d, and m1 is loaded prior to m2, then:

::d
Executes m1's definition of d.


::m1`d
Executes m1's definition of d.


::m2`d
Executes m2's definition of d.


If module m1 were now unloaded, the next dcmd on the global definition
list (m2`d) would be promoted to global visibility. The current
definition of a dcmd or walker can be determined using the ::which dcmd,
described below. The global definition list can be displayed using the
::which -v option.

dcmd Pipelines
dcmds can be composed into a pipeline using the | operator. The purpose
of a pipeline is to pass a list of values, typically virtual addresses,
from one dcmd or walker to another. Pipeline stages might be used to map
a pointer from one type of data structure to a pointer to a corresponding
data structure, to sort a list of addresses, or to select the addresses
of structures with certain properties.


mdb executes each dcmd in the pipeline in order from left to right. The
leftmost dcmd is executed using the current value of dot, or using the
value specified by an explicit expression at the start of the command.
When a | operator is encountered, mdb creates a pipe (a shared buffer)
between the output of the dcmd to its left and the mdb parser, and an
empty list of values. As the dcmd executes, its standard output is placed
in the pipe and then consumed and evaluated by the parser, as if mdb were
reading this data from standard input. Each line must consist of an
arithmetic expression terminated by a NEWLINE or semicolon (;). The value
of the expression is appended to the list of values associated with the
pipe. If a syntax error is detected, the pipeline is aborted.


When the dcmd to the left of a | operator completes, the list of values
associated with the pipe is then used to invoke the dcmd to the right of
the | operator. For each value in the list, dot is set to this value and
the right-hand dcmd is executed. Only the rightmost dcmd in the pipeline
has its output printed to standard output. If any dcmd in the pipeline
produces output to standard error, these messages are printed directly to
standard error and are not processed as part of the pipeline.

Signal Handling


The debugger ignores the PIPE and QUIT signals. The INT signal aborts the
command that is currently executing. The debugger intercepts and provides
special handling for the ILL, TRAP, EMT, FPE, BUS, and SEGV signals. If
any of these signals are generated asynchronously (that is, delivered
from another process using kill(2)), mdb restores the signal to its
default disposition and dump core. However, if any of these signals are
generated synchronously by the debugger process itself and a dcmd from an
externally loaded dmod is currently executing, and standard input is a
terminal, mdb provides a menu of choices allowing the user to force a
core dump, quit without producing a core dump, stop for attach by a
debugger, or attempt to resume. The resume option aborts all active
commands and unload the dmod whose dcmd was active at the time the fault
occurred. It can then be subsequently re-loaded by the user. The resume
option provides limited protection against buggy dcmds. Refer to
WARNINGS, Use of the Error Recovery Mechanism, below for information
about the risks associated with the resume option.

Command Re-entry
The text of the last HISTSIZE (default 128) commands entered from a
terminal device are saved in memory. The in-line editing facility,
described next, provides key mappings for searching and fetching elements
from the history list.

In-line Editing
If standard input is a terminal device, mdb provides some simple emacs-
style facilities for editing the command line. The search, previous, and
next commands in edit mode provide access to the history list. Only
strings, not patterns, are matched when searching. In the table below,
the notation for control characters is caret (^) followed by a character
shown in upper case. The notation for escape sequences is M- followed by
a character. For example, M-f (pronounced meta-eff) is entered by
depressing ESC followed by 'f', or by depressing Meta followed by 'f' on
keyboards that support a Meta key. A command line is committed and
executed using RETURN or NEWLINE. The edit commands are:

^F
Move cursor forward (right) one character.


M-f
Move cursor forward one word.


^B
Move cursor backward (left) one character.


M-b
Move cursor backward one word.


^A
Move cursor to start of line.


^E
Move cursor to end of line.


^D
Delete current character, if the current line is not empty.
If the current line is empty, ^D denotes EOF and the
debugger exits.


M-^H
(Meta-backspace) Delete previous word.


^K
Delete from the cursor to the end of the line.


^L
Clear the screen and reprint the current line.


^T
Transpose current character with next character.


^N
Fetch the next command from the history. Each time ^N is
entered, the next command forward in time is retrieved.


^P
Fetch the previous command from the history. Each time ^P
is entered, the next command backward in time is retrieved.


^R[string]
Search backward in the history for a previous command line
containing string. The string should be terminated by a
RETURN or NEWLINE. If string is omitted, the previous
history element containing the most recent string is
retrieved.


The editing mode also interprets the following user-defined sequences as
editing commands. User defined sequences can be read or modified using
the stty(1) command.

erase
User defined erase character (usually ^H or ^?). Delete
previous character.


intr
User defined interrupt character (usually ^C). Abort the
current command and print a new prompt.


kill
User defined kill character (usually ^U). Kill the entire
current command line.


quit
User defined quit character (usually ^\). Quit the debugger.


suspend
User defined suspend character (usually ^Z). Suspend the
debugger.


werase
User defined word erase character (usually ^W). Erase the
preceding word.


On keyboards that support an extended keypad with arrow keys, mdb
interprets these keystrokes as editing commands:

up-arrow
Fetch the previous command from the history (same as ^P).


down-arrow
Fetch the next command from the history (same as ^N).


left-arrow
Move cursor backward one character (same as ^B).


right-arrow
Move cursor forward one character (same as ^F).


Output Pager


mdb provides a built-in output pager. The output pager is enabled if the
debugger's standard output is a terminal device. Each time a command is
executed, mdb pauses after one screenful of output is produced and
displays a pager prompt:

>> More [<space>, <cr>, q, n, c, a] ?


The following key sequences are recognized by the pager:

SPACE
Display the next screenful of output.


a, A
Abort the current top-level command and return
to the prompt.


c, C
Continue displaying output without pausing at
each screenful until the current top-level
command is complete.


n, N, NEWLINE, RETURN
Display the next line of output.


q, Q, ^C, ^\
Quit (abort) the current dcmd only.


Formatting dcmds


The /, \, ?, and = metacharacters are used to denote the special output
formatting dcmds. Each of these dcmds accepts an argument list consisting
of one or more format characters, repeat counts, or quoted strings. A
format character is one of the ASCII characters shown in the table below.
Format characters are used to read and format data from the target. A
repeat count is a positive integer preceding the format character that is
always interpreted in base 10 (decimal). A repeat count can also be
specified as an expression enclosed in square brackets preceded by a
dollar sign ($[ ]). A string argument must be enclosed in double-quotes
(" "). No blanks are necessary between format arguments.


The formatting dcmds are:

/
Display data from the target's virtual address space starting at
the virtual address specified by dot.


\
Display data from the target's physical address space starting at
the physical address specified by dot.


?
Display data from the target's primary object file starting at the
object file location corresponding to the virtual address specified
by dot.


=
Display the value of dot itself in each of the specified data
formats. The = dcmd is therefore useful for converting between
bases and performing arithmetic.


In addition to dot, mdb keeps track of another global value called the
increment. The increment represents the distance between dot and the
address following all the data read by the last formatting dcmd. For
example, if a formatting dcmd is executed with dot equal to address A,
and displays a 4-byte integer, then after this dcmd completes, dot is
still A, but the increment is set to 4. The + character (described under
Arithmetic Expansion above) would now evaluate to the value A + 4, and
could be used to reset dot to the address of the next data object for a
subsequent dcmd.


Most format characters increase the value of the increment by the number
of bytes corresponding to the size of the data format, shown in the
table. The table of format characters can be displayed from within mdb
using the ::formats dcmd. The format characters are:


+ increment dot by the count (variable size)
- decrement dot by the count (variable size)
B hexadecimal int (1 byte)
C character using C character notation (1 byte)
D decimal signed int (4 bytes)
E decimal unsigned long long (8 bytes)
F double (8 bytes)
G octal unsigned long long (8 bytes)
H swap bytes and shorts (4 bytes)
I address and disassembled instruction (variable size)
J hexadecimal long long (8 bytes)
K hexadecimal uintptr_t (4 or 8 bytes)
N newline
O octal unsigned int (4 bytes)
P symbol (4 or 8 bytes)
Q octal signed int (4 bytes)
R binary unsigned long long (8 bytes)
S string using C string notation (variable size)
T horizontal tab
U decimal unsigned int (4 bytes)
V decimal unsigned int (1 byte)
W default radix unsigned int (4 bytes)
X hexadecimal int (4 bytes)
Y decoded time32_t (4 bytes)
Z hexadecimal long long (8 bytes)
^ decrement dot by increment * count (variable size)
a dot as symbol+offset
b octal unsigned int (1 byte)
c character (1 byte)
d decimal signed short (2 bytes)
e decimal signed long long (8 bytes)
f float (4 bytes)
g octal signed long long (8 bytes)
h swap bytes (2 bytes)
i disassembled instruction (variable size)
j jazzed-up binary unsigned long long (8 bytes)
n newline
o octal unsigned short (2 bytes)
p symbol (4 or 8 bytes)
q octal signed short (2 bytes)
r whitespace
s raw string (variable size)
t horizontal tab
u decimal unsigned short (2 bytes)
v decimal signed int (1 byte)
w default radix unsigned short (2 bytes)
x hexadecimal short (2 bytes)
y decoded time64_t (8 bytes)
z write whose size is inferred by CTF info (variable size)


The /, \, and ? formatting dcmds can also be used to write to the
target's virtual address space, physical address space, or object file by
specifying one of the following modifiers as the first format character,
and then specifying a list of words that are either immediate values or
expressions enclosed in square brackets preceded by a dollar sign ($[ ]).


The write modifiers are:

v
Write the lowest byte of the value of each expression to the target
beginning at the location specified by dot.


w
Write the lowest two bytes of the value of each expression to the
target beginning at the location specified by dot.


W
Write the lowest 4 bytes of the value of each expression to the
target beginning at the location specified by dot.


Z
Write the complete 8 bytes of the value of each expression to the
target beginning at the location specified by dot.


The /, \, and ? formatting dcmds can also be used to search for a
particular integer value in the target's virtual address space, physical
address space, and object file, respectively, by specifying one of the
following modifiers as the first format character, and then specifying a
value and optional mask. The value and mask are each specified as either
immediate values or expressions enclosed in square brackets preceded by a
dollar sign. If only a value is specified, mdb reads integers of the
appropriate size and stops at the address containing the matching value.
If a value V and mask M are specified, mdb reads integers of the
appropriate size and stops at the address containing a value X where (X &
M) == V. At the completion of the dcmd, dot is updated to the address
containing the match. If no match is found, dot is left at the last
address that was read.


The search modifiers are:


l Search for the specified 2-byte value.
L Search for the specified 4-byte value.
M Search for the specified 8-byte value.


Notice that for both user and kernel targets, an address space is
typically composed of a set of discontiguous segments. It is not legal to
read from an address that does not have a corresponding segment. If a
search reaches a segment boundary without finding a match, it aborts when
the read past the end of the segment boundary fails.

Execution Control


mdb provides facilities for controlling and tracing the execution of a
live running program. Currently, only the user process target provides
support for execution control. mdb provides a simple model of execution
control: a target process can be started from within the debugger using
::run, or mdb can attach to an existing process using :A, ::attach, or
the -p command-line option, as described below. A list of traced software
events can be specified by the user. Each time a traced event occurs in
the target process, all threads in the target stop, the thread that
triggered the event is chosen as the representative thread, and control
returns to the debugger. Once the target program is set running, control
can be asynchronously returned to the debugger by typing the user-defined
interrupt character (typically ^C).


A software event is a state transition in the target program that is
observed by the debugger. For example, the debugger can observe the
transition of a program counter register to a value of interest (a
breakpoint) or the delivery of a particular signal.


A software event specifier is a description of a class of software events
that is used by the debugger to instrument the target program in order to
observe these events. The ::events dcmd is used to list the software
event specifiers. A set of standard properties is associated with each
event specifier, as described under ::events, below.


The debugger can observe a variety of different software events,
including breakpoints, watchpoints, signals, machine faults, and system
calls. New specifiers can be created using ::bp, ::fltbp, ::sigbp,
::sysbp, or ::wp. Each specifier has an associated callback (an mdb
command string to execute as if it had been typed at the command prompt)
and a set of properties, as described below. Any number of specifiers for
the same event can be created, each with different callbacks and
properties. The current list of traced events and the properties of the
corresponding event specifiers can be displayed using the ::events dcmd.
The event specifier properties are defined as part of the description of
the ::events and ::evset dcmds, below.


The execution control built-in dcmds, described below, are always
available, but issues an error message indicating they are not supported
if applied to a target that does not support execution control. For more
information about the interaction of exec, attach, release, and job
control with debugger execution control, refer to NOTES, below.

Event Callbacks


The ::evset dcmd and event tracing dcmds allow you to associate an event
callback (using the -c option) with each event specifier. The event
callbacks are strings that represent mdb commands to execute when the
corresponding event occurs in the target. These commands are executed as
if they had been typed at the command prompt. Before executing each
callback, the dot variable is set to the value of the representative
thread's program counter and the "hits" variable is set to the number of
times this specifier has been matched, including the current match.


If the event callbacks themselves contain one or more commands to
continue the target (for example, ::cont or ::step), these commands do
not immediately continue the target and wait for it to stop again.
Instead, inside of an event callback, the continue dcmds note that a
continue operation is now pending, and then return immediately.
Therefore, if multiple dcmds are included in an event callback, the step
or continue dcmd should be the last command specified. Following the
execution of all event callbacks, the target immediately resumes
execution if all matching event callbacks requested a continue. If
conflicting continue operations are requested, the operation with the
highest precedence determines what type of continue occurs. The order of
precedence from highest to lowest is: step, step-over (next), step-out,
continue.

Thread Support


mdb provides facilities to examine the stacks and registers of each
thread associated with the target. The persistent "thread" variable
contains the current representative thread identifier. The format of the
thread identifier depends on the target. The ::regs and ::fpregs dcmds
can be used to examine the register set of the representative thread, or
of another thread if its register set is currently available. In
addition, the register set of the representative thread is exported as a
set of named variables. The user can modify the value of one or more
registers by applying the > dcmd to the corresponding named variable.


The mdb kernel target exports the virtual address of the corresponding
internal thread structure as the identifier for a given thread. The
Modular Debugger Guide provides more information on debugging support for
threads in the kernel. The mdb process target provides proper support for
examination of multi-threaded user processes that use the native lwp_*
interfaces, /usr/lib/libthread.so or /usr/lib/lwp/libthread.so. When
debugging a live user process, mdb detects if a single threaded process
dlopens or closes libthread and automatically adjusts its view of the
threading model on-the-fly. The process target thread identifiers
corresponds to either the lwpid_t, thread_t, or pthread_t of the
representative, depending on the threading model used by the application.


If mdb is debugging a user process target and the target makes use of
compiler-supported thread-local storage, mdb automatically evaluates
symbol names referring to thread-local storage to the address of the
storage corresponding to the current representative thread. The ::tls
built-in dcmd can be used to display the value of the symbol for threads
other than the representative thread.

Built-in dcmds
mdb provides a set of built-in dcmds that are always defined. Some of
these dcmds are only applicable 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 can 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 underneath the ::identifier form. The built-in dcmds are:

> variable-name
>/modifier/variable-name

Assign the value of dot to the specified named variable. Some
variables are read-only and can not 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. Instead, they
fetch the specified number of low-order bytes (on little-endian
architectures) or high-order bytes (big-endian architectures).
Modifiers are provided for backwards compatibility; the mdb
*/modifier/ and %/modifier/ syntax should be used instead.


$< macro-name

Read and execute commands from the specified macro file. The filename
can be given as an absolute or relative path. If the filename 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.


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

Re-open 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 pathname 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.


[address] ::bp [-/-dDesT] [-c cmd] [-n count] sym ...
address :b [cmd ...]

Set a breakpoint at the specified locations. The ::bp dcmd sets a
breakpoint at each address or symbol specified, including an optional
address specified by an explicit expression preceding the dcmd, and
each string or immediate value following the dcmd. The arguments can
either be symbol names or immediate values denoting a particular
virtual address of interest. If a symbol name is specified, it can
refer to a symbol that cannot yet be evaluated in the target process.
That is, it can consist of an object name and function name in a load
object that has not yet been opened. In this case, the breakpoint is
deferred and is not active in the target until an object matching the
given name is loaded. The breakpoint is automatically enabled when
the load object is opened. Breakpoints on symbols defined in a shared
library should always be set using a symbol name and not using an
address expression, as the address can refer to the corresponding
Procedure Linkage Table (PLT) entry instead of the actual symbol
definition. Breakpoints set on PLT entries can be overwritten by the
run-time link-editor when the PLT entry is subsequently resolved to
the actual symbol definition. The -d, -D, -e, -s, -t, -T, -c, and -n
options have the same meaning as they do for the ::evset dcmd, as
described below. If the :b form of the dcmd is used, a breakpoint is
only set at the virtual address specified by the expression preceding
the dcmd. The arguments following the :b dcmd are concatenated
together to form the callback string. If this string contains meta-
characters, it must be quoted.


::cat filename ...

Concatenate and display files. Each filename can be specified as a
relative or absolute pathname. The file contents are printed to
standard output, but are not passed to 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.


::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 simply
waits for the target to terminate or stop after an event of interest.
If an optional signal name or number (see signal.h(3HEAD)) is
specified as an argument, 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 user-defined interrupt character (usually ^C). This
SIGINT signal is automatically cleared and is not observed by the
target the next time it is continued. 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 only valid 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. Once
the switch occurs, the new target interposes its dcmds at the global
level: thus the / dcmd now formats and displays data from the virtual
address space of the user process, the ::mappings dcmd displays 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 ] ::delete [ id | all ]
[ address ] :d [ id | all ]

Delete the event specifiers with the given id number. The id number
argument is interpreted in decimal by default. If an optional address
is specified preceding the dcmd, all event specifiers that are
associated with the given virtual address are deleted (for example,
all breakpoints or watchpoints affecting that address). If the
special argument "all" is given, all event specifiers are deleted,
except those that are marked sticky (T flag). The ::events dcmd
displays the current list of event specifiers.


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


::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 ]
#sp;#sp;[ -g bytes ] [ -w paragraphs ]

Print a hexadecimal and ASCII memory dump of the 16-byte aligned
region of 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
Adjusts for endian-ness. The -e option assumes
4-byte words. The -g option can be used to change
the default word size.


-f
Reads 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 bytes
Displays 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
Interprets address as a physical address location in
the target's address space instead of a virtual
address.


-q
Does not print an ASCII decoding of the data.


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


-s
Elides repeated lines.


-t
Only reads from and displays the contents of the
specified addresses, instead of reading and printing
entire lines.


-u
Unaligns output instead of aligning the output at a
paragraph boundary.


-w paragraphs
Displays paragraphs at 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 $[ ] is 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 whitespace, it should be enclosed
in double or single quotes.


::events [ -av ]
$b [ -av ]

Display the list of software event specifiers. Each event specifier
is assigned a unique ID number that can be used to delete or modify
it at a later time. The debugger can also have its own internal
events enabled for tracing. These events are only be displayed if
the -a option is present. If the -v option is present, a more verbose
display, including the reason for any specifier inactivity, are
shown. Here is some sample output:

> ::events
ID S TA HT LM Description Action
----- - -- -- -- -------------------------------- ------
[ 1 ] - T 1 0 stop on SIGINT -
[ 2 ] - T 0 0 stop on SIGQUIT -
[ 3 ] - T 0 0 stop on SIGILL -
...
[ 11] - T 0 0 stop on SIGXCPU -
[ 12] - T 0 0 stop on SIGXFSZ -
[ 13] - 2 0 stop at libc`printf ::echo printf
>


The following table explains the meaning of each column. A summary of
this information is available using ::help events.

ID
The event specifier identifier. The identifier is
shown in square brackets [ ] if the specifier is
enabled, in parentheses ( ) if the specifier is
disabled, or in angle brackets < > if the target
program is currently stopped on an event that matches
the given specifier.


S
The event specifier state. The state is one of the
following symbols:

-
The event specifier is idle. When no target
program is running, all specifiers are idle. When
the target program is running, a specifier can be
idle if it cannot be evaluated (for example, a
deferred breakpoint in a shared object that is
not yet loaded).


+
The event specifier is active. When the target is
continued, events of this type is detected by the
debugger.


*
The event specifier is armed. This state means
that the target is currently running with
instrumentation for this type of event. This
state is only visible if the debugger is attached
to a running program with the -o nostop option.


!
The event specifier was not armed due to an
operating system error. The ::events -v option
can be used to display more information about the
reason the instrumentation failed.


TA
The Temporary, Sticky, and Automatic event specifier
properties. One or more of the following symbols can
be shown:

t
The event specifier is temporary, and is deleted
the next time the target stops, regardless of
whether it is matched.


T
The event specifier is sticky, and is not be
deleted by ::delete all or :z. The specifier can
be deleted by explicitly specifying its id number
to ::delete.


d
The event specifier is automatically disabled
when the hit count is equal to the hit limit.


D
The event specifier is automatically deleted when
the hit count is equal to the hit limit.


s
The target automatically stops when the hit count
is equal to the hit limit.


HT
The current hit count. This column displays the number
of times the corresponding software event has occurred
in the target since the creation of this event
specifier.


LM
The current hit limit. This column displays the limit
on the hit count at which the auto-disable, auto-
delete, or auto-stop behavior takes effect. These
behaviors can be configured using the ::evset dcmd,
described below.


Description
A description of the type of software event that is
matched by the given specifier.


Action
The callback string to execute when the corresponding
software event occurs. This callback is executed as
if it had been typed at the command prompt.


[id] ::evset [-/-dDestT] [-c cmd] [-n count] id ...

Modify the properties of one or more software event specifiers. The
properties are set for each specifier identified by the optional
expression preceding the dcmd and an optional list of arguments
following the dcmd. The argument list is interpreted as a list of
decimal integers, unless an explicit radix is specified. The ::evset
dcmd recognizes the following options:

-d
Disables the event specifier when the hit count reaches the hit
limit. If the -d form of the option is given, this behavior is
disabled. Once an event specifier is disabled, the debugger
removes any corresponding instrumentation and ignores the
corresponding software events until the specifier is
subsequently re-enabled. If the -n option is not present, the
specifier is disabled immediately.


-D
Deletes the event specifier when the hit count reaches the hit
limit. If the -D form of the option is given, this behavior is
disabled. The -D option takes precedence over the -d option.
The hit limit can be configured using the -n option.


-e
Enables the event specifier. If the -e form of the option is
given, the specifier is disabled.


-s
Stops the target program when the hit count reaches the hit
limit. If the -s form of the option is given, this behavior is
disabled. The -s behavior tells the debugger to act as if the
::cont were issued following each execution of the specifier's
callback, except for the Nth execution, where N is the current
value of the specifier's hit limit. The -s option takes
precedence over both the -D option and the -d option.


-t
Marks the event specifier as temporary. Temporary specifiers
are automatically deleted the next time the target stops,
regardless of whether it stopped as the result of a software
event corresponding to the given specifier. If the -t form of
the option is given, the temporary marker is removed. The -t
option takes precedence over the -T option.


-T
Marks the event specifier as sticky. Sticky specifiers are not
deleted by ::delete all or :z. They can be deleted by
specifying the corresponding specifier ID as an explicit
argument to ::delete. If the -T form of the option is given,
the sticky property is removed. The default set of event
specifiers are all initially marked sticky.


-c
Executes the specified cmd string each time the corresponding
software event occurs in the target program. The current
callback string can be displayed using ::events.


-n
Sets the current value of the hit limit to count. If no hit
limit is currently set and the -n option does not accompany -s
or D, the hit limit is set to one.

A summary of this information is available using ::help evset.


::files
$f

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


[flt] ::fltbp [-/-dDestT] [-c cmd] [-n count] flt ...

Trace the specified machine faults. The faults are identified using
an optional fault number preceding the dcmd, or a list of fault names
or numbers (see <sys/fault.h>) following the dcmd. The -d, -D, -e,
-s, -t, -T, -c, and -n options have the same meaning as they do for
the ::evset dcmd.


[ thread ] ::fpregs
[ 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, above.


::formats

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


::grep command

Evaluate the specified command string, and then print the old value
of dot if the new value of dot is non-zero. If the command contains
whitespace 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.


signal :i

If the target is a live user process, ignore the specified signal and
allow it to be delivered transparently to the target. All event
specifiers that are tracing delivery of the specified signal is
deleted from the list of traced events. By default, the set of
ignored signals is initialized to the complement of the set of
signals that cause a process to dump core by default (see
signal.h(3HEAD)), except for SIGINT, which is traced by default.


$i

Display the list of signals that are ignored by the debugger and that
is handled directly by the target. More information on traced signals
can be obtained using the ::events dcmd.


::kill
:k

Forcibly terminate the target if it is a live user process. The
target is also forcibly terminated when the debugger exits if it was
created by the debugger using ::run.


$l

Print the LWPID of the representative thread, if the target is a user
process.


$L

Print the LWPIDs of each LWP in the target, if the target is a user
process.


[ 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 continues 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 is assigned the value
returned at each step of the walk when mdb invokes the next stage of
a pipeline. The ::list dcmd can only be used with objects that
contain symbolic debugging information designed for use with mdb.
Refer to NOTES, Symbolic Debugging Information, below for more
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 can not be loaded; the existing module
must be unloaded first. If the -s option is present, mdb remains
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 filename is given. The -d option disables
logging. If the $> dcmd is used, logging is enabled if a filename
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, and then print the new value of dot.
If the command contains whitespace 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 only shows the mapping that
contains the given address. If a string name argument is given, mdb
only shows the mapping matching that description.


::next [ SIG ]
:e [ SIG ]

Step the target program one instruction, but step over subroutine
calls. If an optional signal name or number (see signal.h(3HEAD)) is
specified as an argument, the signal is immediately delivered to the
target as part of resuming its execution. If no target program is
currently running, ::next starts a new program running as if by ::run
and stop at the first instruction.


[ address ] ::nm [ -DPdghnopuvx ] [ -t types ]
#sp;#sp;[ -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 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.


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


-u
Prints only undefined symbols.


-v
Sorts symbols by value.


-x
Prints value and size fields in
hexadecimal.


-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


-f format[,format ... ]
Prints only the specified symbol
information. The valid format argument
strings are:

ndx
symbol table index


val
symbol value


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


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 under Symbol
Name Resolution above. The ::nmadd dcmd also recognizes the following
options:

-e
Sets the size of the symbol to end - value.


-f
Sets the type of the symbol to STT_FUNC.


-o
Sets the type of the symbol to STT_OBJECT.


-s
Sets 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. The -v option displays
the version of each load object. Version information is not available
for all load objects. Load objects without version information is
listed as having a version of "Unknown" in the output for the -v
option.


::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 can
be printed in bits. The output is always suffixed with the
appropriate units for clarity. The type name can use the backquote
(`) scoping operator described under Symbol Name Resolution, above.
The ::offsetof dcmd can only be used with objects that contain
symbolic debugging information designed for use with mdb. Refer to
NOTES, Symbolic Debugging Information, below for more information.


address ::print [ -aCdiLptx ] [ -c lim ]
#sp;#sp;[ -l lim ] [ type [ member ... ] ]

Print the data structure at the specified virtual address using the
given type information. The type parameter can 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
can use the backquote (`) scoping operator described under Symbol
Name Resolution, above. 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. If the type argument is specified, it can be followed
by an optional list of member expressions, in which case only those
members and submembers of the specified type are displayed. If type
contains other structured types, each member string can refer to a
sub-structure element by forming a list of member names separated by
period ('.') delimiters. The ::print dcmd can only be used with
objects that contain symbolic debugging information designed for use
with mdb. Refer to NOTES, Symbolic Debugging Information, below for
more information. 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 -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 is 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 is 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 under OPTIONS.

If the -i option is specified, the address value is interpreted as an
immediate value to be printed. You must give a type with which to
interpret the value. If the type is smaller than 64 bits, the
immediate value is interpreted as if it were the size of the type.
The -i option cannot be used in conjunction with the -p option. If
the -a option is given, the addresses shown are byte offsets starting
at zero.


::quit
$q

Quit the debugger.


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


::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) (see proc(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.


::run [ args ... ]
:r [ args ... ]

Start a new target program running with the specified arguments and
attach to it. The arguments are not interpreted by the shell. If the
debugger is already examining a live running program, it first
detaches from this program as if by ::release.


::set [ -wF ] [ -/-o option ] [ -s distance ] [ -I path ]
#sp;#sp;[ -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 takes 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
Sets the default path for locating macro files. The path
argument can contain any of the special tokens described for
the -I command-line option under OPTIONS.


-L
Sets the default path for locating debugger modules. The path
argument can contain any of the special tokens described for
the -I command-line option under OPTIONS.


-o
Enables 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 under OPTIONS.


-P
Sets the command prompt to the specified prompt string.


-s
Sets the symbol matching distance to the specified distance.
Refer to the description of the -s command-line option under
OPTIONS for more information.


-w
Re-opens 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. With no
options specified, general system information is displayed. The -v
option displays version information for all load objects, whereas the
-p option displays the version information only for the load objects
that have been installed on the system as part of a patch. Version
information is not available for all load objects. Load objects
without version information is omitted from the output for the -p
option and is listed as having a version of "Unknown" in the output
for the -v option.


[signal] ::sigbp [-/-dDestT] [-c cmd] [-n count] SIG ...
[signal] :t [-/-dDestT] [-c cmd] [-n count] SIG ...

Trace delivery of the specified signals. The signals are identified
using an optional signal number preceding the dcmd, or a list of
signal names or numbers (see signal.h(3HEAD)) following the dcmd. The
-d, -D, -e, -s, -t, -T, -c, and -n options have the same meaning as
they do for the ::evset dcmd. Initially, the set of signals that
cause the process to dump core by default (see signal.h(3HEAD)) and
SIGINT are traced.


::sizeof type

Print the size of the specified type in bytes. The type parameter can
name a C struct, union, enum, fundamental integer type, or a pointer
to any of these types. The type name can use the backquote (`)
scoping operator described under Symbol Name Resolution, above. The
::sizeof dcmd can only be used with objects that contain symbolic
debugging information designed for use with mdb. Refer to NOTES,
Symbolic Debugging Information, below for more information.


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

Print a C stack backtrace. 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.


::status

Print a summary of information related to the current target.


::step [ over | out ] [ SIG ]
:s [ SIG ]
:u [ SIG ]

Step the target program one instruction. If an optional signal name
or number (see signal.h(3HEAD)) is specified as an argument, the
signal is immediately delivered to the target as part of resuming its
execution. If the optional "over" argument is specified, ::step steps
over subroutine calls. The ::step over argument is the same as the
::next dcmd. If the optional "out" argument is specified, the target
program continues until the representative thread returns from the
current function. If no target program is currently running, ::step
out starts a new program running as if by ::run and stop at the first
instruction. The :s dcmd is the same as ::step. The :u dcmd is the
same as ::step out.


[ syscall ] ::sysbp [ -/-dDestT ] [ -io ] [ -c cmd ]
#sp;#sp;[ -n count ] syscall...

Trace entry to or exit from the specified system calls. The system
calls are identified using an optional system call number preceding
the dcmd, or a list of system call names or numbers (see
<sys/syscall.h>) following the dcmd. If the -i option is specified
(the default), the event specifiers trigger on entry into the kernel
for each system call. If the -o option is specified, the event
specifiers trigger on exit out from the kernel. The -d, -D, -e, -s,
-t, -T, -c, and -n options have the same meaning as they do for the
::evset dcmd.


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, above. The symbol name can use any of the
scoping operators described under Symbol Name Resolution, above.


::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 can not be unloaded. Modules
that are busy (that is, provide dcmds that are currently executing)
can not be unloaded.


::unset variable-name ...

Unset (remove) the specified variable(s) from the list of defined
variables. Some variables exported by mdb are marked as persistent,
and can not 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 and
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 prints 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 under dcmd and Walker Name
Resolution, above. If the optional variable-name is specified, the
specified variable is 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 the section
on dcmd and Walker Name Resolution above 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.


addr [ ,len ]::wp [ -/-dDestT ] [ -rwx ] [ -c cmd ]
#sp;#sp; [ -n count ]
addr [ ,len ] :a [ cmd ... ]
addr [ ,len ] :p [ cmd ... ]
addr [ ,len ] :w [ cmd ... ]

Set a watchpoint at the specified address. The length in bytes of the
watched region can be set by specifying an optional repeat count
preceding the dcmd. If no length is explicitly set, the default is
one byte. The ::wp dcmd allows the watchpoint to be configured to
trigger on any combination of read (-r option), write (-w option), or
execute (-x option) access. The -d, -D, -e, -s, -t, -T, -c, and -n
options have the same meaning as they do for the ::evset dcmd. The :a
dcmd sets a read access watchpoint at the specified address. The :p
dcmd sets an execute access watchpoint at the specified address. The
:w dcmd sets a write access watchpoint at the specified address. The
arguments following the :a, :p, and :w dcmds are concatenated
together to form the callback string. If this string contains meta-
characters, it must be quoted.


::xdata

List the external data buffers exported by the current target.
External data buffers represent information associated with the
target that can not 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 the
Modular Debugger Guide.


:z

Delete all event specifiers from the list of traced software events.
Event specifiers can also be deleted using ::delete.


OPTIONS


The following options are supported:

-A
Disables automatic loading of mdb modules. By default, mdb
attempts to load debugger modules corresponding to the
active shared libraries in a user process or core file, or
to the loaded kernel modules in the live operating system
or an operating system crash dump.


-b VM
Attaches to and stops the specified bhyve VM.


-e expr
Causes mdb to ignore standard input and instead evaluate
the mdb expression expr. Upon completing evaluation, mdb
terminates and returns a status code. A non-zero return
code from mdb indicates that either mdb or the evaluation
of expr failed.


-f
Forces raw file debugging mode. By default, mdb attempts
to infer whether the object and core file operands refer
to a user executable and core dump or to a pair of
operating system crash dump files. If the file type cannot
be inferred, the debugger defaults to examining the files
as plain binary data. The -f option forces mdb to
interpret the arguments as a set of raw files to examine.


-F
Forcibly takes over the specified user process, if
necessary. By default, mdb refuses to attach to a user
process that is already under the control of another
debugging tool, such as truss(1). With the -F option, mdb
attaches to these processes anyway. This can produce
unexpected interactions between mdb and the other tools
attempting to control the process.


-I path
Sets default path for locating macro files. Macro files
are read using the $< or $<< dcmds. The path is a sequence
of directory names delimited by colon (:) characters. The
-I include path and -L library path (see below) can also
contain any of the following tokens:

%i
Expands to the current instruction set architecture
(ISA) name ('sparc', 'sparcv9', or 'i386').


%o
Expands to the old value of the path being modified.
This is useful for appending or prepending
directories to an existing path.


%p
Expands to the current platform string (either uname
-i or the platform string stored in the process core
file or crash dump).


%r
Expands to the pathname of the root directory. An
alternate root directory can be specified using the
-R option. If no -R option is present, the root
directory is derived dynamically from the path to
the mdb executable itself. For example, if /bin/mdb
is executed, the root directory is /. If
/net/hostname/bin/mdb were executed, the root
directory would be derived as /net/hostname.


%t
Expands to the name of the current target. This is
either the literal string 'proc' (a user process or
user process core file), 'kvm' (a kernel crash dump
or the live operating system), or 'raw' (a raw
file).

The default include path for 32-bit mdb is:

%r/usr/platform/%p/lib/adb:%r/usr/lib/adb


The default include path for 64-bit mdb is:

%r/usr/platform/%p/lib/adb/%i:%r/usr/lib/adb/%i


-k
Forces kernel debugging mode. By default, mdb attempts to
infer whether the object and core file operands refer to a
user executable and core dump, or to a pair of operating
system crash dump files. The -k option forces mdb to
assume these files are operating system crash dump files.
If no object or core operand is specified, but the -k
option is specified, mdb defaults to an object file of
/dev/ksyms and a core file of /dev/kmem. Read access to
/dev/kmem is restricted to group sys. Write access
requires ALL privileges.


-K
Load kmdb, stop the live running operating system kernel,
and proceed to the kmdb debugger prompt. This option
should only be used on the system console, as the
subsequent kmdb prompt appears on the system console.


-L path
Sets default path for locating debugger modules. Modules
are loaded automatically on startup or using the ::load
dcmd. The path is a sequence of directory names delimited
by colon (:) characters. The -L library path can also
contain any of the tokens shown for -I above.


-m
Disables demand-loading of kernel module symbols. By
default, mdb processes the list of loaded kernel modules
and performs demand loading of per-module symbol tables.
If the -m option is specified, mdb does not attempt to
process the kernel module list or provide per-module
symbol tables. As a result, mdb modules corresponding to
active kernel modules are not loaded on startup.


-M
Preloads all kernel module symbols. By default, mdb
performs demand-loading for kernel module symbols: the
complete symbol table for a module is read when an address
is that module's text or data section is referenced. With
the -M option, mdb loads the complete symbol table of all
kernel modules during startup.


-o option
Enables the specified debugger option. If the -o form of
the option is used, the specified option is disabled.
Unless noted below, each option is off by default. mdb
recognizes the following option arguments:

adb
Enables stricter adb(1)
compatibility. The prompt is set
to the empty string and many mdb
features, such as the output
pager, is disabled.


array_mem_limit=limit
Sets the default limit on the
number of array members that
::print displays. If limit is the
special token none, all array
members are displayed by default.


array_str_limit=limit
Sets the default limit on the
number of characters that ::print
attempts to display as an ASCII
string when printing a char
array. If limit is the special
token none, the entire char array
is displayed as a string by
default.


autowrap
Forces output to be autowrapped
at the terminal width. When this
option is enabled, mdb will
autowrap output, making some
attempt to inject newlines at
word boundaries. This option is
disabled by default.


follow_exec_mode=mode
Sets the debugger behavior for
following an exec(2) system call.
The mode should be one of the
following named constants:

ask
If stdout is a terminal
device, the debugger
stops after the exec(2)
system call has
returned and then
prompts the user to
decide whether to
follow the exec or
stop. If stdout is not
a terminal device, the
ask mode defaults to
stop.


follow
The debugger follows
the exec by
automatically
continuing the target
process and resetting
all of its mappings and
symbol tables based on
the new executable. The
follow behavior is
discussed in more
detail under NOTES,
Interaction with Exec,
below.


stop
The debugger stops
following return from
the exec system call.
The stop behavior is
discussed in more
detail under NOTES,
Interaction with Exec,
below.


follow_fork_mode=mode
Sets the debugger behavior for
following a fork(2), fork1(2), or
vfork(2) system call. The mode
should be one of the following
named constants:

ask
If stdout is a terminal
device, the debugger
stops after the fork(2)
system call has
returned and then
prompts the user to
decide whether to
follow the parent or
child. If stdout is not
a terminal device, the
ask mode defaults to
parent.


parent
The debugger follows
the parent process, and
detaches from the child
process and sets it
running.


child
The debugger follows
the child process, and
detaches from the
parent process and sets
it running.


ignoreeof
The debugger does not exit when
an EOF sequence (^D) is entered
at the terminal. The ::quit dcmd
must be used to quit.


nostop
Does not stop a user process when
attaching to it when the -p
option is specified or when the
::attach or :A dcmds are applied.
The nostop behavior is described
in more detail under NOTES,
Process Attach and Release,
below.


pager
Enables the output pager
(default).


repeatlast
If a NEWLINE is entered as the
complete command at the terminal,
mdb repeats the previous command
with the current value of dot.
This option is implied by -o adb.


showlmid
mdb provides support for symbol
naming and identification in user
applications that make use of
link maps other than LM_ID_BASE
and LM_ID_LDSO, as described in
Symbol Name Resolution, above.
Symbols on link maps other than
LM_ID_BASE or LM_ID_LDSO is shown
as LMlmid`library`symbol, where
lmid is the link-map ID in the
default output radix (16). The
user can optionally configure mdb
to show the link-map ID scope of
all symbols and objects,
including those associated with
LM_ID_BASE and LM_ID_LDSO, by
enabling the showlmid option.
Built-in dcmds that deal with
object file names displays link-
map IDs according to the value of
showlmid above, including ::nm,
::mappings, $m, and ::objects.


-p pid
Attaches to and stops the specified process-id. mdb uses
the /proc/pid/object/a.out file as the executable file
pathname.


-P prompt
Sets the command prompt. The default prompt is '> '.


-R root
Sets root directory for pathname expansion. By default,
the root directory is derived from the pathname of the mdb
executable itself. The root directory is substituted in
place of the %r token during pathname expansion.


-s distance
Sets the symbol matching distance for address-to-symbol-
name conversions to the specified distance. By default,
mdb sets the distance to zero, which enables a smart-
matching mode. Each ELF symbol table entry includes a
value V and size S, representing the size of the function
or data object in bytes. In smart mode, mdb matches an
address A with the given symbol if A is in the range [ V,
V + S ). If any non-zero distance is specified, the same
algorithm is used, but S in the expression above is always
the specified absolute distance and the symbol size is
ignored.


-S
Suppresses processing of the user's ~/.mdbrc file. By
default, mdb reads and processes the macro file .mdbrc if
one is present in the user's home directory, as defined by
$HOME. If the -S option is present, this file is not read.


-u
Forces user debugging mode. By default, mdb attempts to
infer whether the object and core file operands refer to a
user executable and core dump, or to a pair of operating
system crash dump files. The -u option forces mdb to
assume these files are not operating system crash dump
files.


-U
Unload kmdb if it is loaded. You should unload kmdb when
it is not in use to release the memory used by the kernel
debugger back to the free memory available to the
operating system.


-V version
Sets disassembler version. By default, mdb attempts to
infer the appropriate disassembler version for the debug
target. The disassembler can be set explicitly using the
-V option. The ::disasms dcmd lists the available
disassembler versions.


-w
Opens the specified object and core files for writing.


-W
Permit access to memory addresses that are mapped to I/O
devices. By default, mdb does not allow such access
because many devices do not provide hardware protection
against invalid software manipulations. Use this option
only when debugging device drivers and with caution.


-y
Sends explicit terminal initialization sequences for tty
mode. Some legacy terminal emulators require explicit
initialization sequences to switch into a tty mode.
Without this initialization sequence, terminal features
such as standout mode will not be available to mdb.


OPERANDS


The following operands are supported:

object
Specifies an ELF format object file to examine. mdb provides
the ability to examine and edit ELF format executables
(ET_EXEC), ELF dynamic library files (ET_DYN), ELF relocatable
object files (ET_REL), and operating system unix.X symbol table
files.


core
Specifies an ELF process core file (ET_CORE), or an operating
system crash dump vmcore.X file. If an ELF core file operand is
provided without a corresponding object file and the core file
settings have been modified to store less than the default,
some information may be unavailable.


suffix
Specifies the numerical suffix representing a pair of operating
system crash dump files. For example, if the suffix is '3', mdb
infers that it should examine the files 'unix.3' and
'vmcore.3'. The string of digits are not interpreted as a
suffix if an actual file of the same name is present in the
current directory.


USAGE


mdb processes all input files (including scripts, object files, core
files, and raw data files) in a large file aware fashion. See
largefile(7) for more information about the processing of large files,
which are files greater than or equal to 2 Gbytes (2^31 bytes).

EXIT STATUS


The following exit values are returned:

0
Debugger completed execution successfully.


1
A fatal error occurred.


2
Invalid command line options were specified.


ENVIRONMENT VARIABLES


HISTSIZE
This variable is used to determine the maximum length of the
command history list. If this variable is not present, the
default length is 128.


HOME
This variable is used to determine the pathname of the user's
home directory, where a .mdbrc file can reside. If this
variable is not present, no .mdbrc processing occurs.


SHELL
This variable is used to determine the pathname of the shell
used to process shell escapes requested using the ! meta-
character. If this variable is not present, /bin/sh is used.


FILES


$HOME/.mdbrc

User mdb initialization file. The .mdbrc file, if present, is
processed after the debug target has been initialized, but before
module auto-loading is performed or any commands have been read from
standard input.


/dev/kmem

Kernel virtual memory image device. This device special file is used
as the core file when examining the live operating system.


/dev/ksyms

Kernel symbol table device. This device special file is used as the
object file when examining the live operating system.


/proc/pid/*

Process information files that are read when examining and
controlling user processes.


/usr/lib/adb
/usr/platform/platform-name/lib/adb

Default directories for macro files that are read with the $< and $<<
dcmds. platform-name is the name of the platform, derived either from
information in a core file or crash dump, or from the current machine
as if by uname -i (see uname(1)).


/usr/lib/mdb
/usr/platform/platform-name/lib/mdb

Default directories for debugger modules that are loaded using the
::load dcmd. platform-name is the name of the platform, derived
either from information in a core file or crash dump, or from the
current machine as if by uname -i (see uname(1)).


ATTRIBUTES


See attributes(7) for descriptions of the following attributes:


+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|Interface Stability | Evolving |
+--------------------+-----------------+

SEE ALSO


adb(1), gcore(1), pgrep(1), proc(1), ps(1), stty(1), truss(1), uname(1),
_lwp_self(2), exec(2), fork(2), pipe(2), vfork(2), dlopen(3C),
signal(3C), thr_self(3C), elf(3ELF), signal.h(3HEAD), libc_db(3LIB),
libkvm(3LIB), libthread(3LIB), ksyms(4D), mem(4D), core(5), proc(5),
attributes(7), largefile(7), threads(7), coreadm(8), dumpadm(8),
savecore(8)


Linker and Libraries Guide


Modular Debugger Guide:


https://illumos.org/books/mdb/

WARNINGS


Use of the Error Recovery Mechanism


The debugger and its dmods execute in the same address space, and thus it
is quite possible that a buggy dmod can cause mdb to dump core or
otherwise misbehave. The mdb resume capability, described above under
Signal Handling, provides a limited recovery mechanism for these
situations. However, it is not possible for mdb to know definitively
whether the dmod in question has corrupted only its own state, or the
debugger's global state. Therefore a resume operation cannot be
guaranteed to be safe, or to prevent a subsequent crash of the debugger.
The safest course of action following a resume is to save any important
debug information, and then quit and restart the debugger.

Use of the Debugger to Modify the Live Operating System


The use of the debugger to modify (that is, write to) the address space
of live running operating system is extremely dangerous, and can result
in a system panic in the event the user damages a kernel data structure.

NOTES


Limitations on Examining Process Core Files


By default, text sections and read-only data are included in core files.
While ill-advised, users can configure their processes to exclude that
information from core files using coreadm(8). Such core files will be
missing the information necessary to interpret them; to debug them using
mdb, the object file shold be specified in addition to the core file.
The instruction set architecture of the machine running mdb must match
the instruction set architecture of the machine that generated the core
file.

Limitations on Examining Crash Dump Files


If a crash dump from one operating system release is examined using the
dmods from a different operating system release, changes in the kernel
implementation can prevent some dcmds or walkers from working properly.
mdb issues a warning message if it detects this condition. The
instruction set architecture of the machine running mdb must match the
instruction set architecture of the machine that generated the crash
dump.

Relationship Between 32-bit and 64-bit Debugger
mdb provides support for debugging both 32-bit and 64-bit programs. Once
it has examined the target and determined its data model, mdb
automatically re-executes the mdb binary that has the same data model as
the target, if necessary. This approach simplifies the task of writing
debugger modules, because the modules that are loaded use the same data
model as the primary target. Only the 64-bit debugger can be used to
debug 64-bit target programs. The 64-bit debugger can only be used on a
system that is running the 64-bit operating environment.


The debugger can also need to re-execute itself when debugging a 32-bit
process that execs a 64-bit process, or vice-versa. The handling of this
situation is discussed in more detail under Interaction with Exec, below.

Interaction with Exec


When a controlled process performs a successful exec(2), the behavior of
the debugger is controlled by the ::set -o follow_exec_mode option, as
described above. If the debugger and victim process have the same data
model, then the "stop" and "follow" modes determine whether mdb
automatically continues the target or returns to the debugger prompt
following the exec. If the debugger and victim process have a different
data model, then the "follow" behavior causes mdb to automatically re-
exec the mdb binary with the appropriate data model and to re-attach to
the process, still stopped on return from the exec. Not all debugger
state is preserved across this re-exec.


If a 32-bit victim process execs a 64-bit program, then "stop" returns to
the command prompt, but the debugger is no longer able to examine the
process because it is now using the 64-bit data model. To resume
debugging, execute the ::release -a dcmd, quit mdb, and then execute mdb
-p pid to re-attach the 64-bit debugger to the process.


If a 64-bit victim process execs a 32-bit program, then "stop" returns to
the command prompt, but the debugger only provides limited capabilities
for examining the new process. All built-in dcmds work as advertised, but
loadable dcmds do not since they do not perform data model conversion of
structures. The user should release and re-attach the debugger to the
process as described above in order to restore full debugging
capabilities.

Interaction with Job Control


If the debugger is attached to a process that is stopped by job control
(that is, it stopped in response to SIGTSTP, SIGTTIN, or SIGTTOU), the
process can not be able to be set running again when it is continued by a
continue dcmd. If the victim process is a member of the same session
(that is, it shares the same controlling terminal as mdb), mdb attempts
to bring the associated process group to the foreground and to continue
the process with SIGCONT to resume it from job control stop. When mdb is
detached from such a process, it restores the process group to the
background before exiting. If the victim process is not a member of the
same session, mdb cannot safely bring the process group to the
foreground, so it continues the process with respect to the debugger, but
the process remains stopped by job control. mdb prints a warning in this
case, and the user must issue an "fg" command from the appropriate shell
in order to resume the process.

Process Attach and Release


When mdb attaches to a running process, the process is stopped and
remains stopped until one of the continue dcmds is applied, or the
debugger quits. If the -o nostop option is enabled prior to attaching the
debugger to a process with -p, or prior to issuing an ::attach or :A
command, mdb attaches to the process but does not stop it. While the
process is still running, it can be inspected as usual (albeit with
inconsistent results) and breakpoints or other tracing flags might be
enabled. If the :c or ::cont dcmds are executed while the process is
running, the debugger waits for the process to stop. If no traced
software events occur, the user can send an interrupt (^C) after :c or
::cont to force the process to stop and return control to the debugger.


mdb releases the current running process (if any) when the :R, ::release,
:r, ::run, $q, or ::quit dcmds are executed, or when the debugger
terminates as the result of an EOF or signal. If the process was
originally created by the debugger using :r or ::run, it is forcibly
terminated as if by SIGKILL when it is released. If the process was
already running prior to attaching mdb to it, it is set running again
when it is released. A process can be released and left stopped and
abandoned using the ::release -a option.

Symbolic Debugging Information


The ::list, ::offsetof, ::print, and ::sizeof dcmds require that one or
more load objects contain compressed symbolic debugging information
suitable for use with mdb. This information is currently only available
for certain kernel modules.

Developer Information


The Modular Debugger Guide provides a more detailed description of mdb
features, as well as information for debugger module developers.


The header file <sys/mdb_modapi.h> contains prototypes for the functions
in the MDB Module API, and distributions may provide source code for an
example module in the directory /usr/demo/mdb.

February 21, 2023 MDB(1)