|
Hopefully, this page is exactly what you are looking for, but if not, you can always find further assistance on Unix/Linux Forum!
User Commands mdb(1)
NAME
mdb - modular debugger
SYNOPSIS
mdb [-fkmuwyAFKMSUW] [_o option] [-p pid] [-s distance] [-I
path] [-L path] [-P prompt] [-R root] [-V dis-version]
[object [core] | core | suffix]
DESCRIPTION
Introduction
The mdb utility is an extensible utility for low-level
debugging and editing of the live operating system, operat-
ing system crash dumps, user processes, user process core
dumps, and object files. For a more detailed description of
mdb features, refer to the manual, Solaris 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 pro-
gram 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 sys-
tem, 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 situa-
tions where the developer can only access post-mortem infor-
mation.
mdb provides a completely customizable environment for
debugging these programs and scenarios, including a dynamic
module facility that programmers can use to implement their
own debugging commands to perform program-specific analysis.
Each mdb module can be used to examine the program in
several different contexts, including live and post-mortem.
Definitions
The target is the program being inspected by the debugger.
mdb currently provides support for the following types of
targets: user processes, user process core files, 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 proper-
ties, including one or more address spaces, one or more sym-
bol tables, a set of load objects, and a set of threads that
can be examined using the debugger commands described below.
SunOS 5.10 Last change: 30 Nov 2005 1
User Commands mdb(1)
A debugger command, or dcmd (pronounced dee-command) in mdb
terminology, is a routine in the debugger that can access
any of the properties of the current target. mdb parses com-
mands from standard input, and then executes the correspond-
ing 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 Solaris Modular Debugger Guide.
A walker is a set of routines that describe how to walk, or
iterate, through the elements of a particular program data
structure. A walker encapsulates the data structure's imple-
mentation from dcmds and from mdb itself. You can use walk-
ers interactively, or use them as a primitive to build other
dcmds or walkers. As with dcmds, you can extend mdb by
implementing your own walkers as part of a debugger module.
A debugger module, or dmod (pronounced dee-mod), is a dynam-
ically loaded library containing a set of dcmds and walkers.
During initialization, mdb attempts to load dmods
corresponding to the load objects present in the target. You
can subsequently load or unload dmods at any time while run-
ning mdb. mdb ships with a set of standard dmods for debug-
ging the Solaris kernel. The 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 pro-
cess of displaying a simple data structure. mdb provides
complete backward compatibility for the execution of macro
files written for adb(1), and the Solaris installation
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 syn-
tax 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:
[ ] | ! / \ ? = > $ : ;
SunOS 5.10 Last change: 30 Nov 2005 2
User Commands mdb(1)
NEWLINE SPACE TAB
A blank is a TAB or a SPACE. A word is a sequence of charac-
ters separated by one or more non-quoted metacharacters.
Some of the metacharacters only function as delimiters in
certain contexts, as described below. An identifier is a
sequence of letters, digits, underscores, periods, or
backquotes beginning with a letter, underscore, or period.
Identifiers are used as the names of symbols, variables,
dcmds, and walkers. Commands are delimited by a NEWLINE or
semicolon ( ; ).
A dcmd is denoted by one of the following words or metachar-
acters:
/ \ ? = > $character :character ::identifier
dcmds named by metacharacters or prefixed by a single $ or :
are provided as built-in operators, and implement complete
compatibility with the command set of the legacy adb(1)
utility. Once a dcmd has been parsed, the /, \, ?, =, >, $,
and : characters are no longer recognized as metacharacters
until the termination of the argument list.
A simple-command is a dcmd followed by a sequence of zero or
more blank-separated words. The words are passed as argu-
ments to the invoked dcmd, except as specified under Quoting
and Arithmetic Expansion below. Each dcmd returns an exit
status that indicates it was either successful, failed, or
was invoked with invalid arguments.
A pipeline is a sequence of one or more simple commands
separated by |. Unlike the shell, dcmds in mdb pipelines are
not executed as separate processes. After the pipeline has
been parsed, each dcmd is invoked in order from left to
right. Each dcmd's output is processed and stored as
described under dcmd Pipelines below. Once the left-hand
dcmd is complete, its processed output is used as input for
the next dcmd in the pipeline. If any dcmd does not return a
successful exit status, the pipeline is aborted.
An expression is a sequence of words that is evaluated to
compute a 64-bit unsigned integer value. The words are
evaluated using the rules described under Arithmetic Expan-
sion below.
SunOS 5.10 Last change: 30 Nov 2005 3
User Commands mdb(1)
Commands
A command is one of the following:
pipeline [! word ...] [ ; ]
A simple-command or pipeline can be optionally suffixed
with the ! character, indicating that the debugger
should open a pipe(2) and send the standard output of
the last dcmd in the mdb pipeline to an external process
created by executing $SHELL -c followed by the string
formed by concatenating the words after the ! character.
For more details, refer to Shell Escapes below.
expression pipeline [! word ...] [ ; ]
A simple-command or pipeline can be prefixed with an
expression. Before execution of the pipeline, the value
of dot (the variable denoted by ``.'') is set to the
value of the expression.
expression , expression pipeline [! word ...] [ ; ]
A simple-command or pipeline can be prefixed with two
expressions. The first is evaluated to determine the new
value of dot, and the second is evaluated to determine a
repeat count for the first dcmd in the pipeline. This
dcmd is executed count times before the next dcmd in the
pipeline is executed. The repeat count only applies to
the first dcmd in the pipeline.
, expression pipeline [! word ...] [ ; ]
If the initial expression is omitted, dot is not modi-
fied but the first dcmd in the pipeline is repeated
according to the value of the expression.
expression [! word ...] [ ; ]
A command can consist only of an arithmetic expression.
The expression is evaluated and the dot variable is set
to its value, and then the previous dcmd and arguments
are executed using the new value of dot.
SunOS 5.10 Last change: 30 Nov 2005 4
User Commands mdb(1)
expression, expression [! word ...] [ ; ]
A command can consist only of a dot expression and
repeat count expression. After dot is set to the value
of the first expression, the previous dcmd and arguments
are repeatedly executed the number of times specified by
the value of the second expression.
, expression [! word ...] [ ; ]
If the initial expression is omitted, dot is not modi-
fied 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 fol-
lowed by the string formed by concatenating the words
after the ! character.
Comments
A word beginning with // causes that word and all the subse-
quent characters up to a NEWLINE to be ignored.
Arithmetic Expansion
Arithmetic expansion is performed when an mdb command is
preceded by an optional expression representing a start
address, or a start address and a repeat count. Arithmetic
expansion can also be performed to compute a numerical argu-
ment for a dcmd. An arithmetic expression can appear in an
argument list enclosed in square brackets preceded by a dol-
lar sign ($[ expression ]), and is replaced by the value of
the expression.
Expressions can contain any of the following special words:
integer The specified integer value. Integer
values can be prefixed with 0i or 0I
to indicate binary values, 0o or 0O
to indicate octal values, 0t or 0T
to indicate decimal values, and 0x
or 0X to indicate hexadecimal values
(the default).
SunOS 5.10 Last change: 30 Nov 2005 5
User Commands mdb(1)
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 con-
verting each character to a byte
equal to its ASCII value. Up to
eight characters can be specified in
a character constant. Characters are
packed into the integer in reverse
order (right-to-left) beginning at
the least significant byte.
<identifier The value of the variable named by
identifier.
identifier The value of the symbol named by
identifier.
(expression) The value of expression.
. The value of dot.
& The most recent value of dot used to
execute a dcmd.
+ The value of dot incremented by the
current increment.
^ The value of dot decremented by the
current increment.
SunOS 5.10 Last change: 30 Nov 2005 6
User Commands mdb(1)
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 pre-
cedence than binary operators. The unary operators are:
#expression Logical negation.
~expression Bitwise complement.
-expression Integer negation.
%expression The value of a pointer-sized quan-
tity at the object file location
corresponding to virtual address
expression in the target's virtual
address space.
%/[csil]/expression The value of a char, short, int, or
long-sized quantity at the object
file location corresponding to vir-
tual 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 vir-
tual address expression in the
target's virtual address space.
*expression The value of a pointer-sized quan-
tity at virtual address expression
in the target's virtual address
space.
SunOS 5.10 Last change: 30 Nov 2005 7
User Commands mdb(1)
*/[csil]/expression The value of a char, short, int, or
long-sized quantity at virtual
address expression in the target's
virtual address space.
*/[1248]/expression The value of a one, two, four, or
eight-byte quantity at virtual
address expression in the target's
virtual address space.
Binary operators are left associative and have lower pre-
cedence 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.
SunOS 5.10 Last change: 30 Nov 2005 8
User Commands mdb(1)
!= Logical inequality.
& Bitwise AND.
^ Bitwise exclusive OR.
| Bitwise inclusive OR.
Quoting
Each metacharacter described above (see Syntax) terminates a
word unless quoted. Characters can be quoted (forcing mdb to
interpret each character as itself without any special sig-
nificance) by enclosing them in a pair of single (' ') or
double (" ") quote marks. A single quote cannot appear
within single quotes. Inside double quotes, mdb recognizes
the C programming language character escape sequences.
Shell Escapes
The ! character can be used to create a pipeline between an
mdb command and the user's shell. If the $SHELL environment
variable is set, mdb forks and execs this program for shell
escapes; otherwise /bin/sh is used. The shell is invoked
with the -c option followed by a string formed by con-
catenating the words after the ! character. The ! character
takes precedence over all other metacharacters, except semi-
colon (;) and NEWLINE. Once a shell escape is detected, the
remaining characters up to the next semicolon or NEWLINE are
passed as is to the shell. The output of shell commands can
not be piped to mdb dcmds. Commands executed by a shell
escape have their output sent directly to the terminal, not
to mdb.
Variables
A variable is a variable name, a corresponding integer
value, and a set of attributes. A variable name is a
sequence of letters, digits, underscores, or periods. A
variable can be assigned a value using the > dcmd or
::typeset dcmd, and its attributes can be manipulated using
the ::typeset dcmd. Each variable's value is represented as
a 64-bit unsigned integer. A variable can have one or more
of the following attributes: read-only (cannot be modified
by the user), persistent (cannot be unset by the user), and
tagged (user-defined indicator).
SunOS 5.10 Last change: 30 Nov 2005 9
User Commands mdb(1)
The following variables are defined as persistent:
0 The most recent value printed using the /,
\, ?, or = dcmd.
9 The most recent count used with the $< dcmd.
b The virtual address of the base of the data
section.
d The size of the data section in bytes.
e The virtual address of the entry point.
m The initial bytes (magic number) of the
target's primary object file, or zero if no
object file has been read yet.
t The size of the text section in bytes.
hits The count of the number of times the matched
software event specifier has been matched.
See Event Callbacks, below.
thread The thread identifier of the current
representative thread. The value of the
identifier depends on the threading model
used by the current target. See Thread Sup-
port, below.
In addition, the mdb kernel and process targets export the
current values of the representative thread's register set
as named variables. The names of these variables depend on
SunOS 5.10 Last change: 30 Nov 2005 10
User Commands mdb(1)
the target's platform and instruction set architecture.
Symbol Name Resolution
As explained in the Syntax description above, a symbol iden-
tifier present in an expression context evaluates to the
value of this symbol. The value typically denotes the vir-
tual address of the storage associated with the symbol in
the target's virtual address space. A target can support
multiple symbol tables including, but not limited to, a pri-
mary 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 typically
searches the primary executable's symbol tables first, and
then one or more of the other symbol tables. Notice that ELF
symbol tables only contain entries for external, global, and
static symbols; automatic symbols do not appear in the sym-
bol tables processed by mdb.
Additionally, mdb provides a private user-defined symbol
table that is searched prior to any of the target symbol
tables. The private symbol table is initially empty, and can
be manipulated using the ::nmadd and ::nmdel dcmds. The ::nm
-P option can be used to display the contents of the private
symbol table. The private symbol table allows the user to
create symbol definitions for program functions or data that
were either missing from the original program or stripped
out. These definitions are then used whenever mdb converts a
symbolic name to an address, or an address to the nearest
symbol.
As targets contain multiple symbol tables, and each symbol
table can include symbols from multiple object files, dif-
ferent symbols with the same name can exist. mdb uses the
backquote (`) character as a symbol name scoping operator to
allow the programmer to obtain the value of the desired sym-
bol in this situation. The programmer can specify the scope
used to resolve a symbol name as either: object`name, or
file`name, or object`file`name. The object identifier refers
to the name of a load object. The file identifier refers to
the basename of a source file that has a symbol of type
STT_FILE in the specified object's symbol table. The object
identifier's interpretation depends on the target type.
The mdb kernel target expects object to specify the basename
of a loaded kernel module. For example, the symbol name
specfs`_init
evaluates to the value of the _init symbol in the specfs
kernel module.
SunOS 5.10 Last change: 30 Nov 2005 11
User Commands mdb(1)
The mdb process target expects object to specify the name of
the executable or of a loaded shared library. It can take
any of the following forms:
1. An exact match (that is, a full pathname):
/usr/lib/libc.so.1
2. An exact basename match: libc.so.1
3. An initial basename match up to a ``.'' suffix: libc.so
or libc
4. The literal string a.out is accepted as an alias for the
executable.
The process target also accepts any of the four forms
described above preceded by an optional link-map id (lmid).
The lmid prefix is specified by an initial "LM" followed by
the link-map id in hexadecimal followed by an additional
backquote. For example, the symbol name
LM0`libc.so.1`_init
evaluates to the value of the _init symbol in the libc.so.1
library that is loaded on link-map 0 (LM_ID_BASE). The
link-map specifier can be necessary to resolve symbol naming
conflicts in the event that the same library is loaded on
more than one link map. For more information on link maps,
refer to the Linker and Libraries Guide and dlopen(3C).
Link-map identifiers are displayed when symbols are printed
according to the setting of the showlmid option, as
described under OPTIONS.
In the case of a naming conflict between symbols and hexade-
cimal integer values, mdb attempts to evaluate an ambiguous
token as a symbol first, before evaluating it as an integer
value. For example, the token f can either refer to the
decimal integer value 15 specified in hexadecimal (the
default base), or to a global variable named f in the
target's symbol table. If a symbol with an ambiguous name is
present, the integer value can be specified by using an
explicit 0x or 0X prefix.
dcmd and Walker Name Resolution
As described earlier, each mdb dmod provides a set of dcmds
and walkers. dcmds and walkers are tracked in two distinct,
global namespaces. mdb also keeps track of a dcmd and walker
namespace associated with each dmod. Identically named dcmds
SunOS 5.10 Last change: 30 Nov 2005 12
User Commands mdb(1)
or walkers within a given dmod are not allowed: a dmod with
this type of naming conflict fails to load. Name conflicts
between dcmds or walkers from different dmods are allowed in
the global namespace. In the case of a conflict, the first
dcmd or walker with that particular name to be loaded is
given precedence in the global namespace. Alternate defini-
tions are kept in a list in load order. The backquote char-
acter (`) 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 visibil-
ity. The current definition of a dcmd or walker can be
determined using the ::which dcmd, described below. The glo-
bal definition list can be displayed using the ::which -v
option.
dcmd Pipelines
dcmds can be composed into a pipeline using the | operator.
The purpose of a pipeline is to pass a list of values, typi-
cally virtual addresses, from one dcmd or walker to another.
Pipeline stages might be used to map a pointer from one type
of data structure to a pointer to a corresponding data
structure, to sort a list of addresses, or to select the
addresses of structures with certain properties.
mdb executes each dcmd in the pipeline in order from left to
right. The leftmost dcmd is executed using the current value
of dot, or using the value specified by an explicit expres-
sion 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 stan-
dard input. Each line must consist of an arithmetic expres-
sion terminated by a NEWLINE or semicolon (;). The value of
SunOS 5.10 Last change: 30 Nov 2005 13
User Commands mdb(1)
the expression is appended to the list of values associated
with the pipe. If a syntax error is detected, the pipeline
is aborted.
When the dcmd to the left of a | operator completes, the
list of values associated with the pipe is then used to
invoke the dcmd to the right of the | operator. For each
value in the list, dot is set to this value and the right-
hand dcmd is executed. Only the rightmost dcmd in the pipe-
line 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 sig-
nal aborts the command that is currently executing. The
debugger intercepts and provides special handling for the
ILL, TRAP, EMT, FPE, BUS, and SEGV signals. If any of these
signals are generated asynchronously (that is, delivered
from another process using kill(2)), mdb restores the signal
to its default disposition and dump core. However, if any of
these signals are generated synchronously by the debugger
process itself and a dcmd from an externally loaded dmod is
currently executing, and standard input is a terminal, mdb
provides a menu of choices allowing the user to force a core
dump, quit without producing a core dump, stop for attach by
a debugger, or attempt to resume. The resume option aborts
all active commands and unload the dmod whose dcmd was
active at the time the fault occurred. It can then be subse-
quently re-loaded by the user. The resume option provides
limited protection against buggy dcmds. Refer to WARNINGS,
Use of the Error Recovery Mechanism, below for information
about the risks associated with the resume option.
Command Re-entry
The text of the last HISTSIZE (default 128) commands
entered from a terminal device are saved in memory. The in-
line editing facility, described next, provides key mappings
for searching and fetching elements from the history list.
In-line Editing
If standard input is a terminal device, mdb provides some
simple emacs-style facilities for editing the command line.
The search, previous, and next commands in edit mode provide
access to the history list. Only strings, not patterns, are
matched when searching. In the table below, the notation for
control characters is caret (^) followed by a character
shown in upper case. The notation for escape sequences is M-
followed by a character. For example, M-f (pronounced meta-
eff) is entered by depressing <ESC> followed by 'f', or by
depressing <Meta> followed by 'f' on keyboards that support
SunOS 5.10 Last change: 30 Nov 2005 14
User Commands mdb(1)
a Meta key. A command line is committed and executed using
RETURN or NEWLINE. The edit commands are:
^F Move cursor forward (right) one character.
M-f Move cursor forward one word.
^B Move cursor backward (left) one character.
M-b Move cursor backward one word.
^A Move cursor to start of line.
^E Move cursor to end of line.
^D Delete current character, if the current
line is not empty. If the current line is
empty, ^D denotes EOF and the debugger
exits.
M-^H (Meta-backspace) Delete previous word.
^K Delete from the cursor to the end of the
line.
^L Clear the screen and reprint the current
line.
^T Transpose current character with next char-
acter.
SunOS 5.10 Last change: 30 Nov 2005 15
User Commands mdb(1)
^N Fetch the next command from the history.
Each time ^N is entered, the next command
forward in time is retrieved.
^P Fetch the previous command from the history.
Each time ^P is entered, the next command
backward in time is retrieved.
^R[string] Search backward in the history for a previ-
ous command line containing string. The
string should be terminated by a RETURN or
NEWLINE. If string is omitted, the previous
history element containing the most recent
string is retrieved.
The editing mode also interprets the following user-defined
sequences as editing commands. User defined sequences can be
read or modified using the stty(1) command.
erase User defined erase character (usually ^H or
^?). Delete previous character.
intr User defined interrupt character (usually
^C). Abort the current command and print a
new prompt.
kill User defined kill character (usually ^U).
Kill the entire current command line.
quit User defined quit character (usually ^\).
Quit the debugger.
suspend User defined suspend character (usually ^Z).
Suspend the debugger.
SunOS 5.10 Last change: 30 Nov 2005 16
User Commands mdb(1)
werase User defined word erase character (usually
^W). Erase the preceding word.
On keyboards that support an extended keypad with arrow
keys, mdb interprets these keystrokes as editing commands:
up-arrow Fetch the previous command from the history
(same as ^P).
down-arrow Fetch the next command from the history
(same as ^N).
left-arrow Move cursor backward one character (same as
^B).
right-arrow Move cursor forward one character (same as
^F).
Output Pager
mdb provides a built-in output pager. The output pager is
enabled if the debugger's standard output is a terminal dev-
ice. Each time a command is executed, mdb pauses after one
screenful of output is produced and displays a pager prompt:
>> More [<space>, <cr>, q, n, c, a] ?
The following key sequences are recognized by the pager:
SPACE Display the next screenful of out-
put.
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 com-
plete.
SunOS 5.10 Last change: 30 Nov 2005 17
User Commands mdb(1)
n, N, NEWLINE, RETURN Display the next line of output.
q, Q, ^C, ^\ Quit (abort) the current dcmd only.
Formatting dcmds
The /, \, ?, and = metacharacters are used to denote the
special output formatting dcmds. Each of these dcmds accepts
an argument list consisting of one or more format charac-
ters, repeat counts, or quoted strings. A format character
is one of the ASCII characters shown in the table below.
Format characters are used to read and format data from the
target. A repeat count is a positive integer preceding the
format character that is always interpreted in base 10
(decimal). A repeat count can also be specified as an
expression enclosed in square brackets preceded by a dollar
sign ($[ ]). A string argument must be enclosed in double-
quotes (" "). No blanks are necessary between format argu-
ments.
The formatting dcmds are:
/ Display data from the target's virtual address
space starting at the virtual address specified by
dot.
\ Display data from the target's physical address
space starting at the physical address specified by
dot.
? Display data from the target's primary object file
starting at the object file location corresponding
to the virtual address specified by dot.
= Display the value of dot itself in each of the
specified data formats. The = dcmd is therefore
useful for converting between bases and performing
arithmetic.
In addition to dot, mdb keeps track of another global value
called the increment. The increment represents the distance
SunOS 5.10 Last change: 30 Nov 2005 18
User Commands mdb(1)
between dot and the address following all the data read by
the last formatting dcmd. For example, if a formatting dcmd
is executed with dot equal to address A, and displays a 4-
byte integer, then after this dcmd completes, dot is still
A, but the increment is set to 4. The + character (described
under Arithmetic Expansion above) would now evaluate to the
value A + 4, and could be used to reset dot to the address
of the next data object for a subsequent dcmd.
Most format characters increase the value of the increment
by the number of bytes corresponding to the size of the data
format, shown in the table. The table of format characters
can be displayed from within mdb using the ::formats dcmd.
The format characters are:
+ increment dot by the count (variable size)
- decrement dot by the count (variable size)
B hexadecimal int (1 byte)
C character using C character notation (1 byte)
D decimal signed int (4 bytes)
E decimal unsigned long long (8 bytes)
F double (8 bytes)
G octal unsigned long long (8 bytes)
H swap bytes and shorts (4 bytes)
I address and disassembled instruction (variable
size)
J hexadecimal long long (8 bytes)
K hexadecimal uintptr_t (4 or 8 bytes)
N newline
O octal unsigned int (4 bytes)
P symbol (4 or 8 bytes)
Q octal signed int (4 bytes)
R binary int (8 bytes)
S string using C string notation (variable size)
T horizontal tab
U decimal unsigned int (4 bytes)
V decimal unsigned int (1 byte)
W default radix unsigned int (4 bytes)
X hexadecimal int (4 bytes)
Y decoded time32_t (4 bytes)
Z hexadecimal long long (8 bytes)
^ decrement dot by increment * count (variable
size)
a dot as symbol+offset
b octal unsigned int (1 byte)
c character (1 byte)
d decimal signed short (2 bytes)
e decimal signed long long (8 bytes)
f float (4 bytes)
g octal signed long long (8 bytes)
h swap bytes (2 bytes)
SunOS 5.10 Last change: 30 Nov 2005 19
User Commands mdb(1)
i disassembled instruction (variable size)
n newline
o octal unsigned short (2 bytes)
p symbol (4 or 8 bytes)
q octal signed short (2 bytes)
r whitespace
s raw string (variable size)
t horizontal tab
u decimal unsigned short (2 bytes)
v decimal signed int (1 byte)
w default radix unsigned short (2 bytes)
x hexadecimal short (2 bytes)
y decoded time64_t (8 bytes)
The /, \, and ? formatting dcmds can also be used to write
to the target's virtual address space, physical address
space, or object file by specifying one of the following
modifiers as the first format character, and then specifying
a list of words that are either immediate values or expres-
sions enclosed in square brackets preceded by a dollar sign
($[ ]).
The write modifiers are:
v Write the lowest byte of the value of each expres-
sion to the target beginning at the location speci-
fied by dot.
w Write the lowest two bytes of the value of each
expression to the target beginning at the location
specified by dot.
W Write the lowest 4 bytes of the value of each
expression to the target beginning at the location
specified by dot.
Z Write the complete 8 bytes of the value of each
expression to the target beginning at the location
specified by dot.
The /, \, and ? formatting dcmds can also be used to search
for a particular integer value in the target's virtual
address space, physical address space, and object file,
SunOS 5.10 Last change: 30 Nov 2005 20
User Commands mdb(1)
respectively, by specifying one of the following modifiers
as the first format character, and then specifying a value
and optional mask. The value and mask are each specified as
either immediate values or expressions enclosed in square
brackets preceded by a dollar sign. If only a value is
specified, mdb reads integers of the appropriate size and
stops at the address containing the matching value. If a
value V and mask M are specified, mdb reads integers of the
appropriate size and stops at the address containing a value
X where (X & M) == V. At the completion of the dcmd, dot is
updated to the address containing the match. If no match is
found, dot is left at the last address that was read.
The search modifiers are:
l Search for the specified 2-byte value.
L Search for the specified 4-byte value.
M Search for the specified 8-byte value.
Notice that for both user and kernel targets, an address
space is typically composed of a set of discontiguous seg-
ments. 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 exe-
cution 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 pro-
cess can be started from within the debugger using ::run, or
mdb can attach to an existing process using :A, ::attach, or
the -p command-line option, as described below. A list of
traced software events can be specified by the user. Each
time a traced event occurs in the target process, all
threads in the target stop, the thread that triggered the
event is chosen as the representative thread, and control
returns to the debugger. Once the target program is set 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 par-
ticular signal.
A software event specifier is a description of a class of
software events that is used by the debugger to instrument
SunOS 5.10 Last change: 30 Nov 2005 21
User Commands mdb(1)
the target program in order to observe these events. The
::events dcmd is used to list the software event specifiers.
A set of standard properties is associated with each event
specifier, as described under ::events, below.
The debugger can observe a variety of different software
events, including breakpoints, watchpoints, signals, machine
faults, and system calls. New specifiers can be created
using ::bp, ::fltbp, ::sigbp, ::sysbp, or ::wp. Each specif-
ier 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 specif-
iers for the same event can be created, each with different
callbacks and properties. The current list of traced events
and the properties of the corresponding event specifiers can
be displayed using the ::events dcmd. The event specifier
properties are defined as part of the description of the
::events and ::evset dcmds, below.
The execution control built-in dcmds, described below, are
always available, but issues an error message indicating
they are not supported if applied to a target that does not
support execution control. For more information about the
interaction of exec, attach, release, and job control with
debugger execution control, refer to NOTES, below.
Event Callbacks
The ::evset dcmd and event tracing dcmds allow you to asso-
ciate an event callback (using the -c option) with each
event specifier. The event callbacks are strings that
represent mdb commands to execute when the corresponding
event occurs in the target. These commands are executed as
if they had been typed at the command prompt. Before execut-
ing each callback, the dot variable is set to the value of
the representative thread's program counter and the "hits"
variable is set to the number of times this specifier has
been matched, including the current match.
If the event callbacks themselves contain one or more com-
mands to continue the target (for example, ::cont or
::step), these commands do not immediately continue the tar-
get 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 call-
back, 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 con-
tinue operations are requested, the operation with the
highest precedence determines what type of continue occurs.
The order of precedence from highest to lowest is: step,
SunOS 5.10 Last change: 30 Nov 2005 22
User Commands mdb(1)
step-over (next), step-out, continue.
Thread Support
mdb provides facilities to examine the stacks and registers
of each thread associated with the target. The persistent
"thread" variable contains the current representative thread
identifier. The format of the thread identifier depends on
the target. The ::regs and ::fpregs dcmds can be used to
examine the register set of the representative thread, or of
another thread if its register set is currently available.
In addition, the register set of the representative thread
is exported as a set of named variables. The user can
modify the value of one or more registers by applying the >
dcmd to the corresponding named variable.
The mdb kernel target exports the virtual address of the
corresponding internal thread structure as the identifier
for a given thread. The Solaris Modular Debugger Guide pro-
vides more information on debugging support for threads in
the Solaris kernel. The mdb process target provides proper
support for examination of multi-threaded user processes
that use the native lwp_* interfaces, /usr/lib/libthread.so
or /usr/lib/lwp/libthread.so. When debugging a live user
process, mdb detects if a single threaded process dlopens or
closes libthread and automatically adjusts its view of the
threading model on-the-fly. The process target thread iden-
tifiers corresponds to either the lwpid_t, thread_t, or
pthread_t of the representative, depending on the threading
model used by the application.
If mdb is debugging a user process target and the target
makes use of compiler-supported thread-local storage, mdb
automatically evaluates symbol names referring to thread-
local storage to the address of the storage corresponding to
the current representative thread. The ::tls built-in dcmd
can be used to display the value of the symbol for threads
other than the representative thread.
Built-in dcmds
mdb provides a set of built-in dcmds that are always
defined. Some of these dcmds are only applicable to certain
targets: if a dcmd is not applicable to the current target,
it fails and prints a message indicating "command is not
supported by current target". In many cases, mdb provides a
mnemonic equivalent (::identifier) for the legacy adb(1)
dcmd names. For example, ::quit is provided as the
equivalent of $q. Programmers who are experienced with
adb(1) or who appreciate brevity or arcana can prefer the $
or : forms of the built-ins. Programmers who are new to mdb
might prefer the more verbose :: form. The built-ins are
shown in alphabetical order. If a $ or : form has a ::iden-
tifier equivalent, it is shown underneath the ::identifier
SunOS 5.10 Last change: 30 Nov 2005 23
User Commands mdb(1)
form. The built-in dcmds are:
> variable-name
>/modifier/variable-name
Assign the value of dot to the specified named variable.
Some variables are read-only and can not be modified.
If the > is followed by a modifier character surrounded
by / /, then the value is modified as part of the
assignment. The modifier characters are:
c unsigned char quantity (1-byte)
s unsigned short quantity (2-byte)
i unsigned int quantity (4-byte)
l unsigned long quantity (4-byte in 32-bit, 8-
byte in 64-bit)
Notice that these operators do not perform a cast.
Instead, they fetch the specified number of low-order
bytes (on little-endian architectures) or high-order
bytes (big-endian architectures). Modifiers are provided
for backwards compatibility; the mdb */modifier/ and
%/modifier/ syntax should be used instead.
$< macro-name
Read and execute commands from the specified macro file.
The filename can be given as an absolute or relative
path. If the filename is a simple name (that is, if it
does not contain a '/'), mdb searches for it in the
macro file include path. If another macro file is
currently being processed, this file is closed and
replaced with the new file.
$<< macro-name
SunOS 5.10 Last change: 30 Nov 2005 24
User Commands mdb(1)
Read and execute commands from the specified macro file
(as with $<), but do not close the current open macro
file.
$?
Print the process-ID and current signal of the target if
it is a user process or core file, and then print the
general register set of the representative thread.
[ address ] $C [ count ]
Print a C stack backtrace, including stack frame pointer
information. If the dcmd is preceded by an explicit
address, a backtrace beginning at this virtual memory
address is displayed. Otherwise the stack of the
representative thread is displayed. If an optional count
value is given as an argument, no more than count argu-
ments are displayed for each stack frame in the output.
[ base ] $d
Get or set the default output radix. If the dcmd is pre-
ceded by an explicit expression, the default output
radix is set to the given base; otherwise the current
radix is printed in base 10 (decimal). The default radix
is base 16 (hexadecimal).
$e
Print a list of all known external (global) symbols of
type object or function, the value of the symbol, and
the first 4 (32-bit mdb) or 8 (64-bit mdb) bytes stored
at this location in the target's virtual address space.
The ::nm dcmd provides more flexible options for
displaying symbol tables.
$P prompt-string
Set the prompt to the specified prompt-string. The
default prompt is '> '. The prompt can also be set using
::set -P or the -P command-line option.
SunOS 5.10 Last change: 30 Nov 2005 25
User Commands mdb(1)
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 dis-
tance 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 list-
ing variables.
width $w
Set the output page width to the specified value. Typi-
cally, 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 exe-
cuted with the -w option on the command line. Write mode
can also be enabled with the ::set -w option.
[ pid ] ::attach [ core | pid ]
[ pid ] :A [ core | pid ]
If the user process target is active, attach to and
debug the specified process-ID or core file. The core
file pathname should be specified as a string argument.
The process-ID can be specified as the string argument,
or as the value of the expression preceding the dcmd.
Recall that the default base is hexadecimal, so decimal
PIDs obtained using pgrep(1) or ps(1) should be preceded
with "0t" when specified as expressions.
[address] ::bp [+/-dDesT] [-c cmd] [-n count] sym ...
address :b [cmd ...]
SunOS 5.10 Last change: 30 Nov 2005 26
User Commands mdb(1)
Set a breakpoint at the specified locations. The ::bp
dcmd sets a breakpoint at each address or symbol speci-
fied, including an optional address specified by an
explicit expression preceding the dcmd, and each string
or immediate value following the dcmd. The arguments can
either be symbol names or immediate values denoting a
particular virtual address of interest. If a symbol name
is specified, it can refer to a symbol that cannot yet
be evaluated in the target process. That is, it can con-
sist of an object name and function name in a load
object that has not yet been opened. In this case, the
breakpoint is deferred and is not active in the target
until an object matching the given name is loaded. The
breakpoint is automatically enabled when the load object
is opened. Breakpoints on symbols defined in a shared
library should always be set using a symbol name and not
using an address expression, as the address can refer to
the corresponding Procedure Linkage Table (PLT) entry
instead of the actual symbol definition. Breakpoints set
on PLT entries can be overwritten by the run-time link-
editor when the PLT entry is subsequently resolved to
the actual symbol definition. The -d, -D, -e, -s, -t,
-T, -c, and -n options have the same meaning as they do
for the ::evset dcmd, as described below. If the :b form
of the dcmd is used, a breakpoint is only set at the
virtual address specified by the expression preceding
the dcmd. The arguments following the :b dcmd are con-
catenated together to form the callback string. If this
string contains meta-characters, it must be quoted.
::cat filename ...
Concatenate and display files. Each filename can be
specified as a relative or absolute pathname. The file
contents are printed to standard output, but are not
passed to the output pager. This dcmd is intended to be
used with the | operator; the programmer can initiate a
pipeline using a list of addresses stored in an external
file.
::cont [ SIG ]
:c [ SIG ]
Suspend the debugger, continue the target program, and
wait for it to terminate or stop following a software
event of interest. If the target is already running
because the debugger was attached to a running program
SunOS 5.10 Last change: 30 Nov 2005 27
User Commands mdb(1)
with the -o nostop option enabled, this dcmd simply
waits for the target to terminate or stop after an event
of interest. If an optional signal name or number (see
signal.h(3HEAD)) is specified as an argument, the signal
is immediately delivered to the target as part of resum-
ing its execution. If the SIGINT signal is traced, con-
trol 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 contin-
ued. If no target program is currently running, ::cont
starts a new program running as if by ::run.
address ::context
address $p
Context switch to the specified process. A context
switch operation is only valid when using the kernel
target. The process context is specified using the
address of its proc structure in the kernel's virtual
address space. The special context address "0" is used
to denote the context of the kernel itself. mdb can only
perform a context switch when examining a crash dump if
the dump contains the physical memory pages of the
specified user process (as opposed to just kernel
pages). The kernel crash dump facility can be configured
to dump all pages or the pages of the current user pro-
cess using dumpadm(1M). The ::status dcmd can be used to
display the contents of the current crash dump.
When the user requests a context switch from the kernel
target, mdb constructs a new target representing the
specified user process. Once the switch occurs, the new
target interposes its dcmds at the global level: thus
the / dcmd now formats and displays data from the vir-
tual address space of the user process, the ::mappings
dcmd displays the mappings in the address space of the
user process, and so on. The kernel target can be
restored by executing 0::context.
::dcmds
List the available dcmds and print a brief description
for each one.
SunOS 5.10 Last change: 30 Nov 2005 28
User Commands mdb(1)
[ address ] ::delete [ id | all ]
[ address ] :d [ id | all ]
Delete the event specifiers with the given id number.
The id number argument is interpreted in decimal by
default. If an optional address is specified preceding
the dcmd, all event specifiers that are associated with
the given virtual address are deleted (for example, all
breakpoints or watchpoints affecting that address). If
the special argument "all" is given, all event specif-
iers are deleted, except those that are marked sticky (T
flag). The ::events dcmd displays the current list of
event specifiers.
[ address ] ::dis [ -fw ] [ -n count ] [ address ]
Disassemble starting at or around the address specified
by the final argument, or the current value of dot. If
the address matches the start of a known function, the
entire function is disassembled. Otherwise, a "window"
of instructions before and after the specified address
is printed in order to provide context. By default,
instructions are read from the target's virtual address
space. If the -f option is present, instructions are
read from the target's object file instead. The -f
option is enabled by default if the debugger is not
currently attached to a live process, core file, or
crash dump. The -w option can be used to force
"window"-mode, even if the address is the start of a
known function. The size of the window defaults to ten
instructions; the number of instructions can be speci-
fied explicitly using the -n option.
::disasms
List the available disassembler modes. When a target is
initialized, mdb attempts to select the appropriate
disassembler mode. The user can change the mode to any
of the modes listed using the ::dismode dcmd.
::dismode [ mode ]
$V [ mode ]
Get or set the disassembler mode. If no argument is
specified, print the current disassembler mode. If a
SunOS 5.10 Last change: 30 Nov 2005 29
User Commands mdb(1)
mode argument is specified, switch the disassembler to
the specified mode. The list of available disassemblers
can be displayed using the ::disasms dcmd.
::dmods [ -l ] [ module-name ]
List the loaded debugger modules. If the -l option is
specified, the list of the dcmds and walkers associated
with each dmod is printed below its name. The output
can be restricted to a particular dmod by specifying its
name as an additional argument.
[ address ] ::dump [ -eqrstu ] [ -f|-p ]
[ -g bytes ] [ -w paragraphs ]
Print a hexadecimal and ASCII memory dump of the 16-byte
aligned region of memory containing the address speci-
fied by dot. If a repeat count is specified for ::dump,
this is interpreted as a number of bytes to dump rather
than a number of iterations. The ::dump dcmd also recog-
nizes the following options:
-e Adjusts for endian-ness. The -e option
assumes 4-byte words. The -g option can
be used to change the default word size.
-f Reads data from the object file location
corresponding to the given virtual
address instead of from the target's
virtual address space. The -f option is
enabled by default if the debugger is
not currently attached to a live pro-
cess, 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.
SunOS 5.10 Last change: 30 Nov 2005 30
User Commands mdb(1)
-p Interprets address as a physical address
location in the target's address space
instead of a virtual address.
-q Does not print an ASCII decoding of the
data.
-r Numbers lines relative to the start
address instead of with the explicit
address of each line. This option
implies the -u option.
-s Elides repeated lines.
-t Only reads from and displays the con-
tents of the specified addresses,
instead of reading and printing entire
lines.
-u Unaligns output instead of aligning the
output at a paragraph boundary.
-w paragraphs Displays paragraphs at 16-byte para-
graphs per line. The default number of
paragraphs is one. The maximum value
accepted for -w is 16.
::echo [ string | value ...]
Print the arguments separated by blanks and terminated
by a NEWLINE to standard output. Expressions enclosed in
$[ ] is evaluated to a value and printed in the default
base.
::eval command
SunOS 5.10 Last change: 30 Nov 2005 31
User Commands mdb(1)
Evaluate and execute the specified string as a command.
If the command contains metacharacters or whitespace, it
should be enclosed in double or single quotes.
::events [ -av ]
$b [ -av ]
Display the list of software event specifiers. Each
event specifier is assigned a unique ID number that can
be used to delete or modify it at a later time. The
debugger can also have its own internal events enabled
for tracing. These events are only be displayed if the
-a option is present. If the -v option is present, a
more verbose display, including the reason for any
specifier inactivity, are shown. Here is some sample
output:
> ::events
ID S TA HT LM Description Action
----- - -- -- -- -------------------------------- ------
[ 1 ] - T 1 0 stop on SIGINT -
[ 2 ] - T 0 0 stop on SIGQUIT -
[ 3 ] - T 0 0 stop on SIGILL -
...
[ 11] - T 0 0 stop on SIGXCPU -
[ 12] - T 0 0 stop on SIGXFSZ -
[ 13] - 2 0 stop at libc`printf ::echo printf
>
The following table explains the meaning of each column.
A summary of this information is available using ::help
events.
ID The event specifier identifier. The
identifier is shown in square brackets [
] if the specifier is enabled, in
parentheses ( ) if the specifier is dis-
abled, or in angle brackets < > if the
target program is currently stopped on
an event that matches the given specif-
ier.
S The event specifier state. The state is
one of the following symbols:
SunOS 5.10 Last change: 30 Nov 2005 32
User Commands mdb(1)
- The event specifier is idle.
When no target program is run-
ning, all specifiers are idle.
When the target program is run-
ning, a specifier can be idle
if it cannot be evaluated (for
example, a deferred breakpoint
in a shared object that is not
yet loaded).
+ The event specifier is active.
When the target is continued,
events of this type is detected
by the debugger.
* The event specifier is armed.
This state means that the tar-
get is currently running with
instrumentation for this type
of event. This state is only
visible if the debugger is
attached to a running program
with the -o nostop option.
! The event specifier was not
armed due to an operating sys-
tem error. The ::events -v
option can be used to display
more information about the rea-
son the instrumentation failed.
TA The Temporary, Sticky, and Automatic
event specifier properties. One or more
of the following symbols can be shown:
t The event specifier is tem-
porary, and is deleted the next
time the target stops, regard-
less of whether it is matched.
SunOS 5.10 Last change: 30 Nov 2005 33
User Commands mdb(1)
T The event specifier is sticky,
and is not be deleted by
::delete all or :z. The specif-
ier can be deleted by expli-
citly specifying its id number
to ::delete.
d The event specifier is automat-
ically disabled when the hit
count is equal to the hit
limit.
D The event specifier is automat-
ically 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 crea-
tion 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.
SunOS 5.10 Last change: 30 Nov 2005 34
User Commands mdb(1)
Action The callback string to execute when the
corresponding software event occurs.
This callback is executed as if it had
been typed at the command prompt.
[id] ::evset [+/-dDestT] [-c cmd] [-n count] id ...
Modify the properties of one or more software event
specifiers. The properties are set for each specifier
identified by the optional expression preceding the dcmd
and an optional list of arguments following the dcmd.
The argument list is interpreted as a list of decimal
integers, unless an explicit radix is specified. The
::evset dcmd recognizes the following options:
-d Disables the event specifier when the hit count
reaches the hit limit. If the +d form of the
option is given, this behavior is disabled.
Once an event specifier is disabled, the
debugger removes any corresponding instrumenta-
tion and ignores the corresponding software
events until the specifier is subsequently re-
enabled. If the -n option is not present, the
specifier is disabled immediately.
-D Deletes the event specifier when the hit count
reaches the hit limit. If the +D form of the
option is given, this behavior is disabled. The
-D option takes precedence over the -d option.
The hit limit can be configured using the -n
option.
-e Enables the event specifier. If the +e form of
the option is given, the specifier is disabled.
-s Stops the target program when the hit count
reaches the hit limit. If the +s form of the
option is given, this behavior is disabled. The
-s behavior tells the debugger to act as if the
::cont were issued following each execution of
the specifier's callback, except for the Nth
execution, where N is the current value of the
SunOS 5.10 Last change: 30 Nov 2005 35
User Commands mdb(1)
specifier's hit limit. The -s option takes pre-
cedence over both the -D option and the -d
option.
-t Marks the event specifier as temporary. Tem-
porary specifiers are automatically deleted the
next time the target stops, regardless of
whether it stopped as the result of a software
event corresponding to the given specifier. If
the +t form of the option is given, the tem-
porary marker is removed. The -t option takes
precedence over the -T option.
-T Marks the event specifier as sticky. Sticky
specifiers are not deleted by ::delete all or
:z. They can be deleted by specifying the
corresponding specifier ID as an explicit argu-
ment to ::delete. If the +T form of the option
is given, the sticky property is removed. The
default set of event specifiers are all ini-
tially marked sticky.
-c Executes the specified cmd string each time the
corresponding software event occurs in the tar-
get program. The current callback string can be
displayed using ::events.
-n Sets the current value of the hit limit to
count. If no hit limit is currently set and the
-n option does not accompany -s or D, the hit
limit is set to one.
A summary of this information is available using ::help
evset.
::files
$f
Print a list of the known source files (symbols of type
STT_FILE present in the various target symbol tables).
SunOS 5.10 Last change: 30 Nov 2005 36
User Commands mdb(1)
[flt] ::fltbp [+/-dDestT] [-c cmd] [-n count] flt ...
Trace the specified machine faults. The faults are iden-
tified using an optional fault number preceding the
dcmd, or a list of fault names or numbers (see
<sys/fault.h>) following the dcmd. The -d, -D, -e, -s,
-t, -T, -c, and -n options have the same meaning as they
do for the ::evset dcmd.
[ thread ] ::fpregs
[ thread ] $x, $X, $y, $Y
Print the floating-point register set of the representa-
tive thread. If a thread is specified, the floating
point registers of that thread are displayed. The thread
expression should be one of the thread identifiers
described under Thread Support, above.
::formats
List the available output format characters for use with
the /, \, ?, and = formatting dcmds. The formats and
their use is described under Formatting dcmds, above.
::grep command
Evaluate the specified command string, and then print
the old value of dot if the new value of dot is non-
zero. If the command contains whitespace or metacharac-
ters, 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 over-
view of the help facilities available in mdb. If a
dcmd-name is specified, mdb prints a usage summary for
that dcmd.
signal :i
SunOS 5.10 Last change: 30 Nov 2005 37
User Commands mdb(1)
If the target is a live user process, ignore the speci-
fied signal and allow it to be delivered transparently
to the target. All event specifiers that are tracing
delivery of the specified signal is deleted from the
list of traced events. By default, the set of ignored
signals is initialized to the complement of the set of
signals that cause a process to dump core by default
(see signal.h(3HEAD)), except for SIGINT, which is
traced by default.
$i
Display the list of signals that are ignored by the
debugger and that is handled directly by the target.
More information on traced signals can be obtained using
the ::events dcmd.
::kill
:k
Forcibly terminate the target if it is a live user pro-
cess. 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 tar-
get is a user process.
[ address ] ::list type member [ variable-name ]
Walk through the elements of a linked list data struc-
ture 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
SunOS 5.10 Last change: 30 Nov 2005 38
User Commands mdb(1)
is assumed to start at the current value of dot. The
type parameter must name a C struct or union type and is
used to describe the type of the list elements so that
mdb can read in objects of the appropriate size. The
member parameter is used to name the member of type that
contains a pointer to the next list element. The ::list
dcmd continues iterating until a NULL pointer is encoun-
tered, the first element is reached again (a circular
list), or an error occurs while reading an element. If
the optional variable-name is specified, the specified
variable is assigned the value returned at each step of
the walk when mdb invokes the next stage of a pipeline.
The ::list dcmd can only be used with objects that con-
tain symbolic debugging information designed for use
with mdb. Refer to NOTES, Symbolic Debugging Informa-
tion, below for more information.
::load [ -s ] module-name
Load the specified dmod. The module name can be given as
an absolute or relative path. If module-name is a simple
name (that is, does not contain a '/'), mdb searches for
it in the module library path. Modules with conflicting
names can not be loaded; the existing module must be
unloaded first. If the -s option is present, mdb remains
silent and not issue any error messages if the module is
not found or could not be loaded.
::log [ -d | [ -e ] filename ]
$> [ filename ]
Enable or disable the output log. mdb provides an
interactive logging facility where both the input com-
mands 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; other-
wise, logging is disabled. If the specified log file
already exists, mdb appends any new log output to the
file.
::map command
SunOS 5.10 Last change: 30 Nov 2005 39
User Commands mdb(1)
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 descrip-
tion of each mapping. If the dcmd is preceded by an
address, mdb only shows the mapping that contains the
given address. If a string name argument is given, mdb
only shows the mapping matching that description.
::next [ SIG ]
:e [ SIG ]
Step the target program one instruction, but step over
subroutine calls. If an optional signal name or number
(see signal.h(3HEAD)) is specified as an argument, the
signal is immediately delivered to the target as part of
resuming its execution. If no target program is
currently running, ::next starts a new program running
as if by ::run and stop at the first instruction.
[ address ] ::nm [ -DPdghnopuvx ] [ -t types ]
[ -f format ] [ object ]
Print the symbol tables associated with the current tar-
get. If an optional address preceding the dcmd is speci-
fied, only the symbol table entry for the symbol
corresponding to address is displayed. If an object is
specified, only the symbol table for this load object is
displayed. The ::nm dcmd also recognizes the following
options:
-D Prints .dynsym (dynamic symbol
table) instead of .symtab.
SunOS 5.10 Last change: 30 Nov 2005 40
User Commands mdb(1)
-P Prints the private symbol table
instead of .symtab.
-d Prints value and size fields in
decimal.
-g Prints only global symbols.
-h Suppresses the header line.
-n Sorts symbols by name.
-o Prints value and size fields in
octal.
-p Prints symbols as a series of
::nmadd commands. This option
can be used with -P to produce a
macro file that can be subse-
quently read into the debugger
with $<.
-u Prints only undefined symbols.
-v Sorts symbols by value.
-x Prints value and size fields in
hexadecimal.
-t type[,type ... ] Prints only symbols of the
specified type(s). The valid
type argument strings are:
SunOS 5.10 Last change: 30 Nov 2005 41
User Commands mdb(1)
noty STT_NOTYPE
objt STT_OBJECT
func STT_FUNC
sect STT_SECTION
file STT_FILE
comm STT_COMMON
tls STT_TLS
regi STT_SPARC_REGISTER
-f format[,format ... ] Prints only the specified symbol
information. The valid format
argument strings are:
ndx symbol table index
val symbol value
size size in bytes
SunOS 5.10 Last change: 30 Nov 2005 42
User Commands mdb(1)
type symbol type
bind binding
oth other
shndx section index
name symbol name
ctype C type for symbol (if
known)
obj object which defines
symbol
value ::nmadd [ -fo ] [ -e end ] [ -s size ] name
Add the specified symbol name to the private symbol
table. mdb provides a private, configurable symbol table
that can be used to interpose on the target's symbol
table, as described under Symbol Name Resolution above.
The ::nmadd dcmd also recognizes the following options:
-e Sets the size of the symbol to end - value.
-f Sets the type of the symbol to STT_FUNC.
-o Sets the type of the symbol to STT_OBJECT.
SunOS 5.10 Last change: 30 Nov 2005 43
User Commands mdb(1)
-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, show-
ing only those mappings that correspond to the primary
mapping (usually the text section) of each of the known
load objects. The -v option displays the version of each
load object. Version information is not available for
all load objects. Load objects without version informa-
tion is listed as having a version of "Unknown" in the
output for the -v option.
::offsetof type member
Print the offset of the specified member of the speci-
fied type. The type should be the name of a C structure.
The offset is printed in bytes, unless the member is a
bit-field, in which case the offset can be printed in
bits. The output is always suffixed with the appropriate
units for clarity. The type name can use the backquote
(`) scoping operator described under Symbol Name Resolu-
tion, above. The ::offsetof dcmd can only be used with
objects that contain symbolic debugging information
designed for use with mdb. Refer to NOTES, Symbolic
Debugging Information, below for more information.
address ::print [ -aCdiLptx ] [ -c lim ]
[ -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
SunOS 5.10 Last change: 30 Nov 2005 44
User Commands mdb(1)
type is a structured type, the ::print dcmd recursively
prints each member of the struct or union. If the type
argument is not present and a static or global
STT_OBJECT symbol matches the address, ::print infers
the appropriate type automatically. If the type argument
is specified, it can be followed by an optional list of
member expressions, in which case only those members and
submembers of the specified type are displayed. If type
contains other structured types, each member string can
refer to a sub-structure element by forming a list of
member names separated by period ('.') delimiters. The
::print dcmd can only be used with objects that contain
symbolic debugging information designed for use with
mdb. Refer to NOTES, Symbolic Debugging Information,
below for more information. After displaying the data
structure, ::print increments dot by the size of type in
bytes.
If the -a option is present, the address of each member
is displayed. If the -p option is present, ::print
interprets address as a physical memory address instead
of a virtual memory address. If the -t option is
present, the type of each member is displayed. If the -d
or -x options are present, all integers are displayed in
decimal (-d) or hexadecimal (-x). By default, a heuris-
tic is used to determine if the value should be
displayed in decimal or hexadecimal. The number of char-
acters in a character array that is read and displayed
as a string can be limited with the -c option. If the -C
option is present, no limit is enforced. The number of
elements in a standard array that is read and displayed
can be limited with the -l option. If the -L option is
present, no limit is enforced and all array elements are
shown. The default values for -c and -l can be modified
using ::set or the -o command-line option as described
under OPTIONS.
If the -i option is specified, the address value is
interpreted as an immediate value to be printed. You
must give a type with which to interpret the value. If
the type is smaller than 64 bits, the immediate value is
interpreted as if it were the size of the type. The -i
option cannot be used in conjunction with the -p option.
If the -a option is given, the addresses shown are byte
offsets starting at zero.
::quit
$q
SunOS 5.10 Last change: 30 Nov 2005 45
User Commands mdb(1)
Quit the debugger.
[ thread ] ::regs
[ thread ] $r
Print the general purpose register set of the represen-
tative 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 identif-
iers described under Thread Support, above.
::release [ -a ]
:R [ -a ]
Release the previously attached process or core file. If
the -a option is present, the process is released and
left stopped and abandoned. It can subsequently be con-
tinued by prun(1) (see proc(1)) or it can be resumed by
applying mdb or another debugger. By default, a released
process is forcibly terminated if it was created by mdb
using ::run, or it is released and set running if it was
attached to by mdb using the -p option or using the
::attach or :A dcmds.
::run [ args . . . ]
:r [ args . . . ]
Start a new target program running with the specified
arguments and attach to it. The arguments are not inter-
preted by the shell. If the debugger is already examin-
ing a live running program, it first detaches from this
program as if by ::release.
::set [ -wF ] [ +/-o option ] [ -s distance ] [ -I path ]
[ -L path ] [ -P prompt ]
Get or set miscellaneous debugger properties. If no
options are specified, the current set of debugger pro-
perties is displayed. The ::set dcmd recognizes the fol-
lowing options:
SunOS 5.10 Last change: 30 Nov 2005 46
User Commands mdb(1)
-F Forcibly takes over the next user process that
::attach is applied to, as if mdb had been exe-
cuted with the -F option on the command line.
-I Sets the default path for locating macro files.
The path argument can contain any of the spe-
cial 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 speci-
fied distance. Refer to the description of the
-s command-line option under OPTIONS for more
information.
-w Re-opens the target for writing, as if mdb had
been executed with the -w option on the command
line.
::showrev [ -pv ]
Display revision information for the hardware and
software. With no options specified, general system
SunOS 5.10 Last change: 30 Nov 2005 47
User Commands mdb(1)
information is displayed. The -v option displays version
information for all load objects, whereas the -p option
displays the version information only for the load
objects that have been installed on the system as part
of a patch. Version information is not available for all
load objects. Load objects without version information
is omitted from the output for the -p option and is
listed as having a version of "Unknown" in the output
for the -v option.
[signal] ::sigbp [+/-dDestT] [-c cmd] [-n count] SIG ...
[signal] :t [+/-dDestT] [-c cmd] [-n count] SIG ...
Trace delivery of the specified signals. The signals
are identified using an optional signal number preceding
the dcmd, or a list of signal names or numbers (see
signal.h(3HEAD)) following the dcmd. The -d, -D, -e,
-s, -t, -T, -c, and -n options have the same meaning as
they do for the ::evset dcmd. Initially, the set of sig-
nals that cause the process to dump core by default (see
signal.h(3HEAD)) and SIGINT are traced.
::sizeof type
Print the size of the specified type in bytes. The type
parameter can name a C struct, union, enum, fundamental
integer type, or a pointer to any of these types. The
type name can use the backquote (`) scoping operator
described under Symbol Name Resolution, above. The
::sizeof dcmd can only be used with objects that contain
symbolic debugging information designed for use with
mdb. Refer to NOTES, Symbolic Debugging Information,
below for more information.
[ address ] ::stack [ count ]
[ address ] $c [ count ]
Print a C stack backtrace. If the dcmd is preceded by an
explicit address, a backtrace beginning at this virtual
memory address is displayed. Otherwise the stack of the
representative thread is displayed. If an optional count
value is given as an argument, no more than count argu-
ments are displayed for each stack frame in the output.
SunOS 5.10 Last change: 30 Nov 2005 48
User Commands mdb(1)
::status
Print a summary of information related to the current
target.
::step [ over | out ] [ SIG ]
:s [ SIG ]
:u [ SIG ]
Step the target program one instruction. If an optional
signal name or number (see signal.h(3HEAD)) is specified
as an argument, the signal is immediately delivered to
the target as part of resuming its execution. If the
optional "over" argument is specified, ::step steps over
subroutine calls. The ::step over argument is the same
as the ::next dcmd. If the optional "out" argument is
specified, the target program continues until the
representative thread returns from the current function.
If no target program is currently running, ::step out
starts a new program running as if by ::run and stop at
the first instruction. The :s dcmd is the same as
::step. The :u dcmd is the same as ::step out.
[ syscall ] ::sysbp [ +/-dDestT ] [ -io ] [ -c cmd ]
[ -n count] syscall...
Trace entry to or exit from the specified system calls.
The system calls are identified using an optional system
call number preceding the dcmd, or a list of system call
names or numbers (see <sys/syscall.h>) following the
dcmd. If the -i option is specified (the default), the
event specifiers trigger on entry into the kernel for
each system call. If the -o option is specified, the
event specifiers trigger on exit out from the kernel.
The -d, -D, -e, -s, -t, -T, -c, and -n options have the
same meaning as they do for the ::evset dcmd.
thread ::tls symbol
Print the address of the storage for the specified
thread-local storage (TLS) symbol in the context of the
specified thread. The thread expression should be one of
the thread identifiers described under Thread Support,
SunOS 5.10 Last change: 30 Nov 2005 49
User Commands mdb(1)
above. The symbol name can use any of the scoping opera-
tors described under Symbol Name Resolution, above.
::typeset [ +/-t] variable-name . . .
Set attributes for named variables. If one or more vari-
able names are specified, they are defined and set to
the value of dot. If the -t option is present, the
user-defined tag associated with each variable is set.
If the +t option is present, the tag is cleared. If no
variable names are specified, the list of variables and
their values is printed.
::unload module-name
Unload the specified dmod. The list of active dmods can
be printed using the ::dmods dcmd. Built-in modules can
not be unloaded. Modules that are busy (that is, provide
dcmds that are currently executing) can not be unloaded.
::unset variable-name . . .
Unset (remove) the specified variable(s) from the list
of defined variables. Some variables exported by mdb are
marked as persistent, and can not be unset by the user.
::vars [ -npt]
Print a listing of named variables. If the -n option is
present, the output is restricted to variables that
currently have non-zero values. If the -p option is
present, the variables are printed in a form suitable
for re-processing by the debugger using the $< dcmd.
This option can be used to record the variables to a
macro file and then restore these values later. If the
-t option is present, only the tagged variables are
printed. Variables can be tagged using the -t option of
the ::typeset dcmd.
::version
Print the debugger version number.
SunOS 5.10 Last change: 30 Nov 2005 50
User Commands mdb(1)
address ::vtop [-a as]
Print the physical address mapping for the specified
virtual address, if possible. The ::vtop dcmd is only
available when examining a kernel target, or when exa-
mining a user process inside a kernel crash dump (after
a ::context dcmd has been issued).
When examining a kernel target from the kernel context,
the -a option can be used to specify the address (as) of
an alternate address space structure that should be used
for the virtual to physical translation. By default, the
kernel's address space is used for translation. This
option is available for active address spaces even when
the dump content only contains kernel pages.
[ address ] ::walk walker-name [ variable-name ]
Walk through the elements of a data structure using the
specified walker. The available walkers can be listed
using the ::walkers dcmd. Some walkers operate on a glo-
bal data structure and do not require a starting
address. For example, walk the list of proc structures
in the kernel. Other walkers operate on a specific data
structure whose address must be specified explicitly.
For example, given a pointer to an address space, walk
the list of segments. When used interactively, the
::walk dcmd prints the address of each element of the
data structure in the default base. The dcmd can also be
used to provide a list of addresses for a pipeline. The
walker name can use the backquote (`) scoping operator
described under dcmd and Walker Name Resolution, above.
If the optional variable-name is specified, the speci-
fied variable is assigned the value returned at each
step of the walk when mdb invokes the next stage of the
pipeline.
::walkers
List the available walkers and print a brief description
for each one.
::whence [ -v ] name . . .
::which [ -v ] name ...
Print the dmod that exports the specified dcmds and
SunOS 5.10 Last change: 30 Nov 2005 51
User Commands mdb(1)
walkers. These dcmds can be used to determine which dmod
is currently providing the global definition of the
given dcmd or walker. Refer to the section on dcmd and
Walker Name Resolution above for more information on
global name resolution. The -v option causes the dcmd to
print the alternate definitions of each dcmd and walker
in order of precedence.
addr [ ,len ]::wp [ +/-dDestT ] [ -rwx ] [ -c cmd ]
[ -n count ]
addr [ ,len ] :a [ cmd . . . ]
addr [ ,len ] :p [ cmd .. . ]
addr [ ,len ] :w [ cmd . . . ]
Set a watchpoint at the specified address. The length in
bytes of the watched region can be set by specifying an
optional repeat count preceding the dcmd. If no length
is explicitly set, the default is one byte. The ::wp
dcmd allows the watchpoint to be configured to trigger
on any combination of read (-r option), write (-w
option), or execute (-x option) access. The -d, -D, -e,
-s, -t, -T, -c, and -n options have the same meaning as
they do for the ::evset dcmd. The :a dcmd sets a read
access watchpoint at the specified address. The :p dcmd
sets an execute access watchpoint at the specified
address. The :w dcmd sets a write access watchpoint at
the specified address. The arguments following the :a,
:p, and :w dcmds are concatenated together to form the
callback string. If this string contains meta-
characters, it must be quoted.
::xdata
List the external data buffers exported by the current
target. External data buffers represent information
associated with the target that can not be accessed
through standard target facilities (that is, an address
space, symbol table, or register set). These buffers can
be consumed by dcmds; for more information, refer to the
Solaris Modular Debugger Guide.
SunOS 5.10 Last change: 30 Nov 2005 52
User Commands mdb(1)
:z
Delete all event specifiers from the list of traced
software events. Event specifiers can also be deleted
using ::delete.
OPTIONS
The following options are supported:
-A Disables automatic loading of mdb modules.
By default, mdb attempts to load debugger
modules corresponding to the active shared
libraries in a user process or core file, or
to the loaded kernel modules in the live
operating system or an operating system
crash dump.
-f Forces raw file debugging mode. By default,
mdb attempts to infer whether the object and
core file operands refer to a user execut-
able 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 pro-
cess, if necessary. By default, mdb refuses
to attach to a user process that is already
under the control of another debugging tool,
such as truss(1). With the -F option, mdb
attaches to these processes anyway. This can
produce unexpected interactions between mdb
and the other tools attempting to control
the process.
-I path Sets default path for locating macro files.
Macro files are read using the $< or $<<
dcmds. The path is a sequence of directory
names delimited by colon (:) characters. The
-I include path and -L library path (see
below) can also contain any of the following
tokens:
SunOS 5.10 Last change: 30 Nov 2005 53
User Commands mdb(1)
%i Expands to the current instruction
set architecture (ISA) name
('sparc', 'sparcv9', or 'i386').
%o Expands to the old value of the
path being modified. This is useful
for appending or prepending direc-
tories to an existing path.
%p Expands to the current platform
string (either uname -i or the
platform string stored in the pro-
cess core file or crash dump).
%r Expands to the pathname of the root
directory. An alternate root direc-
tory can be specified using the -R
option. If no -R option is present,
the root directory is derived
dynamically from the path to the
mdb executable itself. For example,
if /bin/mdb is executed, the root
directory is /. If
/net/hostname/bin/mdb were exe-
cuted, the root directory would be
derived as /net/hostname.
%t Expands to the name of the current
target. This is either be the
literal string 'proc' (a user pro-
cess or user process core file),
'kvm' (a kernel crash dump or the
live operating system), or 'raw' (a
raw file).
The default include path for 32-bit mdb is:
%r/usr/platform/%p/lib/adb:%r/usr/lib/adb
The default include path for 64-bit mdb is:
SunOS 5.10 Last change: 30 Nov 2005 54
User Commands mdb(1)
%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 execut-
able and core dump, or to a pair of operat-
ing system crash dump files. The -k option
forces mdb to assume these files are operat-
ing system crash dump files. If no object or
core operand is specified, but the -k option
is specified, mdb defaults to an object file
of /dev/ksyms and a core file of /dev/kmem.
Read access to /dev/kmem is restricted to
group sys. Write access requires ALL
privileges.
-K Load kmdb, stop the live running operating
system kernel, and proceed to the kmdb
debugger prompt. This option should only be
used on the system console, as the subse-
quent kmdb prompt appears on the system con-
sole.
-L path Sets default path for locating debugger
modules. Modules are loaded automatically on
startup or using the ::load dcmd. The path
is a sequence of directory names delimited
by colon (:) characters. The -L library path
can also contain any of the tokens shown for
-I above.
-m Disables demand-loading of kernel module
symbols. By default, mdb processes the list
of loaded kernel modules and performs demand
loading of per-module symbol tables. If the
-m option is specified, mdb does not attempt
to process the kernel module list or provide
per-module symbol tables. As a result, mdb
modules corresponding to active kernel
modules are not loaded on startup.
-M Preloads all kernel module symbols. By
default, mdb performs demand-loading for
SunOS 5.10 Last change: 30 Nov 2005 55
User Commands mdb(1)
kernel module symbols: the complete symbol
table for a module is read when an address
is that module's text or data section is
referenced. With the -M option, mdb loads
the complete symbol table of all kernel
modules during startup.
-o option Enables the specified debugger option. If
the +o form of the option is used, the
specified option is disabled. Unless noted
below, each option is off by default. mdb
recognizes the following option arguments:
adb
Enables stricter adb(1) compatibility.
The prompt is set to the empty string
and many mdb features, such as the out-
put pager, is disabled.
array_mem_limit=limit
Sets the default limit on the number of
array members that ::print displays. If
limit is the special token none, all
array members are displayed by default.
array_str_limit=limit
Sets the default limit on the number of
characters that ::print attempts to
display as an ASCII string when printing
a char array. If limit is the special
token none, the entire char array is
displayed as a string by default.
follow_exec_mode=mode
Sets the debugger behavior for following
an exec(2) system call. The mode should
be one of the following named constants:
SunOS 5.10 Last change: 30 Nov 2005 56
User Commands mdb(1)
ask If stdout is a terminal device,
the debugger stops after the
exec(2) system call has
returned and then prompts the
user to decide whether to fol-
low the exec or stop. If stdout
is not a terminal device, the
ask mode defaults to stop.
follow The debugger follows the exec
by automatically continuing the
target process and resetting
all of its mappings and symbol
tables based on the new execut-
able. The follow behavior is
discussed in more detail under
NOTES, Interaction with Exec,
below.
stop The debugger stops following
return from the exec system
call. The stop behavior is dis-
cussed in more detail under
NOTES, Interaction with Exec,
below.
follow_fork_mode=mode
Sets the debugger behavior for following
a fork(2), fork1(2), or vfork(2) system
call. The mode should be one of the fol-
lowing named constants:
ask If stdout is a terminal device,
the debugger stops after the
fork(2) system call has
returned and then prompts the
user to decide whether to fol-
low the parent or child. If
stdout is not a terminal dev-
ice, the ask mode defaults to
parent.
SunOS 5.10 Last change: 30 Nov 2005 57
User Commands mdb(1)
parent The debugger follows the parent
process, and detaches from the
child process and sets it run-
ning.
child The debugger follows the child
process, and detaches from the
parent process and sets it run-
ning.
ignoreeof
The debugger does not exit when an EOF
sequence (^D) is entered at the termi-
nal. The ::quit dcmd must be used to
quit.
nostop
Does not stop a user process when
attaching to it when the -p option is
specified or when the ::attach or :A
dcmds are applied. The nostop behavior
is described in more detail under NOTES,
Process Attach and Release, below.
pager
Enables the output pager (default).
repeatlast
If a NEWLINE is entered as the complete
command at the terminal, mdb repeats the
previous command with the current value
of dot. This option is implied by -o
adb.
SunOS 5.10 Last change: 30 Nov 2005 58
User Commands mdb(1)
showlmid
mdb provides support for symbol naming
and identification in user applications
that make use of link maps other than
LM_ID_BASE and LM_ID_LDSO, as described
in Symbol Name Resolution, above. Sym-
bols on link maps other than LM_ID_BASE
or LM_ID_LDSO is shown as
LMlmid`library`symbol, where lmid is the
link-map ID in the default output radix
(16). The user can optionally configure
mdb to show the link-map ID scope of all
symbols and objects, including those
associated with LM_ID_BASE and
LM_ID_LDSO, by enabling the showlmid
option. Built-in dcmds that deal with
object file names displays link-map IDs
according to the value of showlmid
above, including ::nm, ::mappings, $m,
and ::objects.
-p pid Attaches to and stops the specified
process-id. mdb uses the
/proc/pid/object/a.out file as the execut-
able file pathname.
-P prompt Sets the command prompt. The default prompt
is '> '.
-R root Sets root directory for pathname expansion.
By default, the root directory is derived
from the pathname of the mdb executable
itself. The root directory is substituted in
place of the %r token during pathname expan-
sion.
-s distance Sets the symbol matching distance for
address-to-symbol-name conversions to the
specified distance. By default, mdb sets the
distance to zero, which enables a smart-
matching mode. Each ELF symbol table entry
includes a value V and size S, representing
SunOS 5.10 Last change: 30 Nov 2005 59
User Commands mdb(1)
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 speci-
fied absolute distance and the symbol size
is ignored.
-S Suppresses processing of the user's ~/.mdbrc
file. By default, mdb reads and processes
the macro file .mdbrc if one is present in
the user's home directory, as defined by
$HOME. If the -S option is present, this
file is not read.
-u Forces user debugging mode. By default, mdb
attempts to infer whether the object and
core file operands refer to a user execut-
able and core dump, or to a pair of operat-
ing system crash dump files. The -u option
forces mdb to assume these files are not
operating system crash dump files.
-U Unload kmdb if it is loaded. You should
unload kmdb when it is not in use to release
the memory used by the kernel debugger back
to the free memory available to the operat-
ing system.
-V version Sets disassembler version. By default, mdb
attempts to infer the appropriate disassem-
bler version for the debug target. The
disassembler can be set explicitly using the
-V option. The ::disasms dcmd lists the
available disassembler versions.
-w Opens the specified object and core files
for writing.
SunOS 5.10 Last change: 30 Nov 2005 60
User Commands mdb(1)
-W Permit access to memory addresses that are
mapped to I/O devices. By default, mdb does
not allow such access because many devices
do not provide hardware protection against
invalid software manipulations. Use this
option only when debugging device drivers
and with caution.
-y Sends explicit terminal initialization
sequences for tty mode. Some terminals, such
as cmdtool(1), require explicit initializa-
tion sequences to switch into a tty mode.
Without this initialization sequence, termi-
nal features such as standout mode can not
be available to mdb.
OPERANDS
The following operands are supported:
object Specifies an ELF format object file to examine. mdb
provides the ability to examine and edit ELF format
executables (ET_EXEC), ELF dynamic library files
(ET_DYN), ELF relocatable object files (ET_REL),
and operating system unix.X symbol table files.
core Specifies an ELF process core file (ET_CORE), or an
operating system crash dump vmcore.X file. If an
ELF core file operand is provided without a
corresponding object file, mdb attempts to infer
the name of the executable file that produced the
core using several different algorithms. If no exe-
cutable is found, mdb still executes, but some sym-
bol information can be unavailable.
suffix Specifies the numerical suffix representing a pair
of operating system crash dump files. For example,
if the suffix is '3', mdb infers that it should
examine the files 'unix.3' and 'vmcore.3'. The
string of digits are not interpreted as a suffix if
an actual file of the same name is present in the
current directory.
SunOS 5.10 Last change: 30 Nov 2005 61
User Commands mdb(1)
USAGE
mdb processes all input files (including scripts, object
files, core files, and raw data files) in a large file aware
fashion. See largefile(5) for more information about the
processing of large files, which are files greater than or
equal to 2 Gbytes (2**31 bytes).
EXIT STATUS
The following exit values are returned:
0 Debugger completed execution successfully.
1 A fatal error occurred.
2 Invalid command line options were specified.
ENVIRONMENT VARIABLES
HISTSIZE This variable is used to determine the max-
imum length of the command history list. If
this variable is not present, the default
length is 128.
HOME This variable is used to determine the path-
name 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 path-
name 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.
SunOS 5.10 Last change: 30 Nov 2005 62
User Commands mdb(1)
/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 operat-
ing system.
/proc/pid/*
Process information files that are read when examining
and controlling user processes.
/usr/lib/adb
/usr/platform/platform-name/lib/adb
Default directories for macro files that are read with
the $< and $<< dcmds. platform-name is the name of the
platform, derived either from information in a core file
or crash dump, or from the current machine as if by
uname -i (see uname(1)).
/usr/lib/mdb
/usr/platform/platform-name/lib/mdb
Default directories for debugger modules that are loaded
using the ::load dcmd. platform-name is the name of the
platform, derived either from information in a core file
or crash dump, or from the current machine as if by
uname -i (see uname(1)).
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
SunOS 5.10 Last change: 30 Nov 2005 63
User Commands mdb(1)
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Availability | SUNWmdb |
|_____________________________|_____________________________|
| Interface Stability | Evolving |
|_____________________________|_____________________________|
SEE ALSO
adb(1), cmdtool(1), gcore(1), proc(1), pgrep(1), ps(1),
stty(1), truss(1), uname(1), coreadm(1M), dumpadm(1M), lar-
gefile(5), savecore(1M), exec(2), fork(2), _lwp_self(2),
pipe(2), vfork(2), dlopen(3C), elf(3ELF), libc_db(3LIB),
libkvm(3LIB), libthread(3LIB), signal(3C), signal.h(3HEAD),
thr_self(3C), core(4), proc(4), attributes(5), largefile(5),
threads(5), ksyms(7D), mem(7D)
Linker and Libraries Guide
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 situations.
However, it is not possible for mdb to know definitively
whether the dmod in question has corrupted only its own
state, or the debugger's global state. Therefore a resume
operation cannot be guaranteed to be safe, or to prevent a
subsequent crash of the debugger. The safest course of
action following a resume is to save any important debug
information, and then quit and restart the debugger.
Use of the Debugger to Modify the Live Operating System
The use of the debugger to modify (that is, write to) the
address space of live running operating system is extremely
dangerous, and can result in a system panic in the event the
user damages a kernel data structure.
NOTES
Limitations on Examining Process Core Files
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 informa-
tion might not be available. Since the text section and
read-only data is not present in those core files, the sym-
bol information might not match the data present in the
SunOS 5.10 Last change: 30 Nov 2005 64
User Commands mdb(1)
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
coreadm(1M). 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 Solaris 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 the 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 implementa-
tion can prevent some dcmds or walkers from working prop-
erly. mdb issues a warning message if it detects this condi-
tion. Crash dumps from Solaris x86 systems can not be exam-
ined 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 automatically re-executes the mdb binary
that has the same data model as the target, if necessary.
This approach simplifies the task of writing debugger
modules, because the modules that are loaded use the same
data model as the primary target. Only the 64-bit debugger
can be used to debug 64-bit target programs. The 64-bit
debugger can only be used on a system that is running the
64-bit operating environment.
The debugger can also need to re-execute itself when debug-
ging a 32-bit process that execs a 64-bit process, or vice-
versa. The handling of this situation is discussed in more
detail under Interaction with Exec, below.
Interaction with Exec
When a controlled process performs a successful exec(2), the
behavior of the debugger is controlled by the ::set -o
follow_exec_mode option, as described above. If the debugger
and victim process have the same data model, then the "stop"
and "follow" modes determine whether mdb automatically con-
tinues the target or returns to the debugger prompt follow-
ing the exec. If the debugger and victim process have a dif-
ferent 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.
SunOS 5.10 Last change: 30 Nov 2005 65
User Commands mdb(1)
If a 32-bit victim process execs a 64-bit program, then
"stop" returns to the command prompt, but the debugger is no
longer able to examine the process because it is now using
the 64-bit data model. To resume debugging, execute the
::release -a dcmd, quit mdb, and then execute mdb -p pid to
re-attach the 64-bit debugger to the process.
If a 64-bit victim process execs a 32-bit program, then
"stop" returns to the command prompt, but the debugger only
provides limited capabilities for examining the new process.
All built-in dcmds work as advertised, but loadable dcmds do
not since they do not perform data model conversion of
structures. The user should release and re-attach the
debugger to the process as described above in order to
restore full debugging capabilities.
Interaction with Job Control
If the debugger is attached to a process that is stopped by
job control (that is, it stopped in response to SIGTSTP,
SIGTTIN, or SIGTTOU), the process can not be able to be set
running again when it is continued by a continue dcmd. If
the victim process is a member of the same session (that is,
it shares the same controlling terminal as mdb), mdb
attempts to bring the associated process group to the fore-
ground and to continue the process with SIGCONT to resume it
from job control stop. When mdb is detached from such a pro-
cess, it restores the process group to the background before
exiting. If the victim process is not a member of the same
session, mdb cannot safely bring the process group to the
foreground, so it continues the process with respect to the
debugger, but the process remains stopped by job control.
mdb prints a warning in this case, and the user must issue
an "fg" command from the appropriate shell in order to
resume the process.
Process Attach and Release
When mdb attaches to a running process, the process is
stopped and remains stopped until one of the continue dcmds
is applied, or the debugger quits. If the -o nostop option
is enabled prior to attaching the debugger to a process with
-p, or prior to issuing an ::attach or :A command, mdb
attaches to the process but does not stop it. While the pro-
cess is still running, it can be inspected as usual (albeit
with inconsistent results) and breakpoints or other tracing
flags might be enabled. If the :c or ::cont dcmds are exe-
cuted while the process is running, the debugger waits for
the process to stop. If no traced software events occur, the
user can send an interrupt (^C) after :c or ::cont to force
the process to stop and return control to the debugger.
mdb releases the current running process (if any) when the
:R, ::release, :r, ::run, $q, or ::quit dcmds are executed,
SunOS 5.10 Last change: 30 Nov 2005 66
User Commands mdb(1)
or when the debugger terminates as the result of an EOF or
signal. If the process was originally created by the
debugger using :r or ::run, it is forcibly terminated as if
by SIGKILL when it is released. If the process was already
running prior to attaching mdb to it, it is set running
again when it is released. A process can be released and
left stopped and abandoned using the ::release -a option.
Symbolic Debugging Information
The ::list, ::offsetof, ::print, and ::sizeof dcmds require
that one or more load objects contain compressed symbolic
debugging information suitable for use with mdb. This infor-
mation is currently only available for certain Solaris ker-
nel modules.
Developer Information
The Solaris Modular Debugger Guide provides a more detailed
description of mdb features, as well as information for
debugger module developers.
The header file <sys/mdb_modapi.h> contains prototypes for
the functions in the MDB Module API, and the SUNWmdbdm pack-
age provides source code for an example module in the direc-
tory /usr/demo/mdb.
SunOS 5.10 Last change: 30 Nov 2005 67
Man(1) output converted with
man2html and wrapped by fishsponge
This page was generated on Wed Sep 12 11:25:05 GMT 2007
|
Your favourite pages:
No pages logged yet... Top 10 most popular pages:
prstat man page (24541 hits)
(Solaris 10 11_06)
netcat man page (17692 hits)
(Suse Linux 10.1)
ssh-socks5-proxy-connect man page (13521 hits)
(Solaris 10 11_06)
signal man page (12550 hits)
(Suse Linux 10.1)
startproc man page (11987 hits)
(Suse Linux 10.1)
raidctl man page (11353 hits)
(Solaris 10 11_06)
adv_cap_autoneg man page (10283 hits)
(Solaris 10 11_06)
sqlite3 man page (9728 hits)
(openSUSE 10.2)
CPAN man page (8947 hits)
(Suse Linux 10.1)
BusyBox man page (7698 hits)
(Suse Linux 10.1)
|
Man Pages 
