svcadm(8)을 검색하려면 섹션에서 8 을 선택하고, 맨 페이지 이름에 svcadm을 입력하고 검색을 누른다.
mdb(1)
mdb(1) User Commands mdb(1)
NAME
mdb - modular debugger
SYNOPSIS
mdb [-fkmuwyAFMS][-a path] [±o option] [-p pid][-s distance]
[-I path] [-L path] [-P prompt] [-R root]
[-V dis-version] [object [core...] | core... | suffix | latest ]
mdb -K [-F] --stop-entire-system
mdb -K [-F] --stop-entire-cluster-node
mdb -K [-F] --load-debugger
mdb -k [-w --unsafe-write-access] [--unsafe-io-access]
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 manual, Oracle So‐
laris 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 pro‐
grammers 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 cur‐
rently provides support for the following types of targets: user
processes, user process core files, 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 exam‐
ined using the debugger commands described below.
A debugger command, or dcmd (pronounced dee-command) in mdb terminol‐
ogy, 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 Oracle Solaris Modular De‐
bugger Guide or you can write simple dcmds using the ::alias dcmd.
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 primi‐
tive 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 initial‐
ization, 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 de‐
bugging the Solaris kernel. The Oracle Solaris 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 the Solaris in‐
stallation includes a set of macro files for debugging the Solaris ker‐
nel 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 sepa‐
rated by one or more non-quoted metacharacters. Some of the metacharac‐
ters only function as delimiters in certain contexts, as described be‐
low. An identifier is a sequence of letters, digits, underscores, peri‐
ods, 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
The 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 success‐
ful, 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. The output of each dcmd 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 redirect the output
to the operating system. If ! is followed by > or >> the rest of
the line is used as a file name, opened, and the output appended to
that file. If there is just one > the file is truncated before be‐
ing written to. Otherwise open a pipe(2) and send the standard out‐
put 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 expres‐
sion 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 ex‐
pression. 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 char‐
acters 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 com‐
pute a numerical argument for a dcmd. An arithmetic expression can ap‐
pear in an argument list enclosed in square brackets preceded by a dol‐
lar sign ($[ expression ]), and is replaced by the value of the expres‐
sion.
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 hexa‐
decimal 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
1 if the variable named by identifier is defined otherwise 0.
identifier
The value of the symbol or constant 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 ob‐
ject 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.
%/<var/expression
The value from the object file location corresponding to virtual
address expression. The size of the value is read from the variable
var.
*expression
If the virtual address expression is in the type cache and the
type's size is less than pointer-size then the value of that size
quantity from expression in the target's virtual address space,
otherwise 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.
*/<var/expression
The value from the target's virtual address space corresponding to
virtual address expression. The size of the value is read from the
variable var.
*/type member/expression
The value of the data structure member from the target's virtual
address space corresponding to virtual address expression. The size
and offset that are read are specified by member.
For example to list all processes in a kernel, which do not have a
uid of zero:
> ::walk proc | ::grep '*/proc p_cred->cr_uid/.!=0'
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 un‐
less 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 recog‐
nizes 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 ! charac‐
ter takes precedence over all other metacharacters, except semicolon
(;) and NEWLINE. Once a shell escape is detected, the remaining charac‐
ters 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 ter‐
minal, 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, under‐
scores, or periods. A variable can be assigned a value using the > dcmd
or ::typeset dcmd, or ::save dcmd and its attributes can be manipulated
using the ::typeset dcmd.
If a variable created by using the ::typeset then by default the vari‐
able will be context local. Context local variables by default have the
value assigned when they were created by ::typeset otherwise they take
the value that was last assigned to them within the target's current
context (thread).
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).
Variables names with the string MDB_ and _MDB should not be used. These
are reserved for mdb.
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 speci‐
fier 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.
MDB_PID
The process id of the target process or core file.
MDB_CHILD_PID
The process id of the last child of the target process that was
created while mdb was attached.
MDB_THIS_EVENT
The event ID of the current event. This is only valid during an
event's callback.
MDB_SYSTOD
The number of seconds since the epoch on the system running mdb.
MDB_SYSTOD_NSEC
The number of nanoseconds since the epoch on the system running
mdb.
MDB_SYSHRTIME
The value of the high resolution timer as returned by gethrtime()
or clock_gettime(CLOCK_HIGHRES, ...) on the system running mdb.
MDB_STARTHRTIME
The value of the high resolution timer when the target was started.
MDB_TOD
The number of seconds since the epoch when the target stopped.
MDB_TOD_NSEC
The number of nanoseconds since the epoch when the target stopped.
MDB_STARTTOD
The number of seconds since the epoch when the target started.
MDB_STARTTOD_NSEC
The number of nanoseconds since the epoch when the target started.
MDB_SYSTIME
The number of nanoseconds the target has spent running in the sys‐
tem (kernel).
MDB_USERTIME
The number of nanoseconds the target has spent running in user
space.
MDB_CSYSTIME
The number of nanoseconds the target's children have spent running
in the system (kernel).
MDB_USERTIME
The number of nanoseconds the target's children have spent running
in user space.
MDB_radix
The value of the current radix. Writing a value that is not a legal
radix to this variable results in an error.
MDB_radix_width
MDB_radix_width_alt
MDB_radix_width_<type>
MDB_radix_width_<type>_alt
The maximum width of the string required to display a value of var‐
ious types, in both normal an alternate form in the current radix.
The <type> can be one of short, int, long, llong, ushort, uint,
ulong, ullong. They can be used with the '*' field width specifier
for the ::printf command to correctly format in the current radix.
These variables are marked as hidden so are only visible to the
::vars command if the -a is used.
MDB_IMPORTING
Set to 1 when mdb is importing aliases from the alias path.
stack_bias
The stack bias for the current target.
MDB_LAST_EVENT
The id of the last software event to have been added to the target.
MDB_retaddr
The address to which the current function will return.
MDB_retbp
After an out breakpoint has been hit the address of function re‐
turned from.
MDB_retval
The value returned by the previous function. This is only valid im‐
mediately after a function returns.
In addition, the mdb kernel and process targets export the current val‐
ues of the representative thread's register set as named variables. The
names of these variables depend on the target's platform and instruc‐
tion 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 associ‐
ated 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 Solaris kernel). The target typ‐
ically 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; auto‐
matic 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 defini‐
tions are then used whenever mdb converts a symbolic name to an ad‐
dress, or an address to the nearest symbol.
In some circumstances (file scope declarations, capability symbols, ELF
filter symbols, ... ), a given name may match more than one symbol
within the target. In such cases, the mdb backquote (`) symbol name
scoping operator can be used to unambiguously specify a specific de‐
sired symbol. The user can specify the scope as one of: object`name,
object`file`name, or object`file`index`name. The object identifier
refers to the name of a load object. The file identifier refers to the
basename of the source file that defined the symbol. The index identi‐
fier is a unique number assigned by mdb when object and file are not
sufficient to uniquely identify a symbol. When mdb encounters an am‐
biguous name, it lists all the possibilities, using this symbol scoping
syntax. The user can then use that list to refine their request.
If the option symname_index is not set to off and a symbol name does
not uniquely identify a symbol, mdb will report the uniquely qualified
names and values of all the symbols that match, the user can then pick
the one they want. The user can choose to have mdb ignore modules when
checking for ambiguous symbol names by adding them to the search_de‐
fer_mods list.
When capability symbols are present, a reference to a generic capabil‐
ity symbol is ambiguous, as it can be a reference to the actual generic
function, or to any of the associated capability variants. For example:
bike> memcpy::dis
mdb: memcpy: not a unique symbol name
mdb: libc.so.1``memcpy : 0x7fe6efb410e0
mdb: libc.so.1`memcpy%avx2 : 0x7fe6efca9680
bike>
If given an unqualified capability symbol the ::bp dcmd will internally
set break points on all the symbols. For example:
bike> memcpy::bp
bike> <MDB_LAST_EVENT::events
ID S TAS HT LM Description Action
----- - --- -- -- ------------------------------------------------- ------
[ 13] - --- 0 0 stop at libc.so.1``memcpy, libc.so.1`_memcpy%avx2 -
bike>
For details of capability symbols see the Oracle Solaris 11.4 Linkers
and Libraries Guide.
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 exe‐
cutable 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 ex‐
ecutable.
The process target also accepts any of the four forms described above
preceded by an optional link-map id (lmid). The lmid prefix is speci‐
fied by an initial "LM" followed by the link-map id in hexadecimal fol‐
lowed 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 Oracle Solaris 11.4 Linkers and Libraries
Guide and dlopen(3C). Link-map identifiers are displayed when symbols
are printed according to the setting of the showlmid option, as de‐
scribed under OPTIONS.
In the case of a naming conflict between symbols and hexadecimal inte‐
ger 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 hexa‐
decimal (the default base), or to a global variable named f in the tar‐
get'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.
Constant Name Resolution
Modules can provide constants, similar to symbols but mdb never maps
from the address back to the name. These are searched after symbol
lookup has been attempted. As multiple modules can define different
constants with the same name, mdb uses the backquote (`) character as a
constant scoping operator to allow the programmer to obtain the value
of the desired constant as: module`CONSTANT.
dcmd, alias and Walker Name Resolution
As described earlier, each mdb dmod provides a set of dcmds and walk‐
ers. 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 al‐
lowed in the global namespace. Aliases are dcmds that are loaded into
the global namespace and always take precedence. In the case of a con‐
flict, 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 defini‐
tion of a dcmd or walker can be determined using the ::which dcmd, de‐
scribed below. The global definition list can be displayed using the
::which -v option or ::dcmds will display all the possible dcmds, in‐
cluding aliases and duplicates.
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 corre‐
sponding 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 associ‐
ated 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 sig‐
nals are generated synchronously by the debugger process itself and a
dcmd from an externally loaded dmod is currently executing, and stan‐
dard 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, de‐
scribed 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 or vi-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 uppercase. 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 fol‐
lowed by 'f' on keyboards that support a Meta key. A command line is
committed and executed using RETURN or NEWLINE. With emacs-style 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 en‐
tered, the next command backward in time is retrieved.
^R[string]
Search backward in the history for a previous command line contain‐
ing 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 us‐
ing 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 in‐
terprets 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 com‐
mand 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 consist‐
ing 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 tar‐
get. A repeat count is a positive integer preceding the format charac‐
ter 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 for‐
mats. The = dcmd is therefore useful for converting between bases
and performing arithmetic.
#
Display the human readable byte count (8 bytes).
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 un‐
der 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 num‐
ber 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:
tab(); lw(0.69i) lw(4.81i) +T{ increment dot by the count (variable
size) T} -T{ decrement dot by the count (variable size) T} Bhexadecimal
int (1 byte) CT{ character using C character notation (1 byte) T} Ddec‐
imal signed int (4 bytes) Edecimal unsigned long (8 bytes) Fdouble (8
bytes) Goctal unsigned long (8 bytes) Hswap bytes and shorts (4 bytes)
IT{ address and disassembled instruction (variable size) T} Jhexadeci‐
mal long (8 bytes) Khexadecimal uintptr_t (4 or 8 bytes) Nnewline Ooc‐
tal unsigned int (4 bytes) Psymbol (4 or 8 bytes) Qoctal signed int (4
bytes) Rbinary int (8 bytes) ST{ string using C string notation (vari‐
able size) T} Thorizontal tab Udecimal unsigned int (4 bytes) Vdecimal
unsigned int (1 byte) Wdefault radix unsigned int (4 bytes) Xhexadeci‐
mal int (4 bytes) Ydecoded time32_t (4 bytes) Zhexadecimal long (8
bytes) ^T{ decrement dot by increment * count (variable size) T} adot
as symbol+offset boctal unsigned int (1 byte) ccharacter (1 byte) ddec‐
imal signed short (2 bytes) edecimal signed long (8 bytes) ffloat (4
bytes) goctal signed long long (8 bytes) hswap bytes (2 bytes) idisas‐
sembled instruction (variable size) jT{ jazzed-up binary unsigned long
long (8 bytes) T} nnewline ooctal unsigned short (2 bytes) psymbol (4
or 8 bytes) qoctal signed short (2 bytes) rwhitespace sraw string
(variable size) thorizontal tab udecimal unsigned short (2 bytes) vdec‐
imal signed int (1 byte) wdefault radix unsigned short (2 bytes) xhexa‐
decimal short (2 bytes) ydecoded time64_t (8 bytes)
The /, \, and ? formatting dcmds can also be used to write to the tar‐
get's virtual address space, physical address space, or object file by
specifying one of the following modifiers as the first format charac‐
ter, and then specifying a list of words that are either immediate val‐
ues 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 par‐
ticular 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 ei‐
ther immediate values or expressions enclosed in square brackets pre‐
ceded by a dollar sign. If only a value is specified, mdb reads inte‐
gers of the appropriate size and stops at the address containing the
matching value. If a value V and mask M are specified, mdb reads inte‐
gers 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 up‐
dated 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:
tab(); lw(0.69i) lw(4.81i) lSearch for the specified 2-byte value.
LSearch for the specified 4-byte value. MSearch for the specified
8-byte value.
Notice that for both user and kernel targets, an address space is typi‐
cally 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 soft‐
ware events can be specified by the user. Each time a traced event oc‐
curs 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 run‐
ning, 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, in‐
cluding 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 call‐
backs and properties. The current list of traced events and the proper‐
ties 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 sup‐
ported 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 exe‐
cuted as if they had been typed at the command prompt. Before executing
each callback, the dot variable is set to the value of the representa‐
tive 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 con‐
tinue 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 de‐
termines 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 avail‐
able. In addition, the register set of the representative thread is ex‐
ported 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 Or‐
acle Solaris Modular Debugger Guide provides more information on debug‐
ging support for threads in the Solaris kernel. The mdb process target
provides proper support for examination of multi-threaded user
processes. When debugging a live user process, mdb automatically ad‐
justs 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.
Casting
When referencing structure members it is possible to cast the member to
be a different type. Unlike C casting, the cast comes after the member
being cast. So a structure:
struct bike {
char b_name[16];
void *b_data;
};
If b_data points to a structure of type "struct pearson" with member
p_custom the following can be used to directly access p_custom:
struct bike b_data(struct pearson *)->p_custom
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 indi‐
cating "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 equiv‐
alent, 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 vari‐
ables are read-only and can not be modified. If the > is followed
by a modifier character surrounded by / /, then the value is modi‐
fied 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 ar‐
chitectures) or high-order bytes (big-endian architectures). Modi‐
fiers are provided for backward compatibility; the mdb */modifier/
and %/modifier/ syntax should be used instead.
$< macro-name
Read and execute commands from the specified macro file. The file‐
name can be given as an absolute or relative path. If the 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 informa‐
tion. 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 derived from the current target followed by >. 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.
::alias [[{-A | -a | -e | -i | -l | -m | -r}]
[+/-o {forceflags | init_usage | verbose | noaddrin | readonly}]
[-D description | +D] [-U usage | +U] [-H help | +H]
[-E description example | +E] [+/-t template[+/-t template ... ]]
[-I init | +I][-F fini | +F] name [expansion ... ]]
::alias allows you to create or remove a shorthand term or shortcut
for an mdb expression, with different functionality. ::alias as‐
signs the mdb expression (expansion) to the alias. With no argu‐
ments, ::alias lists all the aliases that are currently defined.
With one argument, ::alias lists just that alias.
Aliases can take command line arguments and flags, which are de‐
fined via templates. These can then be used within the expansion
using shell-like expansions.
When creating an alias, the ::alias dcmd will attempt to generate
correct help, usage and descriptions of the alias based on the ex‐
pansion. You can override all of these options.
For example, the command:
::alias -a p "::print $*"
creates an alias "::p" for the ::print dcmd.
The ::alias dcmd takes the following options:
-a
Add the alias. If the alias already exists this will fail.
-A
Add the alias. If the alias already exists delete the existing
alias first.
-e
Export the alias as the series of mdb expressions that can be
used to reproduce the alias.
-i
Import the specified alias. The alias can be given as an ab‐
solute path to a file or as an alias. If alias is a simple
name, mdb searches for it in the alias path, with an added
.alias suffix. If no alias is given than all the aliases on the
current alias path are loaded.
-l
List the alias in a human readable form.
-m
Modify an existing alias
-r
Remove an existing alias
+/-o option
Set or unset the option. -o sets the value and +o unsets the
value
forceflags
Set or unset flag checking for this alias. By default,
aliases that have no flags will not consume flags and pass
them as positional parameters to the expansion. With flag
checking enabled, the alias will treat flags as a usage er‐
ror
init_usage
Set or unset checking of dot after any init expression is
run. If the value is not zero, return a usage message. See
the -I option below.
noaddrin
Set or unset noaddrin mode. When in noaddrin mode the ex‐
pansion is not passed any input that the alias is given.
readonly
Mark the alias readonly. Readonly aliases cannot be deleted
or modified, except to remove the readonly flag.
verbose
Set or unset verbose mode. In verbose mode expansions are
printed to the error file just before they are executed.
-D Description
Set the description for the alias as displayed by the ::dcmds
command.
+D
Unset the description for the alias as displayed by the ::dcmds
-E Description Example
Add an example to the help text for the alias as displayed by
the ::help. Examples are given as two strings, the description
which describes the example and then the example which is the
text of the example.
+E
Remove all the examples from the help for the alias as dis‐
played by the ::help
-H Help
Set the main help text for the alias as displayed by the
::help. Within the help text $0 will expand to the name of the
alias, $$ expands to $. ::help will always display any flag op‐
tions that you add via templates.
+H
Unset the help for the alias as displayed by the ::help
-U Usage
Set the usage string.
The first and last character of the usage string have special
meanings. If any of these are set they are not displayed but
instead control the runtime behaviour of the alias.
Begins with ':'
The alias requires an address.
Begins with '?'
The alias optionally takes an address.
Begins with '|'
The alias input must be from a pipe.
Begins with neither ':' nor '?' nor '|'
The alias does not take an address.
Ends with '|'
The alias supports output to a pipe.
Does not end with '|'
The alias does not support output to a pipe.
+U
Unset the usage string
-t template
Set the template. Templates allow you to set a shell-like vari‐
able within the mdb expression. Templates have the form:
[flag]:[help]:variable[=value]
flag
An optional single letter flag. This will become an option
to the alias. If there is no flag then variable will be set
globally prior to parsing any flags.
help
Any help text for the flag. This is displayed when ::help
is run for this alias.
variable[=value]
The variable to set. If no value is specified, and the flag
is specified, the command line flag will expect an argument
and variable will be set to that value.
If no value is specified, and the flag is not specified,
variable is set to a string that can be used as an mdb
variable that is guaranteed to not be in use. After the
::alias completes, the variable with this name is removed.
It is not allowed to have a variable that begins "MDB".
These are reserved for internal use.
+t
Unset the template
-I init-expression
An mdb expression to run prior to running the main expression.
The expression will not consume any piped input. If init_usage
is set and this expression evaluates to non zero then a usage
message is returned.
+I
Unset the init expression.
-F fini-expression
A mdb expression to run after to running the main expression.
The expression will not consume any piped input.
+F
Unset the fini expression.
Each of the expressions can contain shell-like variable expansions
within them which are expanded prior to the expression being evalu‐
ated. If the expression evaluated to an empty string or is not de‐
fined, the alias will simply print the current value of dot.
As well as any variables specified via templates the following
variables are defined:
$$ Substitute a single '$'
$* All the positional parameters that have not
been used by flags
$0 The name of this alias
$1 through $999 The unused positional parameters
$MDB_ADDRSPEC Expands to "" if an address was supplied as
an argument
$MDB_LOOP Expands to "" if the alias was invoked in a
loop with the ",count" syntax
$MDB_LOOP_COUNT Expands to the value of count if the alias
was invoked in a loop with the ",count" syn‐
tax
$MDB_PIPE Expands to "" if the alias was invoked with
the input from a pipe
$MDB_PIPE_OUT Expands to "" if the alias was invoked with
the output to a pipe
$MDB_KERNEL Expands to "" if debugging the kernel
$MDB_POSTMORTEM Expands to "" if debugging a post-mortem core
dump
$MDB_ARCH_I386 Expands to "" if the current target architec‐
ture is i386
$MDB_ARCH_AMD64 Expands to "" if the current target architec‐
ture is amd64
$MDB_ARCH_SPARC Expands to "" if the current target architec‐
ture is SPARC
$MDB_BIG_ENDIAN Expands to "" if the current target architec‐
ture's byte order is big-endian
$MDB_LITTLE_ENDIAN Expands to "" if the current target architec‐
ture's byte order is little-endian
$MDB_ARCH_SPARCV9 Expands to "" if the current target architec‐
ture is SPARCV9
$MDB_KMDB Expands to "" if in kmdb
The expansions can have the following modifiers:
${parameter:-word} If parameter is set then substitute its
value; otherwise substitute word
${parameter:+word} If parameter is set then substitute word;
otherwise substitute nothing.
${parameter:?word} If parameter is set then substitute its
value; otherwise print word to standard error
and report the USAGE
${parameter:@word} If parameter is set print word to standard
error and report the USAGE
See ::help ::alias within mdb for examples.
[ pid ] ::attach [ core | pid ]
[ pid ] :A [core | pid ]
If the user process target is active, attach to and debug the spec‐
ified 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 [ +/-BCdDeiosT] [-b function] [-c cmd] [-n count]
sym[+offset] ...
address :b [cmd ...]
The ::bp dcmd sets a breakpoint at each address or symbol plus off‐
set specified, including an optional address specified by an ex‐
plicit expression preceding the dcmd, and each string or immediate
value 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, as
described below.
-b function
Set the breakpoint to only fire below function in the call
stack. This option implies -C
-B
Set the breakpoint to only fire in or below the current stack
frame. This option implies -C
-C
Set the breakpoint to fire in the same thread (context) as the
current thread.
+C
Set the breakpoint to fire in the any thread. This is the de‐
fault unless the context_events option is set.
-o
Set an out breakpoint. This breakpoint will fire when the func‐
tion returns. This must be set before the function is entered.
When this event is hit the MDB_retbp variable will contain addr
or the symbol+offset used to declare the breakpoint.
The :b dcmd sets a breakpoint 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.
Breakpoint locations can be specified symbolically, as a symbol
name plus an optional offset, or as an immediate numeric value de‐
noting a absolute virtual address of interest. The symbolic form is
preferred for its mnemonic benefits, because such breakpoints can
be established early in a debug session before the target object is
loaded, and because they are immune to the normal object mapping
address changes that can occur across multiple execution runs for
position independent executables (PIE) or shared object libraries.
Symbolic breakpoints are deferred until object load time, and are
transparently reestablished by mdb on each run.
Immediate breakpoints can only be set for objects that have already
been mapped, and can become invalid between runs due to object map‐
ping address changes between runs. To allow the user to specify ab‐
solute addresses while mitigating these disadvantages, mdb will au‐
tomatically convert immediate breakpoints into symbolic form when
it is able to identify a symbol plus offset that describes the
given address. This behavior can be disabled by specifying the -i
flag to the ::bp dcmd, or by setting the immediate_breakpoints op‐
tion. See ::set -o.
Breakpoints on symbols defined in a shared library should always be
set using a symbol name, rather than as an address expression. Such
address can refer to the corresponding Procedure Linkage Table
(PLT) entry, and immediate breakpoints set on PLT entries can be
overwritten by the runtime link-editor when the PLT entry is subse‐
quently resolved, causing the breakpoint to be overwritten and
lost. To protect from this mdb will convert breakpoints set in the
PLT to symbolic breakpoints. This behavior can be disabled by spec‐
ifying the -i flag to the ::bp dcmd, or by setting the immedi‐
ate_breakpoints option. See ::set -o.
::cat [ -v variable-name ] 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 ini‐
tiate a pipeline using a list of addresses stored in an external
file.
If the optional variable-name is specified, the specified variable
is assigned the value returned.
::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 sim‐
ply waits for the target to terminate or stop after an event of in‐
terest. 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 cur‐
rently 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 config‐
ured to dump all pages or the pages of the current user process us‐
ing dumpadm(8). The ::status dcmd can be used to display the con‐
tents 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.
[ address ] ::constant [ -a|-d|-l ][-m module][constant]
Add, delete and list constants
The ::constant dcmd takes the following options:
-a Add a constant with value address
-d Delete the name constant
-l List all the constants with name constant
-m Operate on constants from module
::dcmds [ -av ][[ -dn ][ -- ] RE]
List the available dcmds that match regular expression RE and print
a brief description for each one. By default both the description
and name are searched.
The ::dcmds dcmd takes the following options:
-a Only list aliases
-d Search the description for a match
-n Search the name for a match
-v Also print each dcmds usage output
-- Specifies the end of option processing
[ address ] ::delete [ id ... | all ]
[ address ] :d [ id ... | all ]
Delete the event specifiers with the given id numbers. The id num‐
ber arguments are 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 ex‐
ample, 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 fi‐
nal 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 speci‐
fied 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 de‐
bugger 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 initial‐
ized, 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 speci‐
fied, 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 particu‐
lar dmod by specifying its name as an additional argument.
[ address ] ::dump [ -eqrstu ] [ -f|-p ] [ -g bytes ] [ -w paragraphs ]
Print a hexadecimal and ASCII memory dump of the 16-byte aligned
region of memory containing the address specified by dot. If a re‐
peat 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 ad‐
dress space. The -f option is enabled by default if the debug‐
ger 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 tar‐
get'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 op‐
tion.
-s
Elides repeated lines.
-t
Only reads from and displays the contents of the specified ad‐
dresses, 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 [-N][--][ string | value ...]
Print the arguments separated by blanks and terminated by a NEWLINE
to standard output. Expressions enclosed in $[ ] are evaluated to a
value and printed in the default base.
-N Print each argument on a new line.
::eval command
Evaluate and execute the specified string as a command. If the com‐
mand 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 to 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 run‐
ning, 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 contin‐
ued, 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 op‐
tion.
!
The event specifier was not armed due to an operating sys‐
tem 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 proper‐
ties. 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 ex‐
plicitly 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. For break points on capability symbols all
the symbols are listed, if the target program is stopped on one
of the symbols then the symbol that is stopped on is shown in
angle brackets < >.
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 ...
Modifies the properties of one or more software event specifiers.
The properties are set for each specifier identified by the op‐
tional expression preceding the dcmd and an optional list of argu‐
ments 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 re‐
moves any corresponding instrumentation and ignores the corre‐
sponding 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 prece‐
dence 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, re‐
gardless 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 specify‐
ing 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 call‐
back 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.
::editor [subcommand]
Provide editor specific commands and help. With no arguments it
produces help for the current editor mode, including a list of sub‐
commands that are available in this mode
::files
$f
Print a list of the known source files (symbols of type STT_FILE
present in the various target symbol tables).
[flt] ::fltbp [ +/-BCdDehstT] [-b function] [-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. If the -h
option is specified then all the possible machine faults are listed
and the dcmd exits. The -d, -D, -e, -s, -t, -T, -c, and -n options
have the same meaning as they do for the ::evset dcmd.
-b function
Set the breakpoint to only fire below function in the call
stack. This option implies -C
-B
Set the breakpoint to only fire in or below the current stack
frame. This option implies -C
-C
Set the breakpoint to fire in the same thread (context) as the
current thread.
+C
Set the breakpoint to fire in the any thread. This is the de‐
fault unless the context_events option is set.
[ 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 [-d] [-f] [-n | -s | size] [-r|-w] [ RE]
-d match just the description with regular expression RE
-f match just the format char with regular expression RE
-n sort by size of object reported or manipulated
-r only print formats that read
-s only print objects of size specified
-w only print formats that write
List the available output format characters for use with the /, \,
?, and = formatting dcmds, which match regular expression RE or all
of them if no regular expression is given. 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.
[addr] ::history [-n][-pls [file]]
Display, save and load command line history. With no options it
will display the current command line history.
When given an addr it will load and run that entry from the history
-l load the history from the history file
-n do not exec the command
-p print the expanded name of the history file
-s save the history to the history file
The -l, -p and -s flags can take an optional file name. If so they
will apply the expansions for the histfile and then perform the ac‐
tion.
[addr] ::hrtime [-abs] [|::dcmd ...]
Print specified high-resolution timestamp in human readable form
either relative to current system time or absolute time since boot.
If no timestamp is specified uses current hrtime as the value to
print. See ::time
-a Output the time as an absolute value
-b Output the time relative to the target's start (boot) time.
-s Scale an unscaled hrtime_t into nanoseconds.
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 ig‐
nored signals is initialized to the complement of the set of sig‐
nals that cause a process to dump core by default (see sig‐
nal.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.
[ address ] ::if [+a|-a][-p] {type member tests | [type] [at off] test}
Evaluate the tests and then print the old value of dot if the tests
are true.
+a | -a
By default, if examines the arguments to determine whether or
not to apply ADI normalization. If the member is a pointer the
default is to ADI-normalize it, otherwise the default is to not
ADI-normalize it. Set -a to require normalization, or +a to
disable it. If the platform does not support ADI this has no
effect.
-p
Use physical rather than virtual addresses.
There are two kinds of tests. The first allows you to test the
value of a member of a structure or union. The second allows you to
test an offset from dot. These tests can then be joined with AND or
OR to build more complex tests.
Start with an example of testing a member of a structure:
::if "struct foo" namep <> 0
This statement would print the old value of dot if the element
namep in structure foo were not 0.
::if "struct foo" namep <> 0 AND namep->name <> 0 AND
namep->name streq "bar"
The preceding statement would print the old value of dot if the el‐
ement name in structure pointed to by namep in foo were not 0 and
pointed to a string that contained the string bar.
::if "struct foo" name <> 0 AND name streq "bar" and value = 0x123
The preceding statement would print only if the name were bar and
value was 0x123.
The second form tests to see if the type at the given offset has
the given value. Here is an example:
::if uint_t at 0x34 = 0x123
This will print if the value of an uint_t at offset 0x34 is 0x123.
Again this can be joined with other tests using AND or OR. With
this form, ::if has a number of built-in types that are internal
that can be used even when there is no symbolic type information.
These types are:
char, uchar, short, ushort, int, uint, long, ulong,
longlong, ulonglong, pointer, addr
If the type is addr, then, rather than the value at that address,
the actual address is tested. So, the statement:
::if addr at 0x34 = 0x100034
...would report the value of dot only if dot+0x34 was 0x100034,
whereas:
::if pointer at 0x34 = 0x100034
...would print only if the value at dot+0x34.
More usefully, the statement:
::if "char *' at 0x34 streq "foo"
...will print the old value of dot if the string pointed to at off‐
set 0x34 is foo.
Possible tests are:
= The values are equal
<> The values are not equal
< The value is less than the right hand value
<= The value is less than or equal to the right
hand value
> The value is greater than the right hand value
>= The value is greater than or equal the right
hand value
& The values ANDed together are non zero.
% The left value modulo the right is non zero.
^ The values XORed together are non zero.
regex Does the string match the regular expression.
streq The strings exactly match.
strneq The strings do not match.
strcaseeq The strings match case insensitively.
strcaseneq The strings do not match case insensitively.
strstr The string contains the string.
strcasestr The string contains the case insensitive string.
strnstr The string does not contain the string.
strcasenstr The string does not contain the case insensitive
string.
strleneq The string is this length.
strlenne The string is not this length.
strlengt The string is longer than this.
strlenlt The string is shorter than this.
strlenge The string is this long or longer.
strlenle The string is this long or shorter.
=, <, <=, >, >=, &, % and ^ accept the following option:
+a | -a By default, if examines the arguments to determine
whether or not to apply ADI normalization. If the
member is a pointer the default is to ADI-normalize
it, otherwise the default is to not ADI-normalize
it. Set -a to require normalization, or +a to dis‐
able it. If the platform does not support ADI this
has no effect.
streq and strneq accept the following options:
-i Test ignoring the case.
-n Return true if there is no match.
-o offset Start search at offset into string.
-s Search for a substring.
strstr and strnstr accept the following options:
-i Test ignoring the case.
-n Return true if there is no match.
-v variable Store the address of the found string in vari‐
able.
regex accepts the following options:
-i Test ignoring the case.
-n Return true if there is no match.
-v variable Store the address of the found string in vari‐
able.
-x Insist on an exact match.
streq, strneq, strcaseeq, strcaseneq, strstr, and strcasestr accept
these options:
-s Search for a substring.
-o offset Start search at offset into string.
strstr and strcasestr accept these options:
-v variable Store the address of the found string in vari‐
able.
The right hand side of a test can be any one of the following:
o An element in the structure or union.
o The value from a symbol.
o An absolute value.
o <var — the value of the variable var.
o $[expr] - the value of dot after mdb expression expr is
evaluated. For example:
$[<var=J]
...would get the value of variable var.
::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 [-p] [-l] [-r] [-R]
[-b member [{{-M mask | -I mask} | -S bits | -E evalstr}]]
[{{ -m mask | -i mask } | -s bits | -e evalstr }]
[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. If ::list can determine the
type then type can be omitted. The member parameter is used to name
the member of type that contains a pointer to the next list ele‐
ment. The ::list dcmd continues iterating until a NULL pointer is
encountered, the first element is reached again (a circular list),
a loop is detection is enabled (-L) and a loop is detected, back
member checking is enabled (-b) and a bad back pointer is detected,
or an error occurs while reading an element. If the optional vari‐
able-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.
-b member
Verify that member points to the previous member of the list.
The first member of the list is allowed to have a NULL back
pointer.
-e evaluation
Pass the forward pointer through this mdb evaluation before
dereferencing it. If the evaluation updates mdb variables then
be aware that loop checking will also result in the evaluation
being run.
-E evaluation
Pass the back pointer through this mdb evaluation before
dereferencing it. If the evaluation updates mdb variables then
be aware that loop checking will also result in the evaluation
being run.
-i mask
Mask the forward pointer with the inverse of mask before deref‐
erencing it.
-I mask
Mask the back pointer with the inverse of mask before derefer‐
encing it.
-l
Do not check for loops in the list. If there is a loop this
will run forever.
-m mask
Mask the forward pointer with mask before dereferencing it.
-M mask
Mask the back pointer with mask before dereferencing it.
-p
Read from physical rather than virtual addresses.
-r
The forward member is an offset relative to the current value
of dot.
-R
The back member is an offset relative to the current value of
dot.
-s bits
Shift the forward pointer bits left before dereferencing it.
-S bits
Shift the back pointer bits left before dereferencing it.
Both the forward and back pointers can be supplied as members of a
structure or offsets.
addr ::tail [+-]num|[+-]n num [|::dcmd ...]
Prints the last elements in the pipe.
-n num OR -num Passes only the last num elements in the pipe.
+n num OR +num Passes all except the first num elements in the
pipe. (num is in decimal).
addr ::head [-+]num|[-+]n num [|::dcmd ...]
Limits the number of elements in pipe.
-n num OR -num Passes only the first num elements in the pipe.
+n num OR +num Passes all except the last num elements in the
pipe. (num is in decimal).
::load [ -s ] module-name
Load the specified dmod. The module name can be given as an ab‐
solute 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 exist‐
ing 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 log‐
ging 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 out‐
put 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 [ -DPTUdghnopuvx ] [ +/-S ] [ -N names ] [ -s keys ] [
-t types ] [ -f format ] [ object ]
Print the symbol tables associated with the current target. If an
optional address preceding the dcmd is specified, only the symbol
table entry for the symbol corresponding to address is displayed.
If an object is specified, only the symbol table for this load ob‐
ject is displayed. The ::nm dcmd also recognizes the following op‐
tions:
-D
Prints .dynsym dynamic symbol
-N name[,name ... ]
Only print symbols listed
-P
Prints the private symbol
-S
When using -U compare [value,value+size) and only display if
they are identical
-T
Prints .symtab symbol table
+S
When using -U compare [value,value+size) and only display if
they are not identical
-U
Only print symbols that have names that are not unique
-d
Prints value and size fields in decimal.
-g
Prints only global symbols.
-h
Suppresses the header line.
-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 subse‐
quently read into the debugger with $<.
-s key[,key ... ]
Sort using the comma separated list of keys. The valid key ar‐
gument strings are:
bind binding
ctype C type for symbol (if known)
data The contents of a symbol, reading from the address
given by the value for a length defined by the size
file file that defines the local symbol
name symbol name
obj object which defines symbol
type symbol type
size size in bytes
uqn Uniquely qualified name
val symbol value
If any key is prefixed with (^) the direction of the sort for
that key is reversed
-u
Prints only undefined symbols.
-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:
all display all categories of information contained in
this list
bind binding
ctfid ctf id
ctype C type for symbol (if known)
default the default fields (val, size, type, bind, other,
shndx, name)
file file that defines the local symbol
filebase basename of file that defines the local symbol
name symbol name
ndx symbol table index
obj object which defines symbol
objbase basename of the object which defines symbol
oth other
size size in bytes
shndx section index
type symbol type
uqn Uniquely qualified name
val symbol value
value ::nmadd [ -fo ] [ -e end ] [ -s size ] name
Add the specified symbol name to the private symbol table. mdb pro‐
vides a private, configurable symbol table that can be used to in‐
terpose on the target's symbol table, as described under Symbol
Name Resolution above. The ::nmadd dcmd also recognizes the follow‐
ing 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 dis‐
plays the version of each load object. Version information is not
available for all load objects. Load objects without version infor‐
mation is listed as having a version of "Unknown" in the output for
the -v option.
::offsetof member
Print the offset of the specified member of the specified type. The
type should be the name of a C structure. If no member is specified
all the members for this type are reported.
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 al‐
ways 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.
::operators
Print all the mdb operators with short descriptions.
address ::print [ -AaCdiLptx ] [ -c lim ] [ -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 or the address is in the type
cache, ::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 submem‐
bers 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 in‐
formation. 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 dis‐
played. 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 hexa‐
decimal. 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 de‐
scribed 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 start‐
ing at zero.
If the -A option is present then ::print will not print any annota‐
tions for data structures or the members.
address ::printf [ -e ] [ -i ] [ -c lim ] [ -t format ... ] format
[type][ +/-i ] arg ...
Print the data structure using the printf format command. Arguments
to the format can be:
o An element in the structure or union.
o The value from a symbol
o An absolute value.
o <var: The value of the variable var.
The number of characters in a character array or pointer that is
read and displayed as a string can be limited with the -c option.
If the value given is none no limit is applied.
The optional -t argument is used to specify a title which is
printed once before any other output is produced. If the -e is
given then write subsequent output to standard error. For possible
expansions in the format string, see the ::help printf command.
The option -i tells ::printf to treat the subsequent arguments as
immediate values. The +i option stops ::printf from treating argu‐
ments as immediate values. There can be multiple -i and +i argu‐
ments allowing immediate and non-immediate arguments to be mixed in
a single line
address ::poke[ -AnFfS ][ type ][ member ][ operator ][ -AnFfS ][ -v
var ][ -- ]
[ -s size ] value [ [ member ][ operator ][ -AnFfS ][ -v var ][ --
]
[ -s size ] value ]
Poke the supplied values into the supplied data structure. If a
member is given then write the valued into that member.
Multiple member value pairs can be supplied and they will all be
updated. If the user specifies the size and ::poke can determine
the correct size, the poke will only be carried out if the sizes
match or the -F flag is specified. If the poke is not carried out
then poke will report what would be done.
If no operator is specified the default is =
OPERATORS
% Take the modulo of the contents of address by value
C equivalent: *address %= value
& AND the contents of address with value
C equivalent: *address &= value
* Multiply the contents of address by value
C equivalent: *address *= value
+ Add the contents of address with value
C equivalent: *address += value
- Subtract value from the contents of address
C equivalent: *address -= value
/ Divide the contents of address by value
C equivalent: *address /= value
<< Shift left the contents of address by value
C equivalent: *address <<= value
= Write the value to address
C equivalent: *address = value
>> Shift right the contents of address by value. Signed values
are sign extended, unsigned values are zero filled.
C equivalent: *address >>= value
FLIP Flip the bit specified by value at address
C equivalent: *address ^= 1 << value
MASK AND the contents of address with the ones' complement of
value
C equivalent: *address &= ~value
OR OR the contents of address with value
C equivalent: *address |= value
^ XOR the contents of address with value
C equivalent: *address ^= value
~ Invert the bits in address. This operator does not take an
argument.
C equivalent: *address = ~*address
OPTIONS
-A Poke a character array. Without the force flag arrays
can only be poked to character arrays and pointers to
characters. When poking an array to a pointer, the
array is poked to the target of the pointer. Poking
an array is identical to poking a string, except the
terminating NUL is not poked
-f Write to the object file.
-F Force the writing when the size does not match
-S Poke a character string. Without the force flag
strings can only be poked to character arrays and
pointers to characters. When poking an string to a
pointer, the string is poked to the target of the
pointer.
-s size Set the size to poke. If the type is specified either
explicitly or implicitly, from a symbol the size is
not required. The size should only be needed if the
target does not have CTF debugging information. If
given this must be one of: 1, 2, 4 or 8.
-n variable Store the old value in variable.
-v Do not write. Just report what would have been at‐
tempted
::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 op‐
tion is present, the process is released and left stopped and aban‐
doned. It can subsequently be continued by prun(1) or it can be re‐
sumed 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.
[ addr ] ::save [-p] [type] [member] variable
Save values into an mdb variable such that the variable can be used
in a pipeline. If only a variable is given, then the current value
of dot is stored in the variable and dot is printed. If a type and
member is on the command line then the member is stored into the
variable. Dot is always printed without its value being changed.
::set [ -wF ] [ +/-o option ] [ -s distance ] [ -a path ] [ -I path ]
[ -L path ] [ -P prompt ]
Get or set miscellaneous debugger properties. If no options are
specified, the current set of debugger properties is displayed. The
::set dcmd recognizes the following options:
-a
Sets the path for loading aliases.
-F
Forcibly takes over the next user process that ::attach is ap‐
plied 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 argu‐
ment 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.
[address]::shell [-o b|o|d|x|s] "shell command"
Pipe the address or addresses through the shell command given and
then allow the output of the shell command to be piped back into
the mdb pipeline.
If the -o option is entered, interpret the output from the shell
command according to the numerical base specified. Arguments to -o
are as follows:
b binary
o octal
d decimal
x hexadecimal
s treat output as a string with no interpretation
Example:
::walk proc | ::shell "tail -10" | ::print proc_t
::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 ob‐
jects without version information are omitted from the output for
the -p option and are listed as having a version of "Unknown" in
the output for the -v option.
[signal] ::sigbp [+/-BCdDehstT] [-b function] [-c cmd] [-n count] SIG
...
[signal] :t [+/-dDehstT] [-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.
If the -h option is specified then all the possible signals are
listed and the dcmd exits. The -d, -D, -e, -s, -t, -T, -c, and -n
options have the same meaning as they do for the ::evset dcmd. Ini‐
tially, the set of signals that cause the process to dump core by
default (see signal.h(3HEAD)) and SIGINT are traced.
-b function
Set the breakpoint to only fire below function in the call
stack. This option implies -C
-B
Set the breakpoint to only fire in or below the current stack
frame. This option implies -C
-C
Set the breakpoint to fire in the same thread (context) as the
current thread.
+C
Set the breakpoint to fire in the any thread. This is the de‐
fault unless the context_events option is set.
::sizeof [-s size] [-r min max] [type [member ...]]
Options are as follows:
-s size Show types for entries of this size.
-r min max Show types for entries in range of sizes.
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.
member can be specified with standard C syntax using the array in‐
dexing operator "[index]", structure member operator ".".
The ::sizeof dcmd can only be used with objects that contain sym‐
bolic debugging information designed for use with mdb. Refer to
NOTES, Symbolic Debugging Information, below for more information.
::sleep [-m | -n | -u] time
Sleep for time.
-m time is specified in milliseconds
-n time is specified in nanoseconds
-u time is specified in microseconds
... | ::sort [-u [-c] [-v var]] [type] [+a|-a][+S|-S][-s [-i]] [-r]
[at] offset|member [[+a|-a][+S|-S][-s [-i]] [-r] [-u] member]... [|::dcmd ...]
Sort the addresses based on the rules given. With no arguments
::sort sorts the address based on its numeric values. If a type is
given then ::sort sorts based on the member of structure or union
given. If an offset is given then the sort is based on the value of
the simple type at that value. Multiple sort keys can be given and
each sort key can have its own options. See SORT KEY OPTIONS.
SIMPLE TYPES
char, uchar, short, ushort, int, uint, long, ulong, longlong, ulon‐
glong, pointer, addr
OPTIONS
-u Uniq. Only prints addresses that match according to the sort
criteria once.
-R Not unique. Suppresses lines that do not have matches accord‐
ing to the sort.
-U Really unique. Only prints entries that are unique according
to the sort.
-c If not outputting to a pipe and using the unique flag then
print a count of matches before each address.
-v Stores the count of unique entries in variable var.
SORT KEY OPTIONS
-a | +a By default, sort examines the arguments to determine
whether or not to apply ADI normalization. If the member
is a pointer the default is to ADI-normalize it, other‐
wise the default is to not ADI-normalize it. Set -a to
require normalization, or +a to disable it. If the plat‐
form does not support ADI this has no effect.
-i If sorting strings ignore case.
-l len If sorting pointers dereference the pointer and compare
len bytes.
-r Reverse the order of this test.
-s Treat this item as a string.
-S | +S By default, sort examines the arguments to determine
whether to sort values as signed or unsigned. If the
member being sorted is signed then the sort will be
signed otherwise it will be unsigned. Set -S to force
signed sorting, or +S for unsigned sorting.
-u Uniq for this key. Sort using the remaining keys but
only output the last entry that matches on this key. See
::help sort for examples.
[ address ] ::stack [-A][-r][-T][-v][-x] [ count ]
[ address ] $c [-A][-r][-T][-v][-x] [ 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 dis‐
played. If an optional count value is given as an argument and the
debugger can not determine how many arguments a function has then
no more than count arguments are displayed for each stack frame in
the output.
-A Do not print annotations
-r Print registers when available
-T Do not print the types of arguments when available
-v Verbose, print the frame pointer
-x Always print arguments in hex
If mdb can not confirm the validity of a function argument it will
append ? to the value. When structures or unions are passed as ar‐
guments the values may be displayed as raw bit dumps surrounded by
< and > or prefixed with * and then the address of the value is
displayed. Which of the two formats is used depends on how the ar‐
guments are passed to the function, if passed on the stack the ad‐
dress format is used, if passed in registers the <value> form is
used.
::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 re‐
turns 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.
[ addr ] ::sum [type [member]]
Add up list of numbers from pipe. These can be read directly or ac‐
quired from a member in a structure specified by address.
[ addr ] ::strlen
Print the length of a string.
[ syscall ] ::sysbp [ +/-BCdDehstT ] [ -io ] [ -b function ] [ -c cmd ]
[ -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 -h option is specified
then all the possible system calls are listed and the dcmd exits.
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.
-b function
Set the breakpoint to only fire below function in the call
stack. This option implies -C
-B
Set the breakpoint to only fire in or below the current stack
frame. This option implies -C
-C
Set the breakpoint to fire in the same thread (context) as the
current thread.
+C
Set the breakpoint to fire in the any thread. This is the de‐
fault unless the context_events option is set.
[addr] ::time [-abdhlsux] [-o opt,...] [|::dcmd ...]
Print any times that the target supports and convert between for‐
mats. When converting for times with higher resolutions to times
with lower resolutions there is obviously loss of accuracy.
When converting to and from the real-time clock no account is taken
of any adjustments that are made in the real clock by external fac‐
tors, like NTP.
-a Output the time as an absolute value
-b Output the time relative to the target's start (boot)
time.
-d Output the time in decimal (the default).
-h Output the time in a more human readable form.
-l Output the lbolt. Shorthand for -o lbolt.
-o option report the requested option. See OPTIONS
-r Output the time in the default radix.
-s Scale unscaled hrtime_t. Shorthand for -o hrscale.
-u Unscale scaled hrtime_t. Shorthand for -o hrunscale.
-x Output the time in hexadecimal.
OPTIONS
all report all the possible times
allcpu report all the possible CPU times
allstart report all the possible start times
allstop report all the possible stop times
csystime Children's system cpu time
cusertime Children's user cpu time
hr2lbolt Convert high resolution time to lbolt
hr2rt Convert high resolution time to real time
hrres High resolution clock resolution
hrscale Scale addr
hrstart Target start high resolution time
hrstop Target stop high resolution time
hrsys System high resolution time
hrunscale Un-scale addr
hrustart Target start unscaled high resolution time
hrustop Target stop unscaled high resolution time
lbolt The value of lbolt
lbolt2hr Convert lbolt to high resolution time
lboltres Lbolt resolution
list List all the options
pass Print addr as an high resolution time. Default when an
address is supplied.
rt2hr Convert high resolution time to real time
rtres Real time clock resolution
rtstart Target start time after epoch
rtstop Target stop time after epoch
rtsys System time after epoch
systime Process system cpu time
usertime Process user cpu time
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.
[addr]::typecache [-a|-f|-r [-s][ type ]]
Add, remove, flush or view the type cache. Mdb maintains three
caches of types:
system If a type can be be verified within the target to a
type, typically because it references a symbol or as a
confirmed function argument or it is derived from an
entry from the system cache then it is added to the
system cache.
user If the system is relying on the user to specify the
type and can not verify the type then the virtual ad‐
dress is added to the user cache.
pipe The pipe cache only lasts as long as an mdb pipeline.
If an entry appears to be illegal, for example when
its alignment does not match the type to which it
refers, it is added to the pipe cache so that subse‐
quent dcmds in the pipeline get a valid type and can
deal with any error. When debugging targets that are
not stopped, for example a live kernel, pipe cache is
used.
With no options ::typecache dcmd will display any type cache infor‐
mation for addr or the entire cache if no address is given. If the
output is a pipe then every address in the cache is output.
The ::typecache dcmd takes the following options:
-a Add addr to the type cache with type type. If the out‐
put is a pipe addr is printed.
-r Remove addr from the type cache. If type is specified
then remove all the entries with that type from the
cache.
-f Flush the type cache.
-s When adding, deleting or flushing operate on the sys‐
tem cache. The default is to operate on the user
cache.
The two caches are provided as a convenience for the user, making
it simple to flush the user cache without disturbing system en‐
tries.
When the target changes state, for example by being continued, all
the caches are flushed.
[addr]::typemap [-a|-c|-d|-r][[-A [-s]]|[-n]][ -i id ][ -t type ][ -m
type ][ -c expression ][mapped type]
Type map is used to manage and display type and name mappings. When
type mapping is enabled mdb will map types according to the map‐
pings defined within mdb modules.
There are three kinds of mappings:
Type Type mappings will map a pointer type from one type to an‐
other. This is typically used to map void pointers to
their actual data types.
Name Name mappings allow short cuts to be set up when accessing
structure or union members. Typically when the source used
#define to access a member, a name mapping allows the same
name to be used in mdb.
Array Array mappings allow mdb to use the contents of a data
structure to determine how many elements of a array are in
use, or for flexible arrays how many elements they con‐
tain. When an array is truncated due to an array mapping,
::print prints +++ rather than ... to indicate there are
more entries.
::typemap takes the following options:
-a add a type mapping
-A Operate on the array mappings
-c expression Expression to test if mapping is to be used. For
array mappings the expression should set dot to
the number of elements in the array
-d disable a mapping
-e enable a mapping
-f force flag (for remove)
-i id id of mapping to be printed/disabled/enabled/re‐
moved
-m member object member for mapping
-n Operate on the name mappings
-O The array mapping is allowed to be out of bounds
without a warning being printed.
-o offset When adding an array mapping, this offset is added
to the value read from mapped type
-r remove a mapping
-t type type of object for mapping
-V verbose mode for printing
When no add, remove, enable or disable options are given ::typemap
displays the current mappings.
See ::help typemap for example usage.
::typeset [+/-C][+/-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 the -C option is present any variables that are created will be
context variables. This is the default unless the typeset_global
option is set with ::set. If the +C is set any variables created
will be global. This is the default if typeset_global is not set.
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. Mod‐
ules that are busy (that is, provide dcmds that are currently exe‐
cuting) 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.
::until expr [do expr1 ...]
Until expr evaluates to set dot non-zero, run expr1 ....
::vars [-Canpt]
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 -a option is present, any built in variables that
are hidden are displayed. If -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 op‐
tion is present, only the tagged variables are printed. Variables
can be tagged using the -t option of the ::typeset dcmd. If the -C
option is given then only context variables are displayed and the
values for all contexts are displayed.
::version
Print the debugger version number.
address ::vtop [-a as]
Print the physical address mapping for the specified virtual ad‐
dress, if possible. The ::vtop dcmd is only available when examin‐
ing a kernel target, or when examining a user process inside a ker‐
nel crash dump (after a ::context dcmd has been issued).
When examining a kernel target from the kernel context, the -a op‐
tion can be used to specify the address (as) of an alternate ad‐
dress space structure that should be used for the virtual to physi‐
cal 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 vari‐
able-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 [[ -dn ][ -- ] RE]
List the available walkers that match the regular expression RE and
print a brief description for each one.
The ::walkers dcmd takes the following options:
-d Search the description for a match
-n Search the name for a match
-- Specifies the end of option processing
... | ::wc [-x]
Count the elements in a pipe.
-x Output the value in hexadecimal.
::whence [ -v ] name ...
::which [ -v ] name ...
Print the dmod that exports the specified dcmds and walkers. These
dcmds can be used to determine which dmod is currently providing
the global definition of the given dcmd or walker. Refer to the
section on dcmd and Walker Name Resolution above for more informa‐
tion on global name resolution. The -v option causes the dcmd to
print the alternate definitions of each dcmd and walker in order of
precedence.
::while expr [do expr1 ...]
While expr evaluates to set dot non-zero, run expr1 ....
addr [ ,len ] ::wp [ +/-dDestT ] [ -rwx ] [ -b function ] [ -c cmd ] [
-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 de‐
fault is one byte. The ::wp dcmd allows the watchpoint to be con‐
figured 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.
-b function
Set the breakpoint to only fire below function in the call
stack. This option implies -C
addr ::array [-t member_type|-s member_size|-S array_size]
[-v variable] [type] [member] [count] [variable] [|::dcmd ...]
Print the addresses of each element in an array. In its first form,
::array treats dot as the start of an array of type type and length
count:
::array type count
In its second form, ::array treats dot as the address of a struc‐
ture or union of type type with a member that is either a pointer
to an array or an embedded array:
::array type member count
In this form, count can be an integer, variable or structure/union
field, in which case the value of that field is used.
You can also specify the size of the array by using one of '-s',
'-S', or '-t' option. This is useful when the array is pointed to
using a "void *" so the correct size can not be inferred from the
type of the pointer.
The arguments to the -S and -s flags can be in integer, mdb vari‐
able (<var), evaluation ($[ mdb eval ]), global variable, integer
pointed to by a global (*global) or member of the data structure.
-v var Save dot into variable var. This is the preferred
way to specify variables.
-S array_size Specify the total size of the array.
-s member_size Specify the size of the element of the array.
-t member_type Specify the type of the element of the array.
addr ::xdata [ -f file [ -w [ -n nelem ]]] [ -o offset ] [ -t type ] [
xdataname ]
With no arguments ::xdata lists the names of the external buffers
exported by the current target. External data buffers represent in‐
formation associated with the target but are not part of the target
address space.
If a valid xdataname is given, that external data is temporarily
mapped into the target's address space and the address of the map‐
ping along with any annotation are reported. There is no actual
change to the target. The mapping only persists while the ::xdata
is running. ::xdata sets the type of the resulting mapping allowing
the output to be piped to other dcmds to process.
-f file Map the named file into the mdb address space. The
file will be mapped into the largest hole in the ad‐
dress space that can be found. If a hole large enough
for the file can not be found, the file will be mapped
at a low, non-zero, address.
-n nelem When a file is mapped read-write with a supplied addr,
copy an array of nelem members of data from the target
into the address space. nelem defaults to 1. If no
type is specified the type defaults to uint8_t.
-o offset Map the data at the given offset, this can be zero but
many dcmds and walkers will check 0 and assume it is
an error. By default ::xdata will attempt to find a
suitable hole in the address space to map the data.
-t type When a file is mapped set the type to type.
-w Map the file read-write. If addr is given then the
file is created, if needed, and nelem objects of type
type are copied from that address prior to the file
being mapped into the target's address space. With
this option the file can be edited with ::poke.
For more information, see the ::help xdata output and refer to the
Oracle Solaris 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 li‐
braries in a user process or core file, or to the loaded kernel
modules in the live operating system or an operating system crash
dump.
-a
Set the default path to load aliases from. The path is a sequence
of directory names delimited by colon (:) characters. When loading
aliases each directory in the alias path is processed until the
alias is loaded. Before reading the directory any sub-directories
named after the currently loaded modules in the target are
processed for aliases.
The alias path, -I include path and -L library path (see below)
can also contain any of the following tokens:
%b
Expands to the number of bits in a word. 32 or 64.
%h
Expands to the current value of the $HOME environment variable.
%i
Expands to the current instruction set architecture (ISA) name
('sparc', 'sparcv9', 'i386' or 'amd64').
%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/host‐
name/bin/mdb were executed, the root directory would be derived
as /net/hostname.
%t
Expands to the name of the current target. This will be one of
the literal strings 'proc' (a user process or user process core
file), 'kvm' (a kernel crash dump or the live operating sys‐
tem), or 'raw' (a raw file).
The default alias path for 32-bit mdb is:
%h/.mdb/%t:%h/.mdb:%r/usr/lib/mdb/alias/%t:%r/usr/lib/mdb/alias
The default alias path for 64-bit mdb is:
%h/.mdb/%t/%i:%h/.mdb/%t:%h/.mdb/%i:%h/.mdb:%r/usr/lib/mdb/alias/%t/%i:%r/usr/lib/mdb/alias/%t:%r/usr/lib/mdb/alias/%i:%r/usr/lib/mdb/alias
-f
Forces raw file debugging mode. By default, mdb attempts to infer
whether the object and core file operands refer to a user exe‐
cutable 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 at‐
tempting to control the process.
-I path
Sets default path for locating macro files. Macro files are read
using the $< or $<< dcmds.
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 exe‐
cutable 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(4D). If not combined with --load-debugger 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. This op‐
tion also requires one of the --stop-entire-system or --stop-en‐
tire-cluster-node if used on a non-clusterered node an clusterered
node respectively.
-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 de‐
mand-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 must be boolean and the option is
disabled. Options can be truncated, as long as the option remains
unique. It is not recommended that options written into aliases or
configuration files are truncated as they could be made invalid in
future updates. Unless noted below, each boolean 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 ar‐
ray. If limit is the special token none, the entire char array
is displayed as a string by default.
context_events
Set the default for new events to be per context (thread). To
get per process events use the +C option when specifying the
event.
editor=editor
Choose the command line editor style. This can take the values
"emacs" or "vi".
follow_exec_mode=mode
Sets the debugger behavior for following an exec() and spawn()
system call. The mode should be one of the following named con‐
stants:
ask
If stdout is a terminal device, the debugger stops after
the exec() or spawn() system call has returned and then
prompts the user to decide whether to follow the new pro‐
gram or stop. If stdout is not a terminal device, the ask
mode defaults to stop. ask is the default.
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 be‐
havior is discussed in more detail under NOTES, Interaction
with Exec, below.
stop
The debugger stops following return from the exec() or
spawn() 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 fork(), fork1(),
vfork(), or spawn() 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() or spawn() system call has returned and then
prompts the user to decide whether to follow the parent or
child and whether to stop or continue. If stdout is not a
terminal device, the ask mode defaults to parent. ask is
the default.
parent
The debugger follows the parent process, and detaches from
the child process.
child
The debugger follows the child process, and detaches from
the parent process.
stop_parent
The debugger follows the parent process, detaches from the
child process and then stops the parent on exit from the
system call.
stop_child
The debugger follows the child process, detaches from the
parent process and then stops the child on exit from the
system call.
histfile
The name of the file to save and load command line history
from. The file name can contain the following expansions:
%% %
%R The value of the ROOT environment variable
%T The value of the TMPDIR environment variable or /tmp if
not set
%b The size of a pointer in bits for the target
%e The (exec)name of the program being debugged
%h The value of the HOME environment variable
%i The target's instruction set architecture
%m The target's machine from uname(1)
%n The target's nodename from uname(1)
%p The target's SI_PLATFORM sysinfo(1)
%r The target's release from uname(1)
%s The target's sysname from uname(1)
%t The name of the target
%u The value of the LOGNAME environment variable
%v The target's version from uname(1)
immediate_breakpoints
Forces mdb to not turn breakpoints into symbol+offset but al‐
ways install them at the address specified. Using this option
will result in incorrect breakpoints if the mapping address of
any object changes between runs.
ignoreeof
The debugger does not exit when an EOF sequence (^D) is entered
at the terminal. The ::quit dcmd must be used to quit.
narg
The default maximum number of function arguments to display
when printing stacks when the validity can't be determined.
noalias
Does not auto load aliases at start up time or when the alias
path changes or modules get loaded. Aliases can still be loaded
via the -i option to the ::alias dcmd.
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 ap‐
plied. The nostop behavior is described in more detail under
NOTES, Process Attach and Release, below.
nostrict
The debugger will not enforce the usage restrictions of DCMDs.
notypecache
The debugger will not use the type cache.
notypemap
The debugger will not do type or name mapping.
typecheck=action
Control whether mdb will check the types of addresses passed to
dcmds and walkers. action can take the following values:
off Do not do type checking.
stop Stop the pipeline if the type of dot does not match one
of the types the dcmd or walker expects.
warn Print a warning if the type of dot does not match one
of the types the dcmd or walker expects.
typeset_global
Variables created with the ::typeset command will default to
being global.
other_fork_branch_mode=mode
When the target makes a fork(), vfork(), fork1() or spawn()
system call, control how to detach from the process that is not
followed. The mode should be one of the following constants:
ask If stdout is a terminal device, the debugger
stops after the fork(), fork1(), vfork() or
spawn() system calls have returned and then
prompts the user to decide whether to leave
the other process stopped. If stdout is not a
terminal device, the ask mode defaults to re‐
lease. ask is the default.
leave_stopped The debugger will leave the other process
stopped. If the system call is vfork() the
other process is not left stopped until after
the child has completed the exec() system call
or exited.
release The debugger releases the other process so
that it can continue.
output_format=format
Select the output format for mdb. The format should be one of
the following:
plain The output is unformatted.
xml The output is XML.
output_level=level
Select the output format for mdb. The level should be one of
the following: default, verbose and debug, where default gives
the least output and debug the most.
pager
Enables the output pager (default).
repeatlast
If a NEWLINE is entered as the complete command at the termi‐
nal, mdb repeats the previous command with the current value of
dot. This option is implied by -o adb.
savehist
When set, save the current command line history to the history
file when mdb exits.
search_defer_mods
A colon separated list of modules to defer searching when per‐
forming a symbol name look up. Symbols from these modules are
only used if no non-zero sized symbols are found in other mod‐
ules with the name given. When updating this option, if the
list begins with +, the entries are added to the existing list.
If the list begins with -, the entries are removed from the
list, otherwise the new list replaces the existing list.
When debugging user applications ld.so.1 is added to this list
by default.
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 Resolu‐
tion, 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 op‐
tionally 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 accord‐
ing to the value of showlmid above, including ::nm, ::mappings,
$m, and ::objects.
symname_index
Control checking for ambiguous symbol names.
ambiguous Only ambiguous symbols are indexed. This uses less
memory but means that the fully qualified ob‐
ject`file`name naming can only be used for symbol
names that are ambiguous. This is the default in
kmdb(4D).
full A full index is maintained. This is the default in
mdb.
off No index is maintained and do no ambiguous symbol
name checking is done. This uses no memory and has
no performance impact. If you know you do not have
ambiguous symbol names in your debugging and are
using conditional breakpoints this reduces the
performance impact of mdb.
zero_alloc
Allow mdb modules to have memory allocations of zero size.
Without this option a memory allocation of zero bytes is con‐
sidered an error and the dcmd or walker is terminated. Using
this option risks the dcmd or walker failing and potentially
causing mdb to crash.
-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 it‐
self. 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 con‐
versions to the specified distance. By default, mdb sets the dis‐
tance 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 dis‐
tance and the symbol size is ignored.
-S
Suppresses processing of the user's ~/.mdbrc file and the default
alias files from the users ~/.mdb directory. By default, mdb reads
and processes the macro file .mdbrc and aliases from the directory
.mdb in the user's home directory, as defined by $HOME, if they are
present. If the -S option is present, these actions are not taken.
-u
Forces user debugging mode. By default, mdb attempts to infer
whether the object and core file operands refer to a user exe‐
cutable and core dump, or to a pair of operating system crash dump
files. The -u option forces mdb to assume these files are not oper‐
ating 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 disas‐
sembler 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. For write
access to the kernel you must use the --unsafe-write-access option.
-y
Sends explicit terminal initialization sequences for tty mode. Some
terminals require explicit initialization sequences to switch into
a tty mode. Without this initialization sequence, terminal features
such as standout mode can not be available to mdb.
--load-debugger
When used with -K loads kmdb but does not enter the debugger. The
system will continue.
--unsafe-io-access
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 manipula‐
tions. Use this option only when debugging device drivers and with
caution.
--unsafe-write-access
Opens the live kernel for writing.
--stop-entire-cluster-node
Required with -K to enter kmdb on a system that identifies as a
cluster node. The system will be stopped and the kmdb prompt will
appear on the console. Any cluster heartbeats will be stopped and
so could result in other nodes taking over cluster operations. Con‐
tinuing from this state is extremely high risk and could result in
data loss.
--stop-entire-system
Required with -K to enter kmdb on a system that does not identify
as a cluster node. The system will be stopped and the kmdb prompt
will appear on the console.
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 sys‐
tem crash dump file. If a process ELF core file operand is provided
without a corresponding object file, mdb attempts to infer the name
of the executable file that produced the core using several differ‐
ent algorithms. If no executable is found, mdb still executes, but
some symbol information can be unavailable.
If system crash dump file is provided without a corresponding ob‐
ject file, mdb attempts to load the object file (the unix binary)
contained in vmcore.N file.
suffix
Specifies the numerical suffix representing a number of operating
system crash dump files. For example, if the suffix is '3', mdb in‐
fers that it should examine the files 'unix.3' and all 'vm‐
core-<section>.3' files. If these files do not exist, but 'vm‐
dump.3' does exist, then a message is printed indicating that
savecore -f vmdump.3 must be run first in order to uncompress the
dump file. If vmcore.3 exists and some of the vmcore-<section>.3
files referenced by vmcore.3 do not exist, mdb loads the files and
issues warning that the virtual memory image will not be complete.
If a system crash dump with this suffix can not be found in the
current directory then the current directory is searched for a sub‐
directory called suffix and then the system crash dump with this
suffix is opened. If no system crash dump can be found in there,
then dumpadm(8) is consulted to find where savecore(8) will write
system crash dumps and the suffix subdirectory is then searched.
The string of digits are not interpreted as a suffix if an actual
file of the same name is present in the current directory.
latest
Specifies that mdb should find the latest system crash dump. The
current directory is searched for a subdirectory called latest and
then the newest system crash dump in that directory is opened. If
no system crash dump can be found in there, then dumpadm(8) is con‐
sulted to find where savecore(8) will save system crash dumps and
the latest subdirectory is then searched.
If there is a file called latest in the current directory then no
search is done.
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
MDB_EDITOR, EDITOR, FCEDIT, VISUAL
These variables are read in order until one is found that contains
the string "vi" or the string "emacs" then the default editor mode
is set accordingly. If none are found the default editor mode is
"emacs"
MDB_HISTFILE
This variable is used to determine the history file to use. The de‐
fault history file is "%h/.mdb/history/%t_%p_%b_%e".
HISTSIZE
This variable is used to determine the maximum length of the com‐
mand 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 control‐
ling user processes.
$HOME/.mdb
/usr/lib/mdb/aliases
Default directories for loading aliases. If an alias already exists
then it will not be over written by a definition later in the path.
/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 ei‐
ther 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 ei‐
ther 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:
tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) ATTRIBUTE TYPEAT‐
TRIBUTE VALUE _ Availabilitydeveloper/debug/mdb _ Interface Stability‐
Committed
SEE ALSO
adb(1), gcore(1), pgrep(1), proc(1), ps(1), stty(1), truss(1), un‐
ame(1), _lwp_self(2), exec(2), fork(2), pipe(2), spawn(2), vfork(2),
dlopen(3C), signal(3C), thr_self(3C), elf(3ELF), signal.h(3HEAD),
libc_db(3LIB), libkvm(3LIB), ksyms(4D), mem(4D), core(5), proc(5), at‐
tributes(7), threads(7), coreadm(8), dumpadm(8), savecore(8)
Oracle Solaris 11.4 Linkers and Libraries Guide
Oracle Solaris Modular Debugger Guide
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 situa‐
tions. However, it is not possible for mdb to know definitively whether
the dmod in question has corrupted only its own state, or the debug‐
ger'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 de‐
bug 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 struc‐
ture.
NOTES
Limitations on Examining Process Core Files
mdb does not provide support for examining process core files that were
generated by a release of Solaris preceding Solaris 2.6. When debugging
core files generated by a release of Solaris 9 or an earlier release,
symbol information might not be available. Since the text section and
read-only data is not present in those core files, the symbol informa‐
tion might not match the data present in the process at the time it
dumped core. In releases later than Solaris 9, text sections and read-
only data are included in core files by default. Users can configure
their processes to exclude that information from core files using core‐
adm(8). Thus, the information presented by mdb for those core files can
not match the data that was present at the time the process dumped
core. Core files from Solaris x86 systems can not be examined on So‐
laris SPARC systems, and vice-versa.
Limitations on Examining Crash Dump Files
Crash dumps from Solaris 7 and earlier releases can only be examined
with the aid of libkvm from the corresponding operating system release.
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.
The mdb command issues a warning message if it detects this condition.
Crash dumps from Solaris x86 systems cannot be examined on Solaris
SPARC systems, and vice-versa.
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 au‐
tomatically 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 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() or spawn(), the
behavior of the debugger is controlled by the ::set -o fol‐
low_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 capabili‐
ties for examining the new process. All built-in dcmds work as adver‐
tised, but loadable dcmds do not since they do not perform data model
conversion of structures. The user should release and re-attach the de‐
bugger to the process as described above in order to restore full de‐
bugging 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 fore‐
ground, 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 re‐
mains stopped until one of the continue dcmds is applied, or the debug‐
ger 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 in‐
consistent results) and breakpoints or other tracing flags might be en‐
abled. If the :c or ::cont dcmds are executed while the process is run‐
ning, 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, ::re‐
lease, :r, ::run, $q, or ::quit dcmds are executed, or when the debug‐
ger 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 al‐
ready 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, ::poke, ::print, and ::sizeof dcmds require
that one or more load objects contain compressed symbolic debugging in‐
formation suitable for use with mdb. This information is currently only
available for certain Solaris commands, libraries and kernel modules.
Developer Information
The Oracle Solaris Modular Debugger Guide provides a more detailed de‐
scription of mdb features, as well as information for debugger module
developers.
The header file <sys/mdb_modapi.h> contains prototypes for the func‐
tions in the MDB Module API, and the /source/demo/mdb-examples package
provides source code for an example module in the directory
/usr/demo/mdb.
Oracle Solaris 11.4 28 August 2025 mdb(1)