SunOS man pages : mdb (1)
User Commands mdb(1)
NAME
mdb - modular debugger
SYNOPSIS
mdb [ -kmuwyAFMS ] [ _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 may not be reproducible and program state is
massive and distributed, for programs that are highly optim-
ized, have had their debug information removed, or are them-
selves low-level debugging tools, or for customer situations
where the developer can only access post-mortem information.
mdb provides a completely customizable environment for
debugging these programs and scenarios, including a dynamic
module facility that programmers can use to implement their
own debugging commands to perform program-specific analysis.
Each mdb module can be used to examine the program in
several different contexts, including live and post-mortem.
Definitions
The target is the program being inspected by the debugger.
mdb currently provides support for the following types of
targets: user processes, user process core files, the live
operating system (via /dev/kmem and /dev/ksyms), operating
system crash dumps, user process images recorded inside an
operating system crash dump, and ELF object files. Each tar-
get exports a standard set of properties, including one or
more address spaces, one or more symbol tables, a set of
load objects, and a set of threads that can be examined
using the debugger commands described below.
SunOS 5.8 Last change: 14 Sep 1999 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 will attempt to load dmods
corresponding to the load objects present in the tar-
get. You can subsequently load or unload dmods at any time
while running mdb. mdb ships with a set of standard dmods
for debugging 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 may 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.8 Last change: 14 Sep 1999 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 builtin 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 or 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.
Commands
A command is one of the following:
SunOS 5.8 Last change: 14 Sep 1999 3
User Commands mdb(1)
pipeline [! word ...] [ ; ]
A simple-command or pipeline can be optionally suf-
fixed 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 fol-
lowed 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 will be 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 will be
repeated according to the value of the expression.
expression [! word ...] [ ; ]
A command can consist only of an arithmetic expres-
sion. The expression is evaluated and the dot variable
is set to its value, and then the previous dcmd and
arguments are executed using the new value of dot.
expression, expression [! word ...] [ ; ]
A command can consist only of a dot expression and
repeat count expression. After dot is set to the value
of the first expression, the previous dcmd and argu-
ments 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 repeat-
edly executed the number of times specified by the
value of the count expression.
! word ... [ ; ]
If the command begins with the ! character, no dcmds
SunOS 5.8 Last change: 14 Sep 1999 4
User Commands mdb(1)
are executed and the debugger simply executes $SHELL
-c followed by the string formed by concatenating the
words after the ! character.
Comments
A word beginning with // causes that word and all the 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 will be replaced by the
value of the expression.
Expressions may contain any of the following special words:
integer
The specified integer value. Integer values may be
prefixed with 0i or 0I to indicate binary values, 0o
or 0O to indicate octal values, 0t or 0T to indicate
decimal values, and 0x or 0X to indicate hexadecimal
values (the default).
0[tT][0-9]+.[0-9]+
The specified decimal floating point value, converted
to its IEEE double-precision floating point represen-
tation.
'cccccccc'
The integer value computed by converting each charac-
ter to a byte equal to its ASCII value. Up to eight
characters may be specified in a character constant.
Characters are packed into the integer in reverse
order (right-to-left) beginning at the least signifi-
cant 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.
SunOS 5.8 Last change: 14 Sep 1999 5
User Commands mdb(1)
+ The value of dot incremented by the current increment.
^ The value of dot decremented by the current increment.
The increment is a global variable that stores the total
bytes read by the last formatting dcmd. For more information
on the increment, refer to the discussion of Formatting
dcmds below.
Unary operators are right associative and have higher 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 quantity at the object
file location corresponding to virtual address expres-
sion in the target's virtual address space.
%/[csil]/expression
The value of a char, short, int, or long-sized quan-
tity 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 virtual
address expression in the target's virtual address
space.
*expression
The value of a pointer-sized quantity at virtual
address expression in the target's virtual address
space.
*/[csil]/expression
The value of a char, short, int, or long-sized quan-
tity 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.
SunOS 5.8 Last change: 14 Sep 1999 6
User Commands mdb(1)
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.
!= 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 dou-
ble (") 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 will fork and exec this program for
shell escapes; otherwise /bin/sh is used. The shell is
invoked with the -c option followed by a string formed by
concatenating the words after the ! character. The ! charac-
ter takes precedence over all other metacharacters, except
semicolon (;) and NEWLINE. Once a shell escape is detected,
the remaining characters up to the next semicolon or NEWLINE
are passed as is to the shell. The output of shell commands
may not be piped to mdb dcmds. Commands executed by a shell
escape have their output sent directly to the terminal, not
to mdb.
SunOS 5.8 Last change: 14 Sep 1999 7
User Commands mdb(1)
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 may have one or more
of the following attributes: read-only (cannot be modified
by the user), persistent (cannot be unset by the user), and
tagged (user-defined indicator).
The following variables are defined as persistent:
0 The most recent value printed using the /, \, ?,
or = dcmd.
9 The most recent count used with the $< dcmd.
b The virtual address of the base of the data sec-
tion.
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.
In addition, the mdb kernel and process targets will export
the current values of the representative thread's register
set as named variables. The names of these variables will
depend on the target's platform and instruction set archi-
tecture.
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 may 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
SunOS 5.8 Last change: 14 Sep 1999 8
User Commands mdb(1)
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 may include symbols from multiple object files, dif-
ferent symbols with the same name may 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.
The mdb process target expects object to specify the name of
the executable or of a loaded shared library. It may 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.
SunOS 5.8 Last change: 14 Sep 1999 9
User Commands mdb(1)
In the case of a naming conflict between symbols and hexade-
cimal integer values, mdb will attempt to evaluate an ambi-
guous token as a symbol first, before evaluating it as an
integer value. For example, the token f may either refer to
the decimal integer value 15 specified in hexadecimal (the
default base), or to a global variable named f in the
target's symbol table. If a symbol with an ambiguous name is
present, the integer value can be specified by using an
explicit 0x or 0X prefix.
dcmd and Walker Name Resolution
As described earlier, each mdb dmod provides a set of dcmds
and walkers. dcmds and walkers are tracked in two distinct,
global namespaces. mdb also keeps track of a dcmd and walker
namespace associated with each dmod. Identically named dcmds
or walkers within a given dmod are not allowed: a dmod with
this type of naming conflict will fail to load. Name con-
flicts 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. Alter-
nate definitions are kept in a list in load order. The
backquote character (`) may 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.
SunOS 5.8 Last change: 14 Sep 1999 10
User Commands mdb(1)
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
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 will restore 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 termi-
nal, mdb will provide 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 will abort all active commands and unload the dmod
whose dcmd was active at the time the fault occurred. It can
then be subsequently re-loaded by the user. The resume
option provides limited protection against buggy dcmds.
Refer to WARNINGS, Use of the Error Recovery Mechanism,
below for information about the risks associated with the
resume option.
Command Re-entry
The text of the last HISTSIZE (default 128) commands
entered from a terminal device are saved in memory. The in-
line editing facility, described next, provides key mappings
for searching and fetching elements from the history list.
SunOS 5.8 Last change: 14 Sep 1999 11
User Commands mdb(1)
In-line Editing
If standard input is a terminal device, mdb provides some
simple emacs-style facilities for editing the command line.
The search, previous, and next commands in edit mode provide
access to the history list. Only strings, not patterns, are
matched when searching. In the table below, the notation for
control characters is caret (^) followed by a character
shown in upper case. The notation for escape sequences is M-
followed by a character. For example, M-f (pronounced meta-
eff) is entered by depressing <ESC> followed by 'f', or by
depressing Meta followed by 'f' on keyboards that support a
Meta key. A command line is committed and executed using
RETURN or NEWLINE. The edit commands are:
^F Move cursor forward (right) one character.
M-f Move cursor forward one word.
^B Move cursor backward (left) one character.
M-b Move cursor backward one word.
^A Move cursor to start of line.
^E Move cursor to end of line.
^D Delete current character, if the current line is not
empty. If the current line is empty, ^D denotes EOF
and the debugger will exit.
^K Delete from the cursor to the end of the line.
^L Reprint the current line.
^T Transpose current character with next character.
^N Fetch the next command from the history. Each time ^N
is entered, the next command forward in time is
retrieved.
^P Fetch the previous command from the history. Each time
^P is entered, the next command backward in time is
retrieved.
^R[string]
Search backward in the history for a previous command
line containing string. The string should be ter-
minated by a RETURN or NEWLINE. If string is omitted,
the previous history element containing the most
recent string is retrieved.
SunOS 5.8 Last change: 14 Sep 1999 12
User Commands mdb(1)
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.
On keyboards that support an extended keypad with arrow
keys, mdb will interpret these keystrokes as editing com-
mands:
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 will pause after
one screenful of output is produced and will display a pager
prompt:
>> More [<space>, <cr>, q, n, c, a] ?
The following key sequences are recognized by the pager:
SPACE Display the next screenful of output.
a, A Abort the current top-level command and return to the
prompt.
SunOS 5.8 Last change: 14 Sep 1999 13
User Commands mdb(1)
c, C Continue displaying output without pausing at each
screenful until the current top-level command is com-
plete.
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 may 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 speci-
fied data formats. The = dcmd is therefore useful for
converting between bases and performing arithmetic.
In addition to dot, mdb keeps track of another global value
called the increment. The increment represents the distance
between dot and the address following all the data read by
the last formatting dcmd. For example, if a formatting dcmd
is executed with dot equal to address A, and displays a 4-
byte integer, then after this dcmd completes, dot is still
A, but the increment is set to 4. The + character (described
under Arithmetic Expansion above) would now evaluate to the
value A + 4, and could be used to reset dot to the address
of the next data object for a subsequent dcmd.
SunOS 5.8 Last change: 14 Sep 1999 14
User Commands mdb(1)
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)
O octal unsigned int (4 bytes)
P symbol (4 or 8 bytes)
Q octal signed int (4 bytes)
S string using C string notation (variable size)
U decimal unsigned int (4 bytes)
V decimal unsigned int (1 byte)
W default radix unsigned int (4 bytes)
X hexadecimal int (4 bytes)
Y decoded time32_t (4 bytes)
Z hexadecimal long long (8 bytes)
^ decrement dot by increment * count (variable
size)
a dot as symbol+offset
b octal unsigned int (1 byte)
c character (1 byte)
d decimal signed short (2 bytes)
e decimal signed long long (8 bytes)
f float (4 bytes)
g octal signed long long (8 bytes)
h swap bytes (2 bytes)
i disassembled instruction (variable size)
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)
SunOS 5.8 Last change: 14 Sep 1999 15
User Commands mdb(1)
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, w Write the lowest 2 bytes of the value of each expres-
sion to the target beginning at the location specified
by dot.
W Write the lowest 4 bytes of the value of each expres-
sion to the target beginning at the location specified
by dot.
Z Write the complete 8 bytes of the value of each
expression to the target beginning at the location
specified by dot.
The /, \, and ? formatting dcmds can also be used to search
for a particular integer value in the target's virtual
address space, physical address space, and object file,
respectively, by specifying one of the following modifiers
as the first format character, and then specifying a value
and optional mask. The value and mask are each specified as
either immediate values or expressions enclosed in square
brackets preceded by a dollar sign. If only a value is
specified, mdb reads integers of the appropriate size and
stops at the address containing the matching value. If a
value V and mask M are specified, mdb reads integers of the
appropriate size and stops at the address containing a value
X where (X & M) == V. At the completion of the dcmd, dot is
updated to the address containing the match. If no match is
found, dot is left at the last address that was read.
The search modifiers are:
l Search for the specified 2-byte value.
L Search for the specified 4-byte value.
M Search for the specified 8-byte value.
Note that for both user and kernel targets, an address space
is typically composed of a set of discontiguous segments. It
is not legal to read from an address that does not have a
corresponding segment. If a search reaches a segment boun-
dary without finding a match, it will abort when the read
past the end of the segment boundary fails.
SunOS 5.8 Last change: 14 Sep 1999 16
User Commands mdb(1)
Builtin dcmds
mdb provides a set of builtin 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 will
fail and print a message indicating "command is not sup-
ported 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 may prefer the $
or : forms of the builtins. Programmers who are new to mdb
may prefer the more verbose :: form. The builtins are shown
in alphabetical order. If a $ or : form has a ::identifier
equivalent, it is shown underneath the ::identifier form.
The builtin dcmds are:
> variable-name
>/modifier/ variable-name
Assign the value of dot to the specified named vari-
able. Some variables are read-only and may not be
modified. If the > is followed by a modifier charac-
ter surrounded by / /, then the value is modified as
part of the assignment. The modifier characters are:
c unsigned char quantity (1-byte)
s unsigned short quantity (2-byte)
i unsigned int quantity (4-byte)
l unsigned long quantity (4-byte in 32-bit, 8-byte in
64-bit)
Notice that these operators do not perform a cast; they
instead fetch the specified number of low-order bytes (on
little-endian architectures) or high-order bytes (big-endian
architectures). Modifiers are provided for backwards compa-
tibility; the mdb */modifier/ and %/modifier/ syntax should
be used instead.
$< macro-name
Read and execute commands from the specified macro
file. The filename may be given as an absolute or
relative path. If the filename is a simple name (that
is, if it does not contain a '/'), mdb will search 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.8 Last change: 14 Sep 1999 17
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 vir-
tual memory address is displayed. Otherwise the stack
of the representative thread is displayed. If an
optional count value is given as an argument, no more
than count arguments are displayed for each stack
frame in the output.
[ base ] $d
Get or set the default output radix. If the dcmd is
preceded by an explicit expression, the default output
radix is set to the given base; otherwise the current
radix is printed in base 10 (decimal). The default
radix is base 16 (hexadecimal).
$e Print a list of all known external (global) symbols of
type object or function, the value of the symbol, and
the first 4 (32-bit mdb) or 8 (64-bit mdb) bytes
stored at this location in the target's virtual
address space. The ::nm dcmd provides more flexible
options for displaying symbol tables.
$P prompt-string
Set the prompt to the specified prompt-string. The
default prompt is '> '. The prompt can also be set
using ::set -P or the -P command-line option
distance $s
Get or set the symbol matching distance for address-
to-symbol-name conversions. The symbol matching dis-
tance modes are discussed along with the -s command-
line option under OPTIONS, below. The symbol matching
distance may also be modified using the ::set -s
option. If no distance is specified, the current set-
ting is displayed.
$v Print a list of the named variables that have non-zero
values. The ::vars dcmd provides other options for
listing variables.
width $w
Set the output page width to the specified value.
SunOS 5.8 Last change: 14 Sep 1999 18
User Commands mdb(1)
Typically, this command is not necessary as mdb
queries the terminal for its width and handles resize
events.
$W Re-open the target for writing, as if mdb had been
executed with the -w option on the command line. Write
mode can also be enabled with the ::set -w option.
[ pid ] ::attach [ core | pid ]
[ pid ] :A [ core | pid ]
If the user process target is active, attach to and
debug the specified process-ID or core file. The core
file pathname should be specified as a string argu-
ment. The process-ID may 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 expres-
sions.
::cat filename ...
Concatenate and display files. Each filename may
specified as a relative or absolute pathname. The file
contents will be printed to standard output, but will
not be passed to the output pager. This dcmd is
intended to be used with the | operator; the program-
mer can initiate a pipeline using a list of addresses
stored in an external file.
address ::context
address $p
Context switch to the specified process. A context
switch operation is 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 all physical memory pages
(as opposed to just kernel pages). The kernel crash
dump facility can be configured to dump all pages
using dumpadm(1M).
When the user requests a context switch from the ker-
nel 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 will now format and display
data from the virtual address space of the user pro-
cess, the ::mappings dcmd will display the mappings in
SunOS 5.8 Last change: 14 Sep 1999 19
User Commands mdb(1)
the address space of the user process, and so on. The
kernel target can be restored by executing 0::context.
::dcmds
List the available dcmds and print a brief description
for each one.
[ address ] ::dis [ -fw ] [ -n count ] [ address ]
Disassemble starting at or around the address speci-
fied by the final argument, or the current value of
dot. If the address matches the start of a known func-
tion, the entire function is disassembled; otherwise a
"window" of instructions before and after the speci-
fied address is printed in order to provide context.
By default, instructions are read from the target's
virtual address space; if the -f option is present,
instructions are read from the target's object file
instead. The -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 will attempt to select the
appropriate disassembler mode. The user can change the
mode to any of the modes listed using the ::dismode
dcmd.
::dismode [ mode ]
$V [ mode ]
Get or set the disassembler mode. If no argument is
specified, print the current disassembler mode. If a
mode argument is specified, switch the disassembler to
the specified mode. The list of available disassem-
blers 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 associ-
ated 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.
::dump
Print a hexadecimal and ASCII memory dump of the 16-
byte aligned region of virtual memory containing the
address specified by dot. If a repeat count is speci-
fied for ::dump, this is interpreted as a number of
bytes to dump rather than a number of iterations.
SunOS 5.8 Last change: 14 Sep 1999 20
User Commands mdb(1)
::echo [ string | value ... ]
Print the arguments separated by blanks and terminated
by a NEWLINE to standard output. Expressions enclosed
in $[ ] will be evaluated to a value and printed in
the default base.
::eval command
Evaluate and execute the specified string as a com-
mand. If the command contains metacharacters or whi-
tespace, it should be enclosed in double or single
quotes.
::files
$f Print a list of the known source files (symbols of
type STT_FILE present in the various target symbol
tables).
::fpregs
$x, $X, $y, $Y
Print the floating-point register set of the represen-
tative thread.
::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 metachar-
acters, it must be quoted. The ::grep dcmd can be used
in pipelines to filter a list of addresses.
::help [ dcmd-name ]
With no arguments, the ::help dcmd prints a brief
overview of the help facilities available in mdb. If a
dcmd-name is specified, mdb will print a usage summary
for that dcmd.
::load module-name
Load the specified dmod. The module name may be given
as an absolute or relative path. If module-name is a
simple name (that is, does not contain a '/'), mdb
will search for it in the module library path. Modules
with conflicting names may not be loaded; the existing
module must be unloaded first.
::log [ -d | [ -e ] filename ]
SunOS 5.8 Last change: 14 Sep 1999 21
User Commands mdb(1)
$> [ 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; otherwise, logging is disabled. If the
specified log file already exists, mdb appends any new
log output to the file.
::map command
Map the value of dot to a corresponding value using
the command specified as a string argument, and then
print the new value of dot. If the command contains
whitespace or metacharacters, it must be quoted. The
::map dcmd can be used in pipelines to transform the
list of addresses into a new list of addresses.
[ address ] ::mappings [ name ]
[ address ] $m [ name ]
Print a list of each mapping in the target's virtual
address space, including the address, size, and
description of each mapping. If the dcmd is preceded
by an address, mdb will only show the mapping that
contains the given address. If a string name argument
is given, mdb will only show the mapping matching that
description.
::nm [ -DPdghnopuvx ] [ object ]
Print the symbol tables associated with the current
target. If an object name argument is specified, only
the symbol table for this load object is displayed.
The ::nm dcmd also recognizes the following options:
-D Print .dynsym (dynamic symbol table) instead of
.symtab.
-P Print the private symbol table instead of .sym-
tab.
-d Print value and size fields in decimal.
-g Print only global symbols.
-h Suppress the header line.
-n Sort symbols by name.
SunOS 5.8 Last change: 14 Sep 1999 22
User Commands mdb(1)
-o Print value and size fields in octal.
-p Print symbols as a series of ::nmadd commands.
This option can be used with -P to produce a
macro file that can be subsequently read into
the debugger with $<.
-u Print only undefined symbols.
-v Sort symbols by value.
-x Print value and size fields in hexadecimal.
value ::nmadd [ -fo ] [ -e end ] [ -s size ] name
Add the specified symbol name to the private symbol
table. mdb provides a private, configurable symbol
table that can be used to interpose on the target's
symbol table, as described under Symbol Name Resolu-
tion above. The ::nmadd dcmd also recognizes the fol-
lowing options:
-e Set the size of the symbol to end - value.
-f Set the type of the symbol to STT_FUNC.
-o Set the type of the symbol to STT_OBJECT.
-s Set the size of the symbol to size.
::nmdel name
Delete the specified symbol name from the private sym-
bol table.
::objects
Print a map of the target's virtual address space,
showing only those mappings that correspond to the
primary mapping (usually the text section) of each of
the known load objects.
::quit
$q Quit the debugger.
::regs
$r Print the general-purpose register set of the
representative thread.
::release
SunOS 5.8 Last change: 14 Sep 1999 23
User Commands mdb(1)
:R Release the previously attached process or core file.
path
::set [ -wF ] [ +/-o option ] [ - s distance ] [ -
I path ] [ -L
] [ -P prompt ]" 6 Get or set miscellaneous debugger
properties. If no options are specified, the current
set of debugger properties is displayed. The ::set
dcmd recognizes the following options:
-F Forcibly take over the next user process that
::attach is applied to, as if mdb had been exe-
cuted with the -F option on the command line.
-I Set the default path for locating macro files.
The path argument may contain any of the special
tokens described for the -I command-line option
under OPTIONS below.
-L Set the default path for locating debugger
modules. The path argument may contain any of
the special tokens described for the -I
command-line option under OPTIONS below.
-o Enable the specified debugger option. If the +o
form is used, the option is
disabled. The option strings are
described along with the -o command-line option
under OPTIONS below.
-P Set the command prompt to the specified prompt
string.
-s Set the symbol matching distance to the speci-
fied distance. Refer to the description of the
-s command-line option under OPTIONS below for
more information.
-w Re-open the target for writing, as if mdb had
been executed with the -w option on the command
line.
[ address ] ::stack [ count ]
[ address ] $c [ count ]
Print a C stack backtrace. If the dcmd is preceded by
an explicit address, a backtrace beginning at this
virtual memory address is displayed. Otherwise the
stack of the representative thread is displayed. If an
optional count value is given as an argument, no more
than count arguments are displayed for each stack
SunOS 5.8 Last change: 14 Sep 1999 24
User Commands mdb(1)
frame in the output.
::status
Print a summary of information related to the current
target.
::typeset [+/-t] variable-name ...
Set attributes for named variables. If one or more
variable names are specified, they are defined and set
to the value of dot. If the -t option is present, the
user-defined tag associated with each variable is set.
If the +t option is present, the tag is cleared. If no
variable names are specified, the list of variables
and their values is printed.
::unload module-name
Unload the specified dmod. The list of active dmods
may be printed using the ::dmods dcmd. Builtin modules
may not be unloaded. Modules that are busy (that is,
provide dcmds that are currently executing) may not be
unloaded.
::unset variable-name ...
Unset (remove) the specified variable(s) from the list
of defined variables. Some variables are exported by
mdb are marked as persistent, and may not be unset by
the user.
::vars [-npt]
Print a listing of named variables. If the -n option
is present, the output is restricted to variables that
currently have non-zero values. If the -p option is
present, the variables are printed in a form suitable
for re-processing by the debugger using the $< dcmd.
This option can be used to record the variables to a
macro file and then restore these values later. If the
-t option is present, only the tagged variables are
printed. Variables can be tagged using the -t option
of the ::typeset dcmd.
::version
Print the debugger version number.
address ::vtop
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).
[ address ] ::walk walker-name [ variable-name ]
Walk through the elements of a data structure using
SunOS 5.8 Last change: 14 Sep 1999 25
User Commands mdb(1)
the specified walker. The available walkers can be
listed using the ::walkers dcmd. Some walkers operate
on a global data structure and do not require a start-
ing address. For example, walk the list of proc struc-
tures in the kernel. Other walkers operate on a
specific data structure whose address must be speci-
fied explicitly. For example, given a pointer to an
address space, walk the list of segments. When used
interactively, the ::walk dcmd will print the address
of each element of the data structure in the default
base. The dcmd can also be used to provide a list of
addresses for a pipeline. The walker name may use the
backquote (`) scoping operator described under dcmd
and Walker Name Resolution, above. If the optional
variable-name is specified, the specified variable
will be assigned the value returned at each step of
the walk when mdb invokes the next stage of the pipe-
line.
::walkers
List the available walkers and print a brief descrip-
tion for each one.
::whence [-v] name ...
::which [-v] name ...
Print the dmod that exports the specified dcmds and
walkers. These dcmds can be used to determine which
dmod is currently providing the global definition of
the given dcmd or walker. Refer to the section on dcmd
and Walker Name Resolution above for more information
on global name resolution. The -v option will cause
the dcmd to print the alternate definitions of each
dcmd and walker in order of precedence.
::xdata
List the external data buffers exported by the current
target. External data buffers represent information
associated with the target that can not be accessed
through standard target facilities (that is, an
address space, symbol table, or register set). These
buffers may be consumed by dcmds; for more informa-
tion, refer to the Solaris Modular Debugger Guide.
OPTIONS
The following options are supported:
-A Disables automatic loading of mdb modules. By default,
mdb will attempt to load debugger modules correspond-
ing 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
SunOS 5.8 Last change: 14 Sep 1999 26
User Commands mdb(1)
dump.
-F Forcibly takes over the specified user process, if
necessary. By default, mdb will refuse 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 will attach to these processes anyway.
This may produce unexpected interactions between mdb
and the other tools attempting to control the process.
-I 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) may also contain any of the following
tokens:
%i Expands to the current instruction set architecture
(ISA) name ('sparc', 'sparcv9', or 'i386').
%o Expands to the old value of the path being modified.
This is useful for appending or prepending directories
to an existing path.
%p Expands to the current platform string (either uname
-i or the platform string stored in the process core
file or crash dump).
%r Expands to the pathname of the root directory. An
alternate root directory may be specified using the -R
option. If no -R option is present, the root directory
is derived dynamically from the path to the mdb exe-
cutable itself. For example, if /bin/mdb is executed,
the root directory will be /. If
/net/hostname/bin/mdb were executed, the root direc-
tory would be derived as /net/hostname.
%t Expands to the name of the current target. This will
either be the literal string 'proc' (a user process or
user process core file), or 'kvm' (a kernel crash dump
or the live operating system).
The default include path for 32-bit mdb is:
%r/usr/platform/%p/lib/adb:%r/usr/lib/adb
The default include path for 64-bit mdb is:
%r/usr/platform/%p/lib/adb/%i:%r/usr/lib/adb/%i
SunOS 5.8 Last change: 14 Sep 1999 27
User Commands mdb(1)
-k Forces kernel debugging mode. By default, mdb will
attempt to infer whether the object and core file
operands refer to a user executable and core dump, or
to a pair of operating system crash dump files. The -k
option forces mdb to assume these files are operating
system crash dump files. If no object or core operand
is specified, but the -k option is specified, mdb will
default to an object file of /dev/ksyms and a core
file of /dev/kmem. Access to /dev/kmem is restricted
to group sys.
-L 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 may also contain any of the tokens shown
for -I above.
-m Disables demand-loading of kernel module symbols. By
default, mdb will process the list of loaded kernel
modules and perform demand loading of per-module sym-
bol tables. If the -m option is specified, mdb will
not attempt to process the kernel module list or pro-
vide per-module symbol tables. As a result, mdb
modules corresponding to active kernel modules will
not be loaded on startup.
-M Preloads all kernel module symbols. By default, mdb
performs demand-loading for kernel module symbols: the
complete symbol table for a module is read when an
address is that module's text or data section is
referenced. With the -M option, mdb will load the com-
plete 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 dis-
abled. Unless noted below, each option is off by
default. mdb recognizes the following option argu-
ments:
adb Enable stricter adb(1) compatibility. The prompt
will be set to the empty string and many mdb
features, such as the output pager, will be dis-
abled.
follow_child
The debugger will follow the child process if a
fork(2)) system call occurs. By default, the
debugger remains attached to the original
target process (the parent).
SunOS 5.8 Last change: 14 Sep 1999 28
User Commands mdb(1)
ignoreeof
The debugger will not exit when an EOF sequence
(^D) is entered at the terminal. The ::quit dcmd
must be used to quit.
pager The output pager will be enabled (default).
repeatlast
If a NEWLINE is entered as the complete command
at the terminal, mdb will repeat the previous
command with the current value of dot. This
option is implied by -o adb.
-p pid
Attach to and stop the specified process-id. mdb will
use the /proc/pid/object/a.out file as the executable
file pathname.
-P Sets the command prompt. The default prompt is '> '.
-R Sets root directory for pathname expansion. By
default, the root directory is derived from the path-
name of the mdb executable itself. The root directory
is substituted in place of the %r token during path-
name expansion.
-s distance
Sets the symbol matching distance for address-to-
symbol-name conversions to the specified distance. By
default, mdb sets the distance to zero, which enables
a smart-matching mode. Each ELF symbol table entry
includes a value V and size S, representing the size
of the function or data object in bytes. In smart
mode, mdb matches an address A with the given symbol
if A is in the range [ V, V + S ). If any non-zero
distance is specified, the same algorithm is used, but
S in the expression above is always the specified
absolute distance and the symbol size is ignored.
-S Suppresses processing of the user's ~/.mdbrc file. By
default, mdb will read and process 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 will not be read.
-u Forces user debugging mode. By default, mdb will
attempt to infer whether the object and core file
operands refer to a user executable and core dump, or
to a pair of operating system crash dump files. The -u
option forces mdb to assume these files are not
operating system crash dump files.
SunOS 5.8 Last change: 14 Sep 1999 29
User Commands mdb(1)
-V Sets disassembler version. By default, mdb will
attempt to infer the appropriate disassembler version
for the debug target. The disassembler can be set
explicitly using the -V option. The ::disasms dcmd
lists the available disassembler versions.
-w Opens the specified object and core files for writing.
-y Sends explicit terminal initialization sequences for
tty mode. Some terminals, such as require explicit
initialization sequences to switch into a tty mode.
Without this initialization sequence, terminal
features such as standout mode may 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 will attempt to infer the name of the
executable file that produced the core using several
different algorithms. If no executable is found, mdb
will still execute, but some symbol information may be
unavailable.
suffix
Specifies the numerical suffix representing a pair of
operating system crash dump files. For example, if the
suffix is '3', mdb infers that it should examine the
files 'unix.3' and 'vmcore.3'. The string of digits
will not be interpreted as a suffix if an actual file
of the same name is present in the current directory.
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.
SunOS 5.8 Last change: 14 Sep 1999 30
User Commands mdb(1)
ENVIRONMENT VARIABLES
HISTSIZE
This variable is used to determine the maximum length
of the command history list. If this variable is not
present, the default length is 128.
HOME This variable is used to determine the pathname of the
user's home directory, where a .mdbrc file may reside.
If this variable is not present, no .mdbrc processing
will occur.
SHELL This variable is used to determine the pathname of the
shell used to process shell escapes requested using
the ! meta-character. If this variable is not present,
/bin/sh is used.
FILES
$HOME/.mdbrc
User mdb initialization file. The .mdbrc file, if
present, is processed after the debug target has been
initialized, but before module auto-loading is per-
formed or any commands have been read from standard
input.
/dev/kmem
Kernel virtual memory image device. This device spe-
cial file is used as the core file when examining the
live operating system.
/dev/ksyms
Kernel symbol table device. This device special file
is used as the object file when examining the live
operating system.
/proc/pid/*
Process information files that are read when examining
and controlling user processes.
/usr/lib/adb
/usr/platform/platform-name/lib/adb
Default directories for macro files that are read with
the $< and $<< dcmds. platform-name is the name of the
platform, derived either from information in a core
file or crash dump, or from the current machine as if
by uname -i (see uname(1)).
/usr/lib/mdb
/usr/platform/platform-name/lib/mdb
Default directories for debugger modules that are
loaded using the ::load dcmds. platform-name is the
SunOS 5.8 Last change: 14 Sep 1999 31
User Commands mdb(1)
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:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
| ____________________________|_____________________________|_
| Availability | SUNWmdb (32-bit), SUNWmdbx|
| | (64-bit) |
|_____________________________|_____________________________|
| Interface Stability | Evolving |
|_____________________________|_____________________________|
SEE ALSO
adb(1), gcore(1), proc(1), pgrep(1), ps(1), stty(1),
truss(1), uname(1), coreadm(1M), dumpadm(1M), savecore(1M),
fork(2), _lwp_self(2), pipe(2), elf(3ELF), libthread(3THR),
libthread_db(3LIB), signal(3C), signal(3HEAD),
thr_self(3THR), core(4), libkvm(4), proc(4), attributes(5),
largefile(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 may result in a system panic in the event the
user damages a kernel data structure.
SunOS 5.8 Last change: 14 Sep 1999 32
User Commands mdb(1)
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. If a core file from one operating system
release is examined on a different operating system release,
the run-time link-editor debugging interface (librtld_db)
may not be able to initialize. In this case, symbol informa-
tion for shared libraries will not be available. Further-
more, since shared mappings are not present in user core
files, the text section and read-only data of shared
libraries may not match the data that was present in the
process at the time it dumped core. Core files from Solaris
Intel systems may not be examined on Solaris SPARC systems,
and vice-versa.
Limitations on Examining Crash Dump Files
Crash dumps from Solaris 7 and earlier releases may 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 may prevent some dcmds or walkers from working prop-
erly. mdb will issue a warning message if it detects this
condition. Crash dumps from Solaris Intel systems may not be
examined on Solaris SPARC systems, and vice-versa.
Relationship Between 32-bit and 64-bit Debugger
mdb provides support for debugging both 32-bit and 64-bit
programs. Once it has examined the target and determined its
data model, mdb will automatically re-execute 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 will use the
same data model as the primary target. Only the 64-bit
debugger may 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.
Developer Information
The Solaris Modular Debugger Guide provides a more detailed
description of mdb features, as well as information for
debugger module developers.
SunOS 5.8 Last change: 14 Sep 1999 33
|
 |
|
|
