path: root/usr/src/man/man1/mdb.1

'\" te
.\" Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved.
.\" Copyright (c) 2012, Joyent, Inc. All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH MDB 1 "Oct 05, 2012"
.SH NAME
mdb \- modular debugger
.SH SYNOPSIS
.LP
.nf
\fBmdb\fR [\fB-fkmuwyAFKMSUW\fR] [\(+-o \fIoption\fR] [\fB-p\fR \fIpid\fR] [\fB-s\fR \fIdistance\fR]
     [\fB-I\fR \fIpath\fR] [\fB-L\fR \fIpath\fR] [\fB-P\fR \fIprompt\fR] [\fB-R\fR \fIroot\fR]
     [\fB-V\fR \fIdis-version\fR] [\fB-e\fR \fIexpr\fR] [object [core] | core | suffix]
.fi

.SH DESCRIPTION
.SS "Introduction"
.sp
.LP
The \fBmdb\fR utility is an extensible utility for low-level debugging and
editing of the live operating system, operating system crash dumps, user
processes, user process core dumps, and object files. For a more detailed
description of \fBmdb\fR features, refer to the manual, \fISolaris Modular
Debugger Guide\fR.
.sp
.LP
Debugging is the process of analyzing the execution and state of a software
program in order to remove defects. Traditional debugging tools provide
facilities for execution control so that programmers can re-execute programs in
a controlled environment and display the current state of program data or
evaluate expressions in the source language used to develop the program.
.sp
.LP
Unfortunately, these techniques are often inappropriate for debugging complex
software systems such as an operating system, where bugs might not be
reproducible and program state is massive and distributed, for programs that
are highly optimized, have had their debug information removed, or are
themselves low-level debugging tools, or for customer situations where the
developer can only access post-mortem information.
.sp
.LP
\fBmdb\fR 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 \fBmdb\fR module can be used to examine the program in several
different contexts, including live and post-mortem.
.SS "Definitions"
.sp
.LP
The \fItarget\fR is the program being inspected by the debugger. \fBmdb\fR
currently provides support for the following types of targets: user processes,
user process core files, the live operating system (via \fB/dev/kmem\fR and
\fB/dev/ksyms\fR), operating system crash dumps, user process images recorded
inside an operating system crash dump, \fBELF\fR object files, and raw binary
files. Each target exports a standard set of properties, including one or more
address spaces, one or more symbol tables, a set of load objects, and a set of
threads that can be examined using the debugger commands described below.
.sp
.LP
A debugger command, or \fIdcmd\fR (pronounced dee-command) in \fBmdb\fR
terminology, is a routine in the debugger that can access any of the properties
of the current target. \fBmdb\fR parses commands from standard input, and then
executes the corresponding dcmds. Each dcmd can also accept a list of string or
numerical arguments, as shown in the syntax description below. \fBmdb\fR
contains a set of built-in dcmds, described below, that are always available.
You can also extend the capabilities of \fBmdb\fR itself by writing your own
dcmds, as described in the \fISolaris Modular Debugger Guide\fR.
.sp
.LP
A \fIwalker\fR is a set of routines that describe how to walk, or iterate,
through the elements of a particular program data structure. A walker
encapsulates the data structure's implementation from dcmds and from \fBmdb\fR
itself. You can use walkers interactively, or use them as a primitive to build
other dcmds or walkers. As with dcmds, you can extend \fBmdb\fR by implementing
your own walkers as part of a debugger module.
.sp
.LP
A debugger module, or \fIdmod\fR (pronounced dee-mod), is a dynamically loaded
library containing a set of dcmds and walkers. During initialization, \fBmdb\fR
attempts to load dmods corresponding to the load objects present in the target.
You can subsequently load or unload dmods at any time while running \fBmdb\fR.
\fBmdb\fR ships with a set of standard dmods for debugging the Solaris kernel.
The \fISolaris Modular Debugger Guide\fR contains more information on
developing your own debugger modules.
.sp
.LP
A \fImacro file\fR is a text file containing a set of commands to execute.
Macro files are typically used to automate the process of displaying a simple
data structure. \fBmdb\fR provides complete backward compatibility for the
execution of macro files written for \fBadb\fR(1), and the Solaris installation
includes a set of macro files for debugging the Solaris kernel that can be used
with either tool.
.SS "Syntax"
.sp
.LP
The debugger processes commands from standard input. If standard input is a
terminal, \fBmdb\fR provides terminal editing capabilities. \fBmdb\fR can also
process commands from macro files and from dcmd pipelines, described below. The
language syntax is designed around the concept of computing the value of an
expression (typically a memory address in the target), and then applying a dcmd
to that address. The current address location is referred to as \fIdot\fR, and
its value is referenced using ``.''.
.sp
.LP
A \fImetacharacter\fR is one of the following characters:
.sp
.in +2
.nf
[   ]   |   !   /   \e   ?   =   >   $   :   ;
            \fINEWLINE\fR   \fISPACE\fR   \fITAB\fR
.fi
.in -2
.sp

.sp
.LP
A \fIblank\fR is a \fITAB\fR or a \fISPACE\fR. A \fIword\fR is a sequence of
characters separated by one or more non-quoted metacharacters. Some of the
metacharacters only function as delimiters in certain contexts, as described
below. An \fIidentifier\fR 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 \fINEWLINE\fR or semicolon ( \fB;\fR ).
.sp
.LP
A dcmd is denoted by one of the following words or metacharacters:
.sp
.in +2
.nf
/   \e   ?   =   >   $character   :character  ::identifier
.fi
.in -2
.sp

.sp
.LP
dcmds named by metacharacters or prefixed by a single \fB$\fR or \fB:\fR are
provided as built-in operators, and implement complete compatibility with the
command set of the legacy \fBadb\fR(1) utility. Once a dcmd has been parsed,
the \fB/\fR, \fB\e\fR, \fB?\fR, \fB=\fR, \fB>\fR, \fB$\fR, and \fB:\fR
characters are no longer recognized as metacharacters until the termination of
the argument list.
.sp
.LP
A \fIsimple-command\fR is a dcmd followed by a sequence of zero or more
blank-separated words. The words are passed as arguments to the invoked dcmd,
except as specified under \fBQuoting and Arithmetic Expansion\fR below. Each
dcmd returns an exit status that indicates it was either successful, failed, or
was invoked with invalid arguments.
.sp
.LP
A \fIpipeline\fR is a sequence of one or more simple commands separated by
\fB|\fR. Unlike the shell, dcmds in \fBmdb\fR 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 \fBdcmd Pipelines\fR 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.
.sp
.LP
An \fIexpression\fR 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 \fBArithmetic Expansion\fR below.
.SS "Commands"
.sp
.LP
A \fIcommand\fR is one of the following:
.sp
.ne 2
.na
\fB\fIpipeline\fR [\fB!\fR \fIword\fR .\|.\|.] [ \fB;\fR ]\fR
.ad
.sp .6
.RS 4n
A simple-command or pipeline can be optionally suffixed with the \fB!\fR
character, indicating that the debugger should open a \fBpipe\fR(2) and send
the standard output of the last dcmd in the \fBmdb\fR pipeline to an external
process created by executing \fB$SHELL\fR \fB-c\fR followed by the string
formed by concatenating the words after the \fB!\fR character. For more
details, refer to \fBShell Escapes\fR below.
.RE

.sp
.ne 2
.na
\fB\fIexpression\fR \fI pipeline\fR [\fB!\fR \fIword\fR .\|.\|.] [ \fB;\fR ]\fR
.ad
.sp .6
.RS 4n
A simple-command or pipeline can be prefixed with an expression. Before
execution of the pipeline, the value of dot (the variable denoted by
``\fB\&.\fR'') is set to the value of the expression.
.RE

.sp
.ne 2
.na
\fB\fIexpression\fR\fB ,\fR \fIexpression\fR \fIpipeline \fR [\fB!\fR
\fIword\fR .\|.\|.] [ \fB;\fR ]\fR
.ad
.sp .6
.RS 4n
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 \fIcount\fR times before the next dcmd in the pipeline is executed.
The repeat count only applies to the first dcmd in the pipeline.
.RE

.sp
.ne 2
.na
\fB\fB,\fR \fIexpression\fR \fIpipeline\fR [\fB!\fR \fIword\fR .\|.\|.] [
\fB;\fR ]\fR
.ad
.sp .6
.RS 4n
If the initial expression is omitted, dot is not modified but the first dcmd in
the pipeline is repeated according to the value of the expression.
.RE

.sp
.ne 2
.na
\fB\fIexpression\fR [\fB!\fR \fIword\fR .\|.\|.] [ \fB;\fR ]\fR
.ad
.sp .6
.RS 4n
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.
.RE

.sp
.ne 2
.na
\fB\fIexpression\fR\fB,\fR \fIexpression\fR  [\fB!\fR \fI word\fR .\|.\|.] [
\fB;\fR ]\fR
.ad
.sp .6
.RS 4n
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.
.RE

.sp
.ne 2
.na
\fB\fB,\fR \fIexpression \fR  [\fB!\fR \fIword\fR .\|.\|.] [ \fB;\fR ]\fR
.ad
.sp .6
.RS 4n
If the initial expression is omitted, dot is not modified but the previous dcmd
and arguments are repeatedly executed the number of times specified by the
value of the count expression.
.RE

.sp
.ne 2
.na
\fB\fB!\fR \fIword\fR .\|.\|. [ \fB;\fR ]\fR
.ad
.sp .6
.RS 4n
If the command begins with the \fB!\fR character, no dcmds are executed and the
debugger simply executes \fB$SHELL\fR \fB-c\fR followed by the string formed by
concatenating the words after the \fB!\fR character.
.RE

.SS "Comments"
.sp
.LP
A word beginning with \fB//\fR causes that word and all the subsequent
characters up to a \fINEWLINE\fR to be ignored.
.SS "Arithmetic Expansion"
.sp
.LP
Arithmetic expansion is performed when an \fBmdb\fR command is preceded by an
optional expression representing a start address, or a start address and a
repeat count. Arithmetic expansion can also be performed to compute a numerical
argument for a dcmd. An arithmetic expression can appear in an argument list
enclosed in square brackets preceded by a dollar sign (\fB$[ expression ]\fR),
and is replaced by the value of the expression.
.sp
.LP
Expressions can contain any of the following special words:
.sp
.ne 2
.na
\fB\fIinteger\fR\fR
.ad
.RS 22n
The specified integer value. Integer values can be prefixed with \fB0i\fR or
\fB0I\fR to indicate binary values, \fB0o\fR or \fB0O\fR to indicate octal
values, \fB0t\fR or \fB0T\fR to indicate decimal values, and \fB0x\fR or
\fB0X\fR to indicate hexadecimal values (the default).
.RE

.sp
.ne 2
.na
\fB0[tT][0-9]+.[0-9]+\fR
.ad
.RS 22n
The specified decimal floating point value, converted to its \fBIEEE\fR
double-precision floating point representation.
.RE

.sp
.ne 2
.na
\fB\&'\fIcccccccc\fR'\fR
.ad
.RS 22n
The integer value computed by converting each character to a byte equal to its
\fBASCII\fR 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.
.RE

.sp
.ne 2
.na
\fB<\fIidentifier\fR\fR
.ad
.RS 22n
The value of the variable named by \fIidentifier\fR.
.RE

.sp
.ne 2
.na
\fB\fIidentifier\fR\fR
.ad
.RS 22n
The value of the symbol named by \fIidentifier\fR.
.RE

.sp
.ne 2
.na
\fB(\fIexpression\fR)\fR
.ad
.RS 22n
The value of \fIexpression\fR.
.RE

.sp
.ne 2
.na
\fB\&.\fR
.ad
.RS 22n
The value of dot.
.RE

.sp
.ne 2
.na
\fB&\fR
.ad
.RS 22n
The most recent value of dot used to execute a dcmd.
.RE

.sp
.ne 2
.na
\fB+\fR
.ad
.RS 22n
The value of dot incremented by the current increment.
.RE

.sp
.ne 2
.na
\fB^\fR
.ad
.RS 22n
The value of dot decremented by the current increment.
.RE

.sp
.LP
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 \fBFormatting dcmds\fR below.
.sp
.LP
Unary operators are right associative and have higher precedence than binary
operators. The unary operators are:
.sp
.ne 2
.na
\fB#\fIexpression\fR\fR
.ad
.RS 23n
Logical negation.
.RE

.sp
.ne 2
.na
\fB~\fIexpression\fR\fR
.ad
.RS 23n
Bitwise complement.
.RE

.sp
.ne 2
.na
\fB-\fIexpression\fR\fR
.ad
.RS 23n
Integer negation.
.RE

.sp
.ne 2
.na
\fB%\fIexpression\fR\fR
.ad
.RS 23n
The value of a pointer-sized quantity at the object file location corresponding
to virtual address \fIexpression\fR in the target's virtual address space.
.RE

.sp
.ne 2
.na
\fB%/[csil]/\fIexpression\fR\fR
.ad
.RS 23n
The value of a char, short, int, or long-sized quantity at the object file
location corresponding to virtual address \fIexpression\fR in the target's
virtual address space.
.RE

.sp
.ne 2
.na
\fB%/[1248]/\fIexpression\fR\fR
.ad
.RS 23n
The value of a one, two, four, or eight-byte quantity at the object file
location corresponding to virtual address \fIexpression\fR in the target's
virtual address space.
.RE

.sp
.ne 2
.na
\fB*\fIexpression\fR\fR
.ad
.RS 23n
The value of a pointer-sized quantity at virtual address \fIexpression\fR in
the target's virtual address space.
.RE

.sp
.ne 2
.na
\fB*/[csil]/\fIexpression\fR\fR
.ad
.RS 23n
The value of a char, short, int, or long-sized quantity at virtual address
\fIexpression\fR in the target's virtual address space.
.RE

.sp
.ne 2
.na
\fB*/[1248]/\fIexpression\fR\fR
.ad
.RS 23n
The value of a one, two, four, or eight-byte quantity at virtual address
\fIexpression\fR in the target's virtual address space.
.RE

.sp
.LP
Binary operators are left associative and have lower precedence than unary
operators. The binary operators, in order of precedence from highest to lowest,
are:
.sp
.ne 2
.na
\fB\fB*\fR\fR
.ad
.RS 6n
Integer multiplication.
.RE

.sp
.ne 2
.na
\fB\fB%\fR\fR
.ad
.RS 6n
Integer division.
.RE

.sp
.ne 2
.na
\fB\fB#\fR\fR
.ad
.RS 6n
Left-hand side rounded up to next multiple of right-hand side.
.RE

.sp
.ne 2
.na
\fB\fB+\fR\fR
.ad
.RS 6n
Integer addition.
.RE

.sp
.ne 2
.na
\fB\fB-\fR\fR
.ad
.RS 6n
Integer subtraction.
.RE

.sp
.ne 2
.na
\fB\fB<<\fR\fR
.ad
.RS 6n
Bitwise shift left.
.RE

.sp
.ne 2
.na
\fB\fB>>\fR\fR
.ad
.RS 6n
Bitwise shift right.
.RE

.sp
.ne 2
.na
\fB\fB==\fR\fR
.ad
.RS 6n
Logical equality.
.RE

.sp
.ne 2
.na
\fB\fB!=\fR\fR
.ad
.RS 6n
Logical inequality.
.RE

.sp
.ne 2
.na
\fB\fB&\fR\fR
.ad
.RS 6n
Bitwise AND.
.RE

.sp
.ne 2
.na
\fB\fB\fR^\fR
.ad
.RS 6n
Bitwise exclusive OR.
.RE

.sp
.ne 2
.na
\fB\fB|\fR\fR
.ad
.RS 6n
Bitwise inclusive OR.
.RE

.SS "Quoting"
.sp
.LP
Each metacharacter described above (see \fBSyntax\fR) terminates a word unless
quoted. Characters can be quoted (forcing \fBmdb\fR to interpret each character
as itself without any special significance) by enclosing them in a pair of
single (\fB\&' '\fR) or double (\fB" "\fR) quote marks. A single quote cannot
appear within single quotes. Inside double quotes, \fBmdb\fR recognizes the C
programming language character escape sequences.
.SS "Shell Escapes"
.sp
.LP
The \fB!\fR character can be used to create a pipeline between an \fBmdb\fR
command and the user's shell. If the $\fBSHELL\fR environment variable is set,
\fBmdb\fR forks and execs this program for shell escapes; otherwise
\fB/bin/sh\fR is used. The shell is invoked with the \fB-c\fR option followed
by a string formed by concatenating the words after the \fB!\fR character. The
\fB!\fR character takes precedence over all other metacharacters, except
semicolon (\fB;\fR) and \fINEWLINE\fR. Once a shell escape is detected, the
remaining characters up to the next semicolon or \fINEWLINE\fR are passed as is
to the shell. The output of shell commands can not be piped to \fBmdb\fR dcmds.
Commands executed by a shell escape have their output sent directly to the
terminal, not to \fBmdb\fR.
.SS "Variables"
.sp
.LP
A \fIvariable\fR 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 \fB>\fR dcmd or
\fB::typeset\fR dcmd, and its attributes can be manipulated using the
\fB::typeset\fR 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).
.sp
.LP
The following variables are defined as persistent:
.sp
.ne 2
.na
\fB0\fR
.ad
.RS 10n
The most recent value printed using the \fB/\fR, \fB\e\fR, \fB?\fR, or \fB=\fR
dcmd.
.RE

.sp
.ne 2
.na
\fB9\fR
.ad
.RS 10n
The most recent count used with the \fB$<\fR dcmd.
.RE

.sp
.ne 2
.na
\fBb\fR
.ad
.RS 10n
The virtual address of the base of the data section.
.RE

.sp
.ne 2
.na
\fBd\fR
.ad
.RS 10n
The size of the data section in bytes.
.RE

.sp
.ne 2
.na
\fBe\fR
.ad
.RS 10n
The virtual address of the entry point.
.RE

.sp
.ne 2
.na
\fBm\fR
.ad
.RS 10n
The initial bytes (magic number) of the target's primary object file, or zero
if no object file has been read yet.
.RE

.sp
.ne 2
.na
\fBt\fR
.ad
.RS 10n
The size of the text section in bytes.
.RE

.sp
.ne 2
.na
\fBhits\fR
.ad
.RS 10n
The count of the number of times the matched software event specifier has been
matched. See \fBEvent Callbacks\fR, below.
.RE

.sp
.ne 2
.na
\fBthread\fR
.ad
.RS 10n
The thread identifier of the current representative thread. The value of the
identifier depends on the threading model used by the current target. See
\fBThread Support\fR, below.
.RE

.sp
.LP
In addition, the \fBmdb\fR kernel and process targets export the current values
of the representative thread's register set as named variables. The names of
these variables depend on the target's platform and instruction set
architecture.
.SS "Symbol Name Resolution"
.sp
.LP
As explained in the \fBSyntax\fR description above, a symbol identifier present
in an expression context evaluates to the value of this symbol. The value
typically denotes the virtual address of the storage associated with the symbol
in the target's virtual address space. A target can support multiple symbol
tables including, but not limited to, a primary executable symbol table, a
primary dynamic symbol table, a run-time link-editor symbol table, and standard
and dynamic symbol tables for each of a number of load objects (such as shared
libraries in a user process, or kernel modules in the 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 \fBELF\fR symbol
tables only contain entries for external, global, and static symbols; automatic
symbols do not appear in the symbol tables processed by \fBmdb\fR.
.sp
.LP
Additionally, \fBmdb\fR 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 \fB::nmadd\fR and
\fB::nmdel\fR dcmds. The \fB::nm\fR \fB-P\fR 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 \fBmdb\fR converts a symbolic name to an address, or an address
to the nearest symbol.
.sp
.LP
As targets contain multiple symbol tables, and each symbol table can include
symbols from multiple object files, different symbols with the same name can
exist. \fBmdb\fR uses the backquote (\fB`\fR) character as a symbol name
scoping operator to allow the programmer to obtain the value of the desired
symbol in this situation. The programmer can specify the scope used to resolve
a symbol name as either: \fIobject\fR\fB`\fR\fIname\fR, or
\fIfile\fR\fB`\fR\fIname\fR, or \fIobject\fR\fB`\fR\fIfile\fR\fB`\fR\fIname\fR.
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
\fBSTT_FILE\fR in the specified object's symbol table. The object identifier's
interpretation depends on the target type.
.sp
.LP
The \fBmdb\fR kernel target expects \fIobject\fR to specify the basename of a
loaded kernel module. For example, the symbol name
.sp
.in +2
.nf
specfs`_init
.fi
.in -2
.sp

.sp
.LP
evaluates to the value of the \fB_init\fR symbol in the \fBspecfs\fR kernel
module.
.sp
.LP
The \fBmdb\fR process target expects \fIobject\fR to specify the name of the
executable or of a loaded shared library. It can take any of the following
forms:
.RS +4
.TP
1.
An exact match (that is, a full pathname): \fB/usr/lib/libc.so.1\fR
.RE
.RS +4
.TP
2.
An exact basename match: \fBlibc.so.1\fR
.RE
.RS +4
.TP
3.
An initial basename match up to a ``\fB\&.\fR'' suffix: \fBlibc.so\fR or
\fBlibc\fR
.RE
.RS +4
.TP
4.
The literal string \fBa.out\fR is accepted as an alias for the executable.
.RE
.sp
.LP
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
"\fBLM\fR" followed by the link-map id in hexadecimal followed by an additional
backquote. For example, the symbol name
.sp
.in +2
.nf
LM0`libc.so.1`_init
.fi
.in -2
.sp

.sp
.LP
evaluates to the value of the \fB_init\fR symbol in the \fBlibc.so.1\fR library
that is loaded on link-map 0 (\fBLM_ID_BASE\fR). 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 \fILinker and Libraries Guide\fR and \fBdlopen\fR(3C). Link-map
identifiers are displayed when symbols are printed according to the setting of
the \fBshowlmid\fR option, as described under OPTIONS.
.sp
.LP
In the case of a naming conflict between symbols and hexadecimal integer
values, \fBmdb\fR attempts to evaluate an ambiguous token as a symbol first,
before evaluating it as an integer value. For example, the token \fBf\fR can
either refer to the decimal integer value \fB15\fR specified in hexadecimal
(the default base), or to a global variable named \fBf\fR 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 \fB0x\fR or \fB0X\fR prefix.
.SS "dcmd and Walker Name Resolution"
.sp
.LP
As described earlier, each \fBmdb\fR dmod provides a set of dcmds and walkers.
dcmds and walkers are tracked in two distinct, global namespaces. \fBmdb\fR
also keeps track of a dcmd and walker namespace associated with each dmod.
Identically named dcmds or walkers within a given dmod are not allowed: a dmod
with this type of naming conflict fails to load. Name conflicts between dcmds
or walkers from different dmods are allowed in the global namespace. In the
case of a conflict, the first dcmd or walker with that particular name to be
loaded is given precedence in the global namespace. Alternate definitions are
kept in a list in load order. The backquote character (\fB`\fR) can be used in
a dcmd or walker name as a scoping operator to select an alternate definition.
For example, if dmods \fBm1\fR and \fBm2\fR each provide a dcmd \fBd\fR, and
\fBm1\fR is loaded prior to \fBm2\fR, then:
.sp
.ne 2
.na
\fB\fB::d\fR\fR
.ad
.RS 10n
Executes \fBm1\fR's definition of \fBd\fR.
.RE

.sp
.ne 2
.na
\fB\fB::m1`d\fR\fR
.ad
.RS 10n
Executes \fBm1\fR's definition of \fBd\fR.
.RE

.sp
.ne 2
.na
\fB\fB::m2`d\fR\fR
.ad
.RS 10n
Executes \fBm2'\fRs definition of \fBd\fR.
.RE

.sp
.LP
If module \fBm1\fR were now unloaded, the next dcmd on the global definition
list (\fBm2`d\fR) would be promoted to global visibility. The current
definition of a dcmd or walker can be determined using the \fB::which\fR dcmd,
described below. The global definition list can be displayed using the
\fB::which\fR \fB-v\fR option.
.SS "dcmd Pipelines"
.sp
.LP
dcmds can be composed into a pipeline using the \fB|\fR operator. The purpose
of a pipeline is to pass a list of values, typically virtual addresses, from
one dcmd or walker to another. Pipeline stages might be used to map a pointer
from one type of data structure to a pointer to a corresponding data structure,
to sort a list of addresses, or to select the addresses of structures with
certain properties.
.sp
.LP
\fBmdb\fR executes each dcmd in the pipeline in order from left to right. The
leftmost dcmd is executed using the current value of dot, or using the value
specified by an explicit expression at the start of the command. When a \fB|\fR
operator is encountered, \fBmdb\fR creates a pipe (a shared buffer) between the
output of the dcmd to its left and the \fBmdb\fR 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 \fBmdb\fR were reading this
data from standard input. Each line must consist of an arithmetic expression
terminated by a \fINEWLINE\fR or semicolon (\fB;\fR). 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.
.sp
.LP
When the dcmd to the left of a \fB|\fR operator completes, the list of values
associated with the pipe is then used to invoke the dcmd to the right of the
\fB|\fR operator. For each value in the list, dot is set to this value and the
right-hand dcmd is executed. Only the rightmost dcmd in the pipeline has its
output printed to standard output. If any dcmd in the pipeline produces output
to standard error, these messages are printed directly to standard error and
are not processed as part of the pipeline.
.SS "Signal Handling"
.sp
.LP
The debugger ignores the \fBPIPE\fR and \fBQUIT\fR signals. The \fBINT\fR
signal aborts the command that is currently executing. The debugger intercepts
and provides special handling for the \fBILL\fR, \fBTRAP\fR, \fBEMT\fR,
\fBFPE\fR, \fBBUS\fR, and \fBSEGV\fR signals. If any of these signals are
generated asynchronously (that is, delivered from another process using
\fBkill\fR(2)), \fBmdb\fR 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, \fBmdb\fR provides a menu of
choices allowing the user to force a core dump, quit without producing a core
dump, stop for attach by a debugger, or attempt to resume. The resume option
aborts all active commands and unload the dmod whose dcmd was active at the
time the fault occurred. It can then be subsequently re-loaded by the user. The
resume option provides limited protection against buggy dcmds. Refer to
WARNINGS, \fBUse of the Error Recovery Mechanism\fR, below for information
about the risks associated with the resume option.
.SS "Command Re-entry"
.sp
.LP
The text of the last \fBHISTSIZE \fR (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.
.SS "In-line Editing"
.sp
.LP
If standard input is a terminal device, \fBmdb\fR provides some simple
emacs-style facilities for editing the command line. The \fBsearch\fR,
\fBprevious\fR, and \fBnext\fR 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 (\fB^\fR) followed by
a character shown in upper case. The notation for escape sequences is \fBM-\fR
followed by a character. For example, \fBM-f\fR (pronounced meta-eff) is
entered by depressing ESC followed by '\fBf\fR', or by depressing Meta followed
by '\fBf\fR' on keyboards that support a \fBMeta\fR key. A command line is
committed and executed using \fIRETURN\fR or \fINEWLINE\fR. The edit commands
are:
.sp
.ne 2
.na
\fB^F\fR
.ad
.RS 14n
Move cursor forward (right) one character.
.RE

.sp
.ne 2
.na
\fBM-f\fR
.ad
.RS 14n
Move cursor forward one word.
.RE

.sp
.ne 2
.na
\fB^B\fR
.ad
.RS 14n
Move cursor backward (left) one character.
.RE

.sp
.ne 2
.na
\fBM-b\fR
.ad
.RS 14n
Move cursor backward one word.
.RE

.sp
.ne 2
.na
\fB^A\fR
.ad
.RS 14n
Move cursor to start of line.
.RE

.sp
.ne 2
.na
\fB^E\fR
.ad
.RS 14n
Move cursor to end of line.
.RE

.sp
.ne 2
.na
\fB^D\fR
.ad
.RS 14n
Delete current character, if the current line is not empty. If the current line
is empty, \fB^D\fR denotes \fBEOF\fR and the debugger exits.
.RE

.sp
.ne 2
.na
\fBM-^H\fR
.ad
.RS 14n
(Meta-backspace) Delete previous word.
.RE

.sp
.ne 2
.na
\fB^K\fR
.ad
.RS 14n
Delete from the cursor to the end of the line.
.RE

.sp
.ne 2
.na
\fB^L\fR
.ad
.RS 14n
Clear the screen and reprint the current line.
.RE

.sp
.ne 2
.na
\fB^T\fR
.ad
.RS 14n
Transpose current character with next character.
.RE

.sp
.ne 2
.na
\fB^N\fR
.ad
.RS 14n
Fetch the next command from the history. Each time \fB^N\fR is entered, the
next command forward in time is retrieved.
.RE

.sp
.ne 2
.na
\fB^P\fR
.ad
.RS 14n
Fetch the previous command from the history. Each time \fB^P\fR is entered, the
next command backward in time is retrieved.
.RE

.sp
.ne 2
.na
\fB^R[\fIstring\fR]\fR
.ad
.RS 14n
Search backward in the history for a previous command line containing
\fIstring\fR. The string should be terminated by a \fIRETURN\fR or
\fINEWLINE\fR. If \fIstring\fR is omitted, the previous history element
containing the most recent string is retrieved.
.RE

.sp
.LP
The editing mode also interprets the following user-defined sequences as
editing commands. User defined sequences can be read or modified using the
\fBstty\fR(1) command.
.sp
.ne 2
.na
\fBerase\fR
.ad
.RS 11n
User defined erase character (usually \fB^H\fR or \fB^?\fR). Delete previous
character.
.RE

.sp
.ne 2
.na
\fBintr\fR
.ad
.RS 11n
User defined interrupt character (usually \fB^C\fR). Abort the current command
and print a new prompt.
.RE

.sp
.ne 2
.na
\fBkill\fR
.ad
.RS 11n
User defined kill character (usually \fB^U\fR). Kill the entire current command
line.
.RE

.sp
.ne 2
.na
\fBquit\fR
.ad
.RS 11n
User defined quit character (usually \fB^\e\fR). Quit the debugger.
.RE

.sp
.ne 2
.na
\fBsuspend\fR
.ad
.RS 11n
User defined suspend character (usually \fB^Z\fR). Suspend the debugger.
.RE

.sp
.ne 2
.na
\fBwerase\fR
.ad
.RS 11n
User defined word erase character (usually \fB^W\fR). Erase the preceding word.
.RE

.sp
.LP
On keyboards that support an extended keypad with arrow keys, \fBmdb\fR
interprets these keystrokes as editing commands:
.sp
.ne 2
.na
\fBup-arrow\fR
.ad
.RS 15n
Fetch the previous command from the history (same as \fB^P\fR).
.RE

.sp
.ne 2
.na
\fBdown-arrow\fR
.ad
.RS 15n
Fetch the next command from the history (same as \fB^N\fR).
.RE

.sp
.ne 2
.na
\fBleft-arrow\fR
.ad
.RS 15n
Move cursor backward one character (same as \fB^B\fR).
.RE

.sp
.ne 2
.na
\fBright-arrow\fR
.ad
.RS 15n
Move cursor forward one character (same as \fB^F\fR).
.RE

.SS "Output Pager"
.sp
.LP
\fBmdb\fR provides a built-in output pager. The output pager is enabled if the
debugger's standard output is a terminal device. Each time a command is
executed, \fBmdb\fR pauses after one screenful of output is produced and
displays a pager prompt:
.sp
.in +2
.nf
 >> More [<space>, <cr>, q, n, c, a] ?
.fi
.in -2
.sp

.sp
.LP
The following key sequences are recognized by the pager:
.sp
.ne 2
.na
\fB\fISPACE\fR\fR
.ad
.RS 25n
Display the next screenful of output.
.RE

.sp
.ne 2
.na
\fBa, A\fR
.ad
.RS 25n
Abort the current top-level command and return to the prompt.
.RE

.sp
.ne 2
.na
\fBc, C\fR
.ad
.RS 25n
Continue displaying output without pausing at each screenful until the current
top-level command is complete.
.RE

.sp
.ne 2
.na
\fBn, N, \fINEWLINE\fR, \fIRETURN\fR\fR
.ad
.RS 25n
Display the next line of output.
.RE

.sp
.ne 2
.na
\fBq, Q, ^C, ^\e\fR
.ad
.RS 25n
Quit (abort) the current dcmd only.
.RE

.SS "Formatting dcmds"
.sp
.LP
The \fB/\fR, \fB\e\fR, \fB?\fR, and \fB=\fR metacharacters are used to denote
the special output formatting dcmds. Each of these dcmds accepts an argument
list consisting of one or more format characters, repeat counts, or quoted
strings. A format character is one of the \fBASCII\fR 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 (\fB$[ ]\fR). A string argument must be enclosed in double-quotes (\fB"
"\fR). No blanks are necessary between format arguments.
.sp
.LP
The formatting dcmds are:
.sp
.ne 2
.na
\fB\fB/\fR\fR
.ad
.RS 6n
Display data from the target's virtual address space starting at the virtual
address specified by dot.
.RE

.sp
.ne 2
.na
\fB\fB\e\fR\fR
.ad
.RS 6n
Display data from the target's physical address space starting at the physical
address specified by dot.
.RE

.sp
.ne 2
.na
\fB\fB?\fR\fR
.ad
.RS 6n
Display data from the target's primary object file starting at the object file
location corresponding to the virtual address specified by dot.
.RE

.sp
.ne 2
.na
\fB\fB=\fR\fR
.ad
.RS 6n
Display the value of dot itself in each of the specified data formats. The
\fB=\fR dcmd is therefore useful for converting between bases and performing
arithmetic.
.RE

.sp
.LP
In addition to dot, \fBmdb\fR keeps track of another global value called the
\fIincrement\fR. 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 \fB4\fR. The \fB+\fR character (described under
\fBArithmetic Expansion\fR above) would now evaluate to the value \fBA + 4\fR,
and could be used to reset dot to the address of the next data object for a
subsequent dcmd.
.sp
.LP
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 \fBmdb\fR using the
\fB::formats\fR dcmd. The format characters are:
.sp

.sp
.TS
l l
l l .
\fB+\fR	T{
increment dot by the count (variable size)
T}
\fB-\fR	T{
decrement dot by the count (variable size)
T}
B	hexadecimal int (1 byte)
C	T{
character using C character notation (1 byte)
T}
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	T{
address and disassembled instruction (variable size)
T}
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	T{
string using C string notation (variable size)
T}
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)
^	T{
decrement dot by increment * count (variable size)
T}
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)
.TE

.sp
.LP
The \fB/\fR, \fB\e\fR, and \fB?\fR formatting dcmds can also be used to write
to the target's virtual address space, physical address space, or object file
by specifying one of the following modifiers as the first format character, and
then specifying a list of words that are either immediate values or expressions
enclosed in square brackets preceded by a dollar sign (\fB$[ ]\fR).
.sp
.LP
The write modifiers are:
.sp
.ne 2
.na
\fB\fBv\fR\fR
.ad
.RS 5n
Write the lowest byte of the value of each expression to the target beginning
at the location specified by dot.
.RE

.sp
.ne 2
.na
\fB\fBw\fR\fR
.ad
.RS 5n
Write the lowest two bytes of the value of each expression to the target
beginning at the location specified by dot.
.RE

.sp
.ne 2
.na
\fB\fBW\fR\fR
.ad
.RS 5n
Write the lowest 4 bytes of the value of each expression to the target
beginning at the location specified by dot.
.RE

.sp
.ne 2
.na
\fB\fBZ\fR\fR
.ad
.RS 5n
Write the complete 8 bytes of the value of each expression to the target
beginning at the location specified by dot.
.RE

.sp
.LP
The \fB/\fR, \fB\e\fR, and \fB?\fR 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, \fBmdb\fR reads integers of the appropriate size and
stops at the address containing the matching value. If a value \fBV\fR and mask
\fBM\fR are specified, \fBmdb\fR reads integers of the appropriate size and
stops at the address containing a value \fBX\fR where \fB(X & M) == V\fR. 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.
.sp
.LP
The search modifiers are:
.sp

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

.sp
.LP
Notice that for both user and kernel targets, an address space is typically
composed of a set of discontiguous segments. It is not legal to read from an
address that does not have a corresponding segment. If a search reaches a
segment boundary without finding a match, it aborts when the read past the end
of the segment boundary fails.
.SS "Execution Control"
.sp
.LP
\fBmdb\fR provides facilities for controlling and tracing the execution of a
live running program. Currently, only the user process target provides support
for execution control. \fBmdb\fR provides a simple model of execution control:
a target process can be started from within the debugger using \fB::run\fR, or
\fBmdb\fR can attach to an existing process using \fB:A\fR, \fB::attach\fR, or
the \fB-p\fR command-line option, as described below. A list of traced software
events can be specified by the user. Each time a traced event occurs in the
target process, all threads in the target stop, the thread that triggered the
event is chosen as the representative thread, and control returns to the
debugger. Once the target program is set running, control can be asynchronously
returned to the debugger by typing the user-defined interrupt character
(typically \fB^C\fR).
.sp
.LP
A \fBsoftware event\fR is a state transition in the target program that is
observed by the debugger. For example, the debugger can observe the transition
of a program counter register to a value of interest (a breakpoint) or the
delivery of a particular signal.
.sp
.LP
A \fBsoftware event specifier\fR is a description of a class of software events
that is used by the debugger to instrument the target program in order to
observe these events. The \fB::events\fR dcmd is used to list the software
event specifiers. A set of standard properties is associated with each event
specifier, as described under \fB::events\fR, below.
.sp
.LP
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 \fB::bp\fR, \fB::fltbp\fR, \fB::sigbp\fR,
\fB::sysbp\fR, or \fB::wp\fR. Each specifier has an associated callback (an
\fBmdb\fR command string to execute as if it had been typed at the command
prompt) and a set of properties, as described below. Any number of specifiers
for the same event can be created, each with different callbacks and
properties. The current list of traced events and the properties of the
corresponding event specifiers can be displayed using the \fB::events\fR dcmd.
The event specifier properties are defined as part of the description of the
\fB::events\fR and \fB::evset\fR dcmds, below.
.sp
.LP
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.
.SS "Event Callbacks"
.sp
.LP
The \fB::evset\fR dcmd and event tracing dcmds allow you to associate an event
callback (using the \fB-c\fR option) with each event specifier. The event
callbacks are strings that represent \fBmdb\fR commands to execute when the
corresponding event occurs in the target. These commands are executed as if
they had been typed at the command prompt. Before executing each callback, the
dot variable is set to the value of the representative thread's program counter
and the "\fBhits\fR" variable is set to the number of times this specifier has
been matched, including the current match.
.sp
.LP
If the event callbacks themselves contain one or more commands to continue the
target (for example, \fB::cont\fR or \fB::step\fR), these commands do not
immediately continue the target and wait for it to stop again. Instead, inside
of an event callback, the continue dcmds note that a continue operation is now
pending, and then return immediately. Therefore, if multiple dcmds are included
in an event callback, the step or continue dcmd should be the last command
specified. Following the execution of \fBall\fR event callbacks, the target
immediately resumes execution if \fBall\fR matching event callbacks requested a
continue. If conflicting continue operations are requested, the operation with
the highest precedence determines what type of continue occurs. The order of
precedence from highest to lowest is: step, step-over (next), step-out,
continue.
.SS "Thread Support"
.sp
.LP
\fBmdb\fR provides facilities to examine the stacks and registers of each
thread associated with the target. The persistent "\fBthread\fR" variable
contains the current representative thread identifier. The format of the thread
identifier depends on the target. The \fB::regs\fR and \fB::fpregs\fR 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 \fB>\fR dcmd
to the corresponding named variable.
.sp
.LP
The \fBmdb\fR kernel target exports the virtual address of the corresponding
internal thread structure as the identifier for a given thread. The \fISolaris
Modular Debugger Guide\fR provides more information on debugging support for
threads in the Solaris kernel. The \fBmdb\fR process target provides proper
support for examination of multi-threaded user processes that use the native
\fBlwp_*\fR interfaces, \fB/usr/lib/libthread.so\fR or
\fB/usr/lib/lwp/libthread.so\fR. When debugging a live user process, \fBmdb\fR
detects if a single threaded process \fBdlopen\fRs or closes \fBlibthread\fR
and automatically adjusts its view of the threading model on-the-fly. The
process target thread identifiers corresponds to either the \fBlwpid_t\fR,
\fBthread_t\fR, or \fBpthread_t\fR of the representative, depending on the
threading model used by the application.
.sp
.LP
If \fBmdb\fR is debugging a user process target and the target makes use of
compiler-supported thread-local storage, \fBmdb\fR automatically evaluates
symbol names referring to thread-local storage to the address of the storage
corresponding to the current representative thread. The \fB::tls\fR built-in
dcmd can be used to display the value of the symbol for threads other than the
representative thread.
.SS "Built-in dcmds"
.sp
.LP
\fBmdb\fR 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, \fBmdb\fR provides a mnemonic
equivalent (\fB::identifier\fR) for the legacy \fBadb\fR(1) dcmd names. For
example, \fB::quit\fR is provided as the equivalent of \fB$q\fR. Programmers
who are experienced with \fBadb\fR(1) or who appreciate brevity or arcana can
prefer the \fB$\fR or \fB:\fR forms of the built-ins. Programmers who are new
to \fBmdb\fR might prefer the more verbose \fB::\fR form. The built-ins are
shown in alphabetical order. If a \fB$\fR or \fB:\fR form has a
\fB::identifier\fR equivalent, it is shown underneath the \fB::identifier\fR
form. The built-in dcmds are:
.sp
.ne 2
.na
\fB> \fIvariable-name\fR\fR
.ad
.br
.na
\fB\fB>\fR/\fImodifier\fR/\fIvariable-name\fR\fR
.ad
.sp .6
.RS 4n
Assign the value of dot to the specified named variable. Some variables are
read-only and can not be modified. If the \fB>\fR is followed by a modifier
character surrounded by \fB/ /\fR, then the value is modified as part of the
assignment. The modifier characters are:
.sp
.ne 2
.na
\fB\fBc\fR\fR
.ad
.RS 5n
unsigned char quantity (1-byte)
.RE

.sp
.ne 2
.na
\fB\fBs\fR\fR
.ad
.RS 5n
unsigned short quantity (2-byte)
.RE

.sp
.ne 2
.na
\fB\fBi\fR\fR
.ad
.RS 5n
unsigned int quantity (4-byte)
.RE

.sp
.ne 2
.na
\fB\fBl\fR\fR
.ad
.RS 5n
unsigned long quantity (4-byte in 32-bit, 8-byte in 64-bit)
.RE

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 \fBmdb\fR */\fImodifier\fR/ and %/\fImodifier\fR/
syntax should be used instead.
.RE

.sp
.ne 2
.na
\fB\fB$<\fR \fImacro-name\fR\fR
.ad
.sp .6
.RS 4n
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 '\fB/\fR'), \fBmdb\fR 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.
.RE

.sp
.ne 2
.na
\fB\fB$<<\fR \fImacro-name\fR\fR
.ad
.sp .6
.RS 4n
Read and execute commands from the specified macro file (as with \fB$<\fR), but
do not close the current open macro file.
.RE

.sp
.ne 2
.na
\fB\fB$?\fR\fR
.ad
.sp .6
.RS 4n
Print the process-\fBID\fR 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.
.RE

.sp
.ne 2
.na
\fB[ \fIaddress\fR ] \fB$C\fR [ \fIcount\fR ]\fR
.ad
.sp .6
.RS 4n
Print a C stack backtrace, including stack frame pointer information. If the
dcmd is preceded by an explicit \fIaddress\fR, 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 \fIcount\fR arguments are displayed for each stack frame in the
output.
.RE

.sp
.ne 2
.na
\fB[ \fIbase\fR ] \fB$d\fR\fR
.ad
.sp .6
.RS 4n
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 \fIbase\fR; otherwise
the current radix is printed in base 10 (decimal). The default radix is base 16
(hexadecimal).
.RE

.sp
.ne 2
.na
\fB\fB$e\fR\fR
.ad
.sp .6
.RS 4n
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 \fBmdb\fR) or 8 (64-bit
\fBmdb\fR) bytes stored at this location in the target's virtual address space.
The \fB::nm\fR dcmd provides more flexible options for displaying symbol
tables.
.RE

.sp
.ne 2
.na
\fB\fB$P\fR \fIprompt-string\fR\fR
.ad
.sp .6
.RS 4n
Set the prompt to the specified \fIprompt-string\fR. The default prompt
is '\fB>\fR '. The prompt can also be set using \fB::set\fR \fB-P\fR or the
\fB-P\fR command-line option.
.RE

.sp
.ne 2
.na
\fB\fIdistance\fR \fB$s\fR\fR
.ad
.sp .6
.RS 4n
Get or set the symbol matching \fIdistance\fR for address-to-symbol-name
conversions. The symbol matching distance modes are discussed along with the
\fB-s\fR command-line option under OPTIONS. The symbol matching distance can
also be modified using the \fB::set\fR \fB-s\fR option. If no distance is
specified, the current setting is displayed.
.RE

.sp
.ne 2
.na
\fB\fB$v\fR\fR
.ad
.sp .6
.RS 4n
Print a list of the named variables that have non-zero values. The \fB::vars\fR
dcmd provides other options for listing variables.
.RE

.sp
.ne 2
.na
\fB\fIwidth\fR \fB$w\fR\fR
.ad
.sp .6
.RS 4n
Set the output page \fIwidth\fR to the specified value. Typically, this command
is not necessary as \fBmdb\fR queries the terminal for its width and handles
resize events.
.RE

.sp
.ne 2
.na
\fB\fB$W\fR\fR
.ad
.sp .6
.RS 4n
Re-open the target for writing, as if \fBmdb\fR had been executed with the
\fB-w\fR option on the command line. Write mode can also be enabled with the
\fB::set\fR \fB-w\fR option.
.RE

.sp
.ne 2
.na
\fB[ \fIpid\fR ] \fB::attach \fR [ \fIcore\fR | \fIpid\fR ]\fR
.ad
.br
.na
\fB[ \fIpid\fR ] \fB:A\fR [ \fI core\fR | \fIpid\fR ]\fR
.ad
.sp .6
.RS 4n
If the user process target is active, attach to and debug the specified
process-\fBID\fR or \fIcore\fR file. The core file pathname should be specified
as a string argument. The process-\fBID\fR 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 \fBPID\fRs obtained using
\fBpgrep\fR(1) or \fBps\fR(1) should be preceded with "\fB0t\fR" when specified
as expressions.
.RE

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

.sp
.ne 2
.na
\fB\fB::cat\fR \fIfilename\fR ...\fR
.ad
.sp .6
.RS 4n
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
\fB|\fR operator; the programmer can initiate a pipeline using a list of
addresses stored in an external file.
.RE

.sp
.ne 2
.na
\fB\fB::cont\fR [ \fISIG\fR ]\fR
.ad
.br
.na
\fB\fB:c\fR [ \fISIG\fR ]\fR
.ad
.sp .6
.RS 4n
Suspend the debugger, continue the target program, and wait for it to terminate
or stop following a software event of interest. If the target is already
running because the debugger was attached to a running program with the
\fB-o\fR \fBnostop\fR 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 \fBsignal.h\fR(3HEAD)) is specified as an argument, the signal is
immediately delivered to the target as part of resuming its execution. If the
\fBSIGINT\fR signal is traced, control can be asynchronously returned to the
debugger by typing the user-defined interrupt character (usually \fB^C\fR).
This \fBSIGINT\fR signal is automatically cleared and is not observed by the
target the next time it is continued. If no target program is currently
running, \fB::cont\fR starts a new program running as if by \fB::run\fR.
.RE

.sp
.ne 2
.na
\fB\fIaddress\fR \fB::context\fR\fR
.ad
.br
.na
\fB\fIaddress\fR \fB$p\fR\fR
.ad
.sp .6
.RS 4n
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
\fIaddress\fR of its proc structure in the kernel's virtual address space. The
special context address "\fB0\fR" is used to denote the context of the kernel
itself. \fBmdb\fR can only perform a context switch when examining a crash dump
if the dump contains the physical memory pages of the specified user process
(as opposed to just kernel pages). The kernel crash dump facility can be
configured to dump all pages or the pages of the current user process using
\fBdumpadm\fR(1M). The \fB::status\fR dcmd can be used to display the contents
of the current crash dump.
.sp
When the user requests a context switch from the kernel target, \fBmdb\fR
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 \fB/\fR dcmd now formats and displays data from the virtual address space
of the user process, the \fB::mappings\fR dcmd displays the mappings in the
address space of the user process, and so on. The kernel target can be restored
by executing \fB0::context\fR.
.RE

.sp
.ne 2
.na
\fB\fB::dcmds\fR\fR
.ad
.sp .6
.RS 4n
List the available dcmds and print a brief description for each one.
.RE

.sp
.ne 2
.na
\fB[ \fIaddress\fR ] \fB::delete\fR [ \fIid\fR | \fBall\fR ]\fR
.ad
.br
.na
\fB[ \fIaddress\fR ] \fB:d\fR [ \fIid\fR | \fBall\fR ]\fR
.ad
.sp .6
.RS 4n
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 "\fBall\fR" is given, all
event specifiers are deleted, except those that are marked sticky (\fBT\fR
flag). The \fB::events\fR dcmd displays the current list of event specifiers.
.RE

.sp
.ne 2
.na
\fB[ \fIaddress\fR ] \fB::dis\fR [ \fB-fw\fR ] [ \fB-n\fR \fIcount\fR ] [
\fIaddress\fR ]\fR
.ad
.sp .6
.RS 4n
Disassemble starting at or around the \fIaddress\fR 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 \fB-f\fR option is present, instructions are read from
the target's object file instead. The \fB-f\fR option is enabled by default if
the debugger is not currently attached to a live process, core file, or crash
dump. The \fB-w\fR option can be used to force "window"-mode, even if the
address is the start of a known function. The size of the window defaults to
ten instructions; the number of instructions can be specified explicitly using
the \fB-n\fR option.
.RE

.sp
.ne 2
.na
\fB\fB::disasms\fR\fR
.ad
.sp .6
.RS 4n
List the available disassembler modes. When a target is initialized, \fBmdb\fR
attempts to select the appropriate disassembler mode. The user can change the
mode to any of the modes listed using the \fB::dismode\fR dcmd.
.RE

.sp
.ne 2
.na
\fB\fB::dismode\fR [ \fImode\fR ]\fR
.ad
.br
.na
\fB\fB$V\fR [ \fImode\fR ] \fR
.ad
.sp .6
.RS 4n
Get or set the disassembler mode. If no argument is specified, print the
current disassembler mode. If a \fImode\fR argument is specified, switch the
disassembler to the specified mode. The list of available disassemblers can be
displayed using the \fB::disasms\fR dcmd.
.RE

.sp
.ne 2
.na
\fB\fB::dmods\fR [ \fB-l\fR ] [ \fImodule-name\fR ]\fR
.ad
.sp .6
.RS 4n
List the loaded debugger modules. If the \fB-l\fR 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.
.RE

.sp
.ne 2
.na
\fB[ \fIaddress\fR ] \fB::dump\fR [ \fB-eqrstu\fR ] [ \fB-f\fR|\fB-p\fR ]\fR
.ad
.br
.na
\fB#sp;#sp;[ \fB-g\fR \fIbytes\fR ] [ \fB-w\fR \fIparagraphs\fR ]\fR
.ad
.sp .6
.RS 4n
Print a hexadecimal and ASCII memory dump of the 16-byte aligned region of
memory containing the address specified by dot. If a repeat count is specified
for \fB::dump\fR, this is interpreted as a number of bytes to dump rather than
a number of iterations. The \fB::dump\fR dcmd also recognizes the following
options:
.sp
.ne 2
.na
\fB\fB-e\fR\fR
.ad
.RS 17n
Adjusts for endian-ness. The \fB-e\fR option assumes 4-byte words. The \fB-g\fR
option can be used to change the default word size.
.RE

.sp
.ne 2
.na
\fB\fB-f\fR\fR
.ad
.RS 17n
Reads data from the object file location corresponding to the given virtual
address instead of from the target's virtual address space. The \fB-f\fR option
is enabled by default if the debugger is not currently attached to a live
process, core file, or crash dump.
.RE

.sp
.ne 2
.na
\fB\fB-g\fR \fIbytes\fR\fR
.ad
.RS 17n
Displays bytes in groups of \fIbytes\fR. The default group size is 4 bytes. The
group size must be a power of two that divides the line width.
.RE

.sp
.ne 2
.na
\fB\fB-p\fR\fR
.ad
.RS 17n
Interprets \fIaddress\fR as a physical address location in the target's address
space instead of a virtual address.
.RE

.sp
.ne 2
.na
\fB\fB-q\fR\fR
.ad
.RS 17n
Does not print an ASCII decoding of the data.
.RE

.sp
.ne 2
.na
\fB\fB-r\fR\fR
.ad
.RS 17n
Numbers lines relative to the start address instead of with the explicit
address of each line. This option implies the \fB-u\fR option.
.RE

.sp
.ne 2
.na
\fB\fB-s\fR\fR
.ad
.RS 17n
Elides repeated lines.
.RE

.sp
.ne 2
.na
\fB\fB-t\fR\fR
.ad
.RS 17n
Only reads from and displays the contents of the specified addresses, instead
of reading and printing entire lines.
.RE

.sp
.ne 2
.na
\fB\fB-u\fR\fR
.ad
.RS 17n
Unaligns output instead of aligning the output at a paragraph boundary.
.RE

.sp
.ne 2
.na
\fB\fB-w\fR \fIparagraphs\fR\fR
.ad
.RS 17n
Displays paragraphs at 16-byte paragraphs per line. The default number of
\fIparagraphs\fR is one. The maximum value accepted for \fB-w\fR is \fB16\fR.
.RE

.RE

.sp
.ne 2
.na
\fB\fB::echo\fR [ \fIstring\fR | \fIvalue\fR ...]\fR
.ad
.sp .6
.RS 4n
Print the arguments separated by blanks and terminated by a \fINEWLINE\fR to
standard output. Expressions enclosed in \fB$[ ]\fR is  evaluated to a value
and printed in the default base.
.RE

.sp
.ne 2
.na
\fB\fB::eval\fR \fIcommand\fR\fR
.ad
.sp .6
.RS 4n
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.
.RE

.sp
.ne 2
.na
\fB\fB::events\fR [ \fB-av\fR ]\fR
.ad
.br
.na
\fB\fB$b\fR [ \fB-av\fR ]\fR
.ad
.sp .6
.RS 4n
Display the list of software event specifiers. Each event specifier is assigned
a unique \fBID\fR 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 \fB-a\fR option is present. If the
\fB-v\fR option is present, a more verbose display, including the reason for
any specifier inactivity, are shown. Here is some sample output:
.sp
.in +2
.nf
> ::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
>
.fi
.in -2
.sp

The following table explains the meaning of each column. A summary of this
information is available using \fB::help\fR \fBevents\fR.
.sp
.ne 2
.na
\fB\fBID\fR\fR
.ad
.RS 15n
The event specifier identifier. The identifier is shown in square brackets \fB[
]\fR if the specifier is enabled, in parentheses \fB( )\fR if the specifier is
disabled, or in angle brackets \fB< >\fR if the target program is currently
stopped on an event that matches the given specifier.
.RE

.sp
.ne 2
.na
\fB\fBS\fR\fR
.ad
.RS 15n
The event specifier state. The state is one of the following symbols:
.sp
.ne 2
.na
\fB\fB-\fR\fR
.ad
.RS 5n
The event specifier is idle. When no target program is running, all specifiers
are idle. When the target program is running, a specifier can be idle if it
cannot be evaluated (for example, a deferred breakpoint in a shared object that
is not yet loaded).
.RE

.sp
.ne 2
.na
\fB\fB+\fR\fR
.ad
.RS 5n
The event specifier is active. When the target is continued, events of this
type is detected by the debugger.
.RE

.sp
.ne 2
.na
\fB\fB*\fR\fR
.ad
.RS 5n
The event specifier is armed. This state means that the target is currently
running with instrumentation for this type of event. This state is only visible
if the debugger is attached to a running program with the \fB-o\fR \fBnostop\fR
option.
.RE

.sp
.ne 2
.na
\fB\fB!\fR\fR
.ad
.RS 5n
The event specifier was not armed due to an operating system error. The
\fB::events\fR \fB-v\fR option can be used to display more information about
the reason the instrumentation failed.
.RE

.RE

.sp
.ne 2
.na
\fB\fBTA\fR\fR
.ad
.RS 15n
The Temporary, Sticky, and Automatic event specifier properties. One or more of
the following symbols can be shown:
.sp
.ne 2
.na
\fB\fBt\fR\fR
.ad
.RS 5n
The event specifier is temporary, and is deleted the next time the target
stops, regardless of whether it is matched.
.RE

.sp
.ne 2
.na
\fB\fBT\fR\fR
.ad
.RS 5n
The event specifier is sticky, and is not be deleted by \fB::delete\fR
\fBall\fR or \fB:z\fR. The specifier can be deleted by explicitly specifying
its id number to \fB::delete\fR.
.RE

.sp
.ne 2
.na
\fB\fBd\fR\fR
.ad
.RS 5n
The event specifier is automatically disabled when the hit count is equal to
the hit limit.
.RE

.sp
.ne 2
.na
\fB\fBD\fR\fR
.ad
.RS 5n
The event specifier is automatically deleted when the hit count is equal to the
hit limit.
.RE

.sp
.ne 2
.na
\fB\fBs\fR\fR
.ad
.RS 5n
The target automatically stops when the hit count is equal to the hit limit.
.RE

.RE

.sp
.ne 2
.na
\fB\fBHT\fR\fR
.ad
.RS 15n
The current hit count. This column displays the number of times the
corresponding software event has occurred in the target since the creation of
this event specifier.
.RE

.sp
.ne 2
.na
\fB\fBLM\fR\fR
.ad
.RS 15n
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 \fB::evset\fR dcmd, described below.
.RE

.sp
.ne 2
.na
\fB\fBDescription\fR\fR
.ad
.RS 15n
A description of the type of software event that is matched by the given
specifier.
.RE

.sp
.ne 2
.na
\fB\fBAction\fR\fR
.ad
.RS 15n
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.
.RE

.RE

.sp
.ne 2
.na
\fB[\fIid\fR] \fB::evset\fR [\fB-/\fR\fB-dDestT\fR] [\fB-c\fR \fIcmd\fR]
[\fB-n\fR \fIcount\fR] \fIid\fR ...\fR
.ad
.sp .6
.RS 4n
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 \fB::evset\fR dcmd recognizes the following options:
.sp
.ne 2
.na
\fB\fB-d\fR\fR
.ad
.RS 6n
Disables the event specifier when the hit count reaches the hit limit. If the
\fB-d\fR form of the option is given, this behavior is disabled. Once an event
specifier is disabled, the debugger removes any corresponding instrumentation
and ignores the corresponding software events until the specifier is
subsequently re-enabled. If the \fB-n\fR option is not present, the specifier
is disabled immediately.
.RE

.sp
.ne 2
.na
\fB\fB-D\fR\fR
.ad
.RS 6n
Deletes the event specifier when the hit count reaches the hit limit. If the
\fB-D\fR form of the option is given, this behavior is disabled. The \fB-D\fR
option takes precedence over the \fB-d\fR option. The hit limit can be
configured using the \fB-n\fR option.
.RE

.sp
.ne 2
.na
\fB\fB-e\fR\fR
.ad
.RS 6n
Enables the event specifier. If the \fB-e\fR form of the option is given, the
specifier is disabled.
.RE

.sp
.ne 2
.na
\fB\fB-s\fR\fR
.ad
.RS 6n
Stops the target program when the hit count reaches the hit limit. If the
\fB-s\fR form of the option is given, this behavior is disabled. The \fB-s\fR
behavior tells the debugger to act as if the \fB::cont\fR were issued following
each execution of the specifier's callback, except for the \fIN\fRth execution,
where \fIN\fR is the current value of the specifier's hit limit. The \fB-s\fR
option takes precedence over both the \fB-D\fR option and the \fB-d\fR option.
.RE

.sp
.ne 2
.na
\fB\fB-t\fR\fR
.ad
.RS 6n
Marks the event specifier as temporary. Temporary specifiers are automatically
deleted the next time the target stops, regardless of whether it stopped as the
result of a software event corresponding to the given specifier. If the
\fB-t\fR form of the option is given, the temporary marker is removed. The
\fB-t\fR option takes precedence over the \fB-T\fR option.
.RE

.sp
.ne 2
.na
\fB\fB-T\fR\fR
.ad
.RS 6n
Marks the event specifier as sticky. Sticky specifiers are not deleted by
\fB::delete\fR \fBall\fR or \fB:z.\fR They can be deleted by specifying the
corresponding specifier \fBID\fR as an explicit argument to \fB::delete\fR. If
the \fB-T\fR form of the option is given, the sticky property is removed. The
default set of event specifiers are all initially marked sticky.
.RE

.sp
.ne 2
.na
\fB\fB-c\fR\fR
.ad
.RS 6n
Executes the specified \fIcmd\fR string each time the corresponding software
event occurs in the target program. The current callback string can be
displayed using \fB::events\fR.
.RE

.sp
.ne 2
.na
\fB\fB-n\fR\fR
.ad
.RS 6n
Sets the current value of the hit limit to \fIcount\fR. If no hit limit is
currently set and the \fB-n\fR option does not accompany \fB-s\fR or D, the hit
limit is set to one.
.RE

A summary of this information is available using \fB::help\fR \fBevset\fR.
.RE

.sp
.ne 2
.na
\fB\fB::files\fR\fR
.ad
.br
.na
\fB\fB$f\fR\fR
.ad
.sp .6
.RS 4n
Print a list of the known source files (symbols of type \fISTT_FILE\fR present
in the various target symbol tables).
.RE

.sp
.ne 2
.na
\fB[\fIflt\fR] \fB::fltbp\fR [\fB-/\fR\fB-dDestT\fR] [\fB-c\fR \fIcmd\fR]
[\fB-n\fR \fIcount\fR] \fIflt\fR ...\fR
.ad
.sp .6
.RS 4n
Trace the specified machine faults. The faults are identified using an optional
fault number preceding the dcmd, or a list of fault names or numbers (see
\fB<sys/fault.h>\fR) following the dcmd. The \fB-d\fR, \fB-D\fR, \fB-e\fR,
\fB-s\fR, \fB-t\fR, \fB-T\fR, \fB-c\fR, and \fB-n\fR options have the same
meaning as they do for the \fB::evset\fR dcmd.
.RE

.sp
.ne 2
.na
\fB[ \fB\fIthread\fR\fR ] \fB::fpregs\fR\fR
.ad
.br
.na
\fB[ \fB\fIthread\fR\fR ] \fB$x\fR, \fB$X\fR, \fB$y\fR, \fB$Y\fR\fR
.ad
.sp .6
.RS 4n
Print the floating-point register set of the representative thread. If a thread
is specified, the floating point registers of that thread are displayed. The
thread expression should be one of the thread identifiers described under
\fBThread Support\fR, above.
.RE

.sp
.ne 2
.na
\fB\fB::formats\fR\fR
.ad
.sp .6
.RS 4n
List the available output format characters for use with the \fB/\fR, \fB\e\fR,
\fB?\fR, and \fB=\fR formatting dcmds. The formats and their use is described
under \fBFormatting dcmds\fR, above.
.RE

.sp
.ne 2
.na
\fB\fB::grep\fR \fIcommand\fR\fR
.ad
.sp .6
.RS 4n
Evaluate the specified command string, and then print the old value of dot if
the new value of dot is non-zero. If the \fIcommand\fR contains whitespace or
metacharacters, it must be quoted. The \fB::grep\fR dcmd can be used in
pipelines to filter a list of addresses.
.RE

.sp
.ne 2
.na
\fB\fB::help\fR [ \fIdcmd-name\fR ]\fR
.ad
.sp .6
.RS 4n
With no arguments, the \fB::help\fR dcmd prints a brief overview of the help
facilities available in \fBmdb\fR. If a \fIdcmd-name\fR is specified, \fBmdb\fR
prints a usage summary for that dcmd.
.RE

.sp
.ne 2
.na
\fB\fIsignal\fR \fB:i\fR\fR
.ad
.sp .6
.RS 4n
If the target is a live user process, ignore the specified signal and allow it
to be delivered transparently to the target. All event specifiers that are
tracing delivery of the specified signal is deleted from the list of traced
events. By default, the set of ignored signals is initialized to the complement
of the set of signals that cause a process to dump core by default (see
\fBsignal.h\fR(3HEAD)), except for \fBSIGINT\fR, which is traced by default.
.RE

.sp
.ne 2
.na
\fB\fB$i\fR\fR
.ad
.sp .6
.RS 4n
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 \fB::events\fR dcmd.
.RE

.sp
.ne 2
.na
\fB\fB::kill\fR\fR
.ad
.br
.na
\fB\fB:k\fR\fR
.ad
.sp .6
.RS 4n
Forcibly terminate the target if it is a live user process. The target is also
forcibly terminated when the debugger exits if it was created by the debugger
using \fB::run\fR.
.RE

.sp
.ne 2
.na
\fB\fB$l\fR\fR
.ad
.sp .6
.RS 4n
Print the \fBLWPID\fR of the representative thread, if the target is a user
process.
.RE

.sp
.ne 2
.na
\fB\fB$L\fR\fR
.ad
.sp .6
.RS 4n
Print the \fBLWPID\fRs of each \fBLWP\fR in the target, if the target is a user
process.
.RE

.sp
.ne 2
.na
\fB[ \fIaddress\fR ] \fB::list\fR \fItype\fR \fImember\fR [ \fIvariable-name\fR
]\fR
.ad
.sp .6
.RS 4n
Walk through the elements of a linked list data structure and print the address
of each element in the list. The address of the first element in the list can
be specified using an optional address. Otherwise, the list is assumed to start
at the current value of dot. The type parameter must name a C struct or union
type and is used to describe the type of the list elements so that \fBmdb\fR
can read in objects of the appropriate size. The member parameter is used to
name the \fImember\fR of \fItype\fR that contains a pointer to the next list
element. The \fB::list\fR dcmd continues iterating until a \fBNULL\fR pointer
is encountered, the first element is reached again (a circular list), or an
error occurs while reading an element. If the optional \fIvariable-name\fR is
specified, the specified variable is assigned the value returned at each step
of the walk when \fBmdb\fR invokes the next stage of a pipeline. The
\fB::list\fR dcmd can only be used with objects that contain symbolic debugging
information designed for use with mdb. Refer to NOTES, \fBSymbolic Debugging
Information\fR, below for more information.
.RE

.sp
.ne 2
.na
\fB\fB::load\fR [ \fB-s\fR ] \fImodule-name\fR\fR
.ad
.sp .6
.RS 4n
Load the specified dmod. The module name can be given as an absolute or
relative path. If \fImodule-name\fR is a simple name (that is, does not contain
a '\fB/\fR'), \fBmdb\fR 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 \fB-s\fR option is present, \fBmdb\fR remains silent and not
issue any error messages if the module is not found or could not be loaded.
.RE

.sp
.ne 2
.na
\fB\fB::log\fR [ \fB-d\fR | [ \fB-e\fR ] \fIfilename\fR ]\fR
.ad
.br
.na
\fB\fB$>\fR [ \fIfilename\fR ]\fR
.ad
.sp .6
.RS 4n
Enable or disable the output log. \fBmdb\fR provides an interactive logging
facility where both the input commands and standard output can be logged to a
file while still interacting with the user. The \fB-e\fR option enables logging
to the specified file, or re-enables logging to the previous log file if no
filename is given. The \fB-d\fR option disables logging. If the \fB$>\fR dcmd
is used, logging is enabled if a filename argument is specified; otherwise,
logging is disabled. If the specified log file already exists, \fBmdb\fR
appends any new log output to the file.
.RE

.sp
.ne 2
.na
\fB\fB::map\fR \fIcommand\fR\fR
.ad
.sp .6
.RS 4n
Map the value of dot to a corresponding value using the \fIcommand\fR 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 \fB::map\fR dcmd
can be used in pipelines to transform the list of addresses into a new list of
addresses.
.RE

.sp
.ne 2
.na
\fB[ \fIaddress\fR ] \fB::mappings\fR [ \fIname\fR ]\fR
.ad
.br
.na
\fB[ \fI address\fR ] \fB$m\fR [ \fIname\fR ]\fR
.ad
.sp .6
.RS 4n
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 \fIaddress\fR, \fBmdb\fR only shows the mapping that contains the given
address. If a string \fIname\fR argument is given, \fBmdb\fR only shows the
mapping matching that description.
.RE

.sp
.ne 2
.na
\fB\fB::next\fR [ \fISIG\fR ]\fR
.ad
.br
.na
\fB\fB:e\fR [ \fISIG\fR ]\fR
.ad
.sp .6
.RS 4n
Step the target program one instruction, but step over subroutine calls. If an
optional signal name or number (see \fBsignal.h\fR(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, \fB::next\fR starts a
new program running as if by \fB::run\fR and stop at the first instruction.
.RE

.sp
.ne 2
.na
\fB[ \fIaddress\fR ] \fB::nm\fR [ \fB-DPdghnopuvx\fR ] [ \fB-t\fR \fItypes\fR
]\fR
.ad
.br
.na
\fB#sp;#sp;[ \fB-f\fR \fIformat\fR ] [ \fIobject\fR ]\fR
.ad
.sp .6
.RS 4n
Print the symbol tables associated with the current target. If an optional
address preceding the dcmd is specified, only the symbol table entry for the
symbol corresponding to \fIaddress\fR is displayed. If an \fIobject\fR is
specified, only the symbol table for this load object is displayed. The
\fB::nm\fR dcmd also recognizes the following options:
.sp
.ne 2
.na
\fB\fB-D\fR\fR
.ad
.RS 27n
Prints \fB\&.dynsym\fR (dynamic symbol table) instead of \fB\&.symtab\fR.
.RE

.sp
.ne 2
.na
\fB\fB-P\fR\fR
.ad
.RS 27n
Prints the private symbol table instead of \fB\&.symtab\fR.
.RE

.sp
.ne 2
.na
\fB\fB-d\fR\fR
.ad
.RS 27n
Prints value and size fields in decimal.
.RE

.sp
.ne 2
.na
\fB\fB-g\fR\fR
.ad
.RS 27n
Prints only global symbols.
.RE

.sp
.ne 2
.na
\fB\fB-h\fR\fR
.ad
.RS 27n
Suppresses the header line.
.RE

.sp
.ne 2
.na
\fB\fB-n\fR\fR
.ad
.RS 27n
Sorts symbols by name.
.RE

.sp
.ne 2
.na
\fB\fB-o\fR\fR
.ad
.RS 27n
Prints value and size fields in octal.
.RE

.sp
.ne 2
.na
\fB\fB-p\fR\fR
.ad
.RS 27n
Prints symbols as a series of \fB::nmadd\fR commands. This option can be used
with \fB-P\fR to produce a macro file that can be subsequently read into the
debugger with \fB$<\fR.
.RE

.sp
.ne 2
.na
\fB\fB-u\fR\fR
.ad
.RS 27n
Prints only undefined symbols.
.RE

.sp
.ne 2
.na
\fB\fB-v\fR\fR
.ad
.RS 27n
Sorts symbols by value.
.RE

.sp
.ne 2
.na
\fB\fB-x\fR\fR
.ad
.RS 27n
Prints value and size fields in hexadecimal.
.RE

.sp
.ne 2
.na
\fB\fB-t\fR \fItype\fR[,\fItype\fR ... ]\fR
.ad
.RS 27n
Prints only symbols of the specified type(s). The valid \fItype\fR argument
strings are:
.sp
.ne 2
.na
\fB\fBnoty\fR\fR
.ad
.RS 8n
\fISTT_NOTYPE\fR
.RE

.sp
.ne 2
.na
\fB\fBobjt\fR\fR
.ad
.RS 8n
\fISTT_OBJECT\fR
.RE

.sp
.ne 2
.na
\fB\fBfunc\fR\fR
.ad
.RS 8n
\fISTT_FUNC\fR
.RE

.sp
.ne 2
.na
\fB\fBsect\fR\fR
.ad
.RS 8n
\fISTT_SECTION\fR
.RE

.sp
.ne 2
.na
\fB\fBfile\fR\fR
.ad
.RS 8n
\fISTT_FILE\fR
.RE

.sp
.ne 2
.na
\fB\fBcomm\fR\fR
.ad
.RS 8n
\fISTT_COMMON\fR
.RE

.sp
.ne 2
.na
\fB\fBtls\fR\fR
.ad
.RS 8n
\fISTT_TLS\fR
.RE

.sp
.ne 2
.na
\fB\fBregi\fR\fR
.ad
.RS 8n
\fISTT_SPARC_REGISTER\fR
.RE

.RE

.sp
.ne 2
.na
\fB\fB-f\fR \fIformat\fR[,\fIformat\fR ... ]\fR
.ad
.RS 27n
Prints only the specified symbol information. The valid \fIformat\fR argument
strings are:
.sp
.ne 2
.na
\fB\fBndx\fR\fR
.ad
.RS 9n
symbol table index
.RE

.sp
.ne 2
.na
\fB\fBval\fR\fR
.ad
.RS 9n
symbol value
.RE

.sp
.ne 2
.na
\fB\fBsize\fR\fR
.ad
.RS 9n
size in bytes
.RE

.sp
.ne 2
.na
\fB\fBtype\fR\fR
.ad
.RS 9n
symbol type
.RE

.sp
.ne 2
.na
\fB\fBbind\fR\fR
.ad
.RS 9n
binding
.RE

.sp
.ne 2
.na
\fB\fBoth\fR\fR
.ad
.RS 9n
other
.RE

.sp
.ne 2
.na
\fB\fBshndx\fR\fR
.ad
.RS 9n
section index
.RE

.sp
.ne 2
.na
\fB\fBname\fR\fR
.ad
.RS 9n
symbol name
.RE

.sp
.ne 2
.na
\fB\fBctype\fR\fR
.ad
.RS 9n
C type for symbol (if known)
.RE

.sp
.ne 2
.na
\fB\fBobj\fR\fR
.ad
.RS 9n
object which defines symbol
.RE

.RE

.RE

.sp
.ne 2
.na
\fB\fIvalue\fR \fB::nmadd\fR [ \fB-fo\fR ] [ \fB-e\fR \fIend\fR ] [ \fB-s\fR
\fIsize\fR ] \fIname \fR\fR
.ad
.sp .6
.RS 4n
Add the specified symbol \fIname\fR to the private symbol table. \fBmdb\fR
provides a private, configurable symbol table that can be used to interpose on
the target's symbol table, as described under \fBSymbol Name Resolution\fR
above. The \fB::nmadd\fR dcmd also recognizes the following options:
.sp
.ne 2
.na
\fB\fB-e\fR\fR
.ad
.RS 6n
Sets the size of the symbol to \fIend\fR - \fIvalue\fR.
.RE

.sp
.ne 2
.na
\fB\fB-f\fR\fR
.ad
.RS 6n
Sets the type of the symbol to \fBSTT_FUNC\fR.
.RE

.sp
.ne 2
.na
\fB\fB-o\fR\fR
.ad
.RS 6n
Sets the type of the symbol to \fBSTT_OBJECT\fR.
.RE

.sp
.ne 2
.na
\fB\fB-s\fR\fR
.ad
.RS 6n
Sets the size of the symbol to \fIsize\fR.
.RE

.RE

.sp
.ne 2
.na
\fB\fB::nmdel\fR \fIname\fR\fR
.ad
.sp .6
.RS 4n
Delete the specified symbol \fIname\fR from the private symbol table.
.RE

.sp
.ne 2
.na
\fB\fB::objects\fR [ \fB-v\fR ]\fR
.ad
.sp .6
.RS 4n
Print a map of the target's virtual address space, showing only those mappings
that correspond to the primary mapping (usually the text section) of each of
the known load objects. The \fB-v\fR option displays the version of each load
object. Version information is not available for all load objects. Load objects
without version information is listed as having a version of "\fBUnknown\fR" in
the output for the \fB-v\fR option.
.RE

.sp
.ne 2
.na
\fB\fB::offsetof\fR \fItype member\fR\fR
.ad
.sp .6
.RS 4n
Print the offset of the specified \fImember\fR of the specified \fItype\fR. The
\fItype\fR 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 (\fB`\fR) scoping operator described under
\fBSymbol Name Resolution\fR, above. The \fB::offsetof\fR dcmd can only be used
with objects that contain symbolic debugging information designed for use with
\fBmdb\fR. Refer to NOTES, \fBSymbolic Debugging Information\fR, below for more
information.
.RE

.sp
.ne 2
.na
\fB\fIaddress\fR \fB::print\fR [ \fB-aCdiLptx\fR ] [ \fB-c\fR \fIlim\fR ]\fR
.ad
.br
.na
\fB#sp;#sp;[ \fB-l\fR \fIlim\fR ] [ \fItype\fR [ \fImember\fR ... ] ]\fR
.ad
.sp .6
.RS 4n
Print the data structure at the specified virtual \fIaddress\fR using the given
\fItype\fR information. The \fItype\fR 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, "\fBstruct foo\fR"), it must be enclosed
in single or double quotes. The type name can use the backquote (\fB`\fR)
scoping operator described under \fBSymbol Name Resolution\fR, above. If the
type is a structured type, the \fB::print\fR dcmd recursively prints each
member of the struct or union. If the \fItype\fR argument is not present and a
static or global \fISTT_OBJECT\fR symbol matches the address, \fB::print\fR
infers the appropriate type automatically. If the \fItype\fR argument is
specified, it can be followed by an optional list of \fImember\fR expressions,
in which case only those members and submembers of the specified \fItype\fR are
displayed. If \fItype\fR contains other structured types, each member string
can refer to a sub-structure element by forming a list of member names
separated by period ('\fB\&.\fR') delimiters. The \fB::print\fR dcmd can only
be used with objects that contain symbolic debugging information designed for
use with \fBmdb\fR. Refer to NOTES, \fBSymbolic Debugging Information\fR, below
for more information. After displaying the data structure, \fB::print\fR
increments dot by the size of \fItype\fR in bytes.
.sp
If the \fB-a\fR option is present, the address of each member is displayed. If
the \fB-p\fR option is present, \fB::print\fR interprets \fIaddress\fR as a
physical memory address instead of a virtual memory address. If the \fB-t\fR
option is present, the type of each member is displayed. If the \fB-d\fR or
\fB-x\fR options are present, all integers are displayed in decimal (\fB-d\fR)
or hexadecimal (\fB-x\fR). By default, a heuristic is used to determine if the
value should be displayed in decimal or hexadecimal. The number of characters
in a character array that is read and displayed as a string can be limited with
the \fB-c\fR option. If the \fB-C\fR 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 \fB-l\fR option. If the \fB-L\fR option is present, no limit
is enforced and all array elements are shown. The default values for \fB-c\fR
and \fB-l\fR can be modified using \fB::set\fR or the \fB-o\fR command-line
option as described under OPTIONS.
.sp
If the \fB-i\fR 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 \fB-i\fR option cannot be used in
conjunction with the \fB-p\fR option. If the \fB-a\fR option is given, the
addresses shown are byte offsets starting at zero.
.RE

.sp
.ne 2
.na
\fB\fB::quit\fR\fR
.ad
.br
.na
\fB\fB$q\fR\fR
.ad
.sp .6
.RS 4n
Quit the debugger.
.RE

.sp
.ne 2
.na
\fB[ \fIthread\fR ] \fB::regs\fR\fR
.ad
.br
.na
\fB[ \fIthread\fR ] \fB$r\fR\fR
.ad
.sp .6
.RS 4n
Print the general purpose register set of the representative thread. If a
thread is specified, the general purpose register set of that thread is
displayed. The thread expression should be one of the thread identifiers
described under \fBThread Support\fR, above.
.RE

.sp
.ne 2
.na
\fB\fB::release\fR [ \fB-a\fR ]\fR
.ad
.br
.na
\fB\fB:R\fR [ \fB-a\fR ]\fR
.ad
.sp .6
.RS 4n
Release the previously attached process or core file. If the \fB-a\fR option is
present, the process is released and left stopped and abandoned. It can
subsequently be continued by \fBprun\fR(1) (see \fBproc\fR(1)) or it can be
resumed by applying \fBmdb\fR or another debugger. By default, a released
process is forcibly terminated if it was created by \fBmdb\fR using
\fB::run\fR, or it is released and set running if it was attached to by
\fBmdb\fR using the \fB-p\fR option or using the \fB::attach\fR or \fB:A\fR
dcmds.
.RE

.sp
.ne 2
.na
\fB\fB::run\fR [ \fIargs\fR . . . ]\fR
.ad
.br
.na
\fB\fB:r\fR [ \fIargs\fR . . . ]\fR
.ad
.sp .6
.RS 4n
Start a new target program running with the specified arguments and attach to
it. The arguments are not interpreted by the shell. If the debugger is already
examining a live running program, it first detaches from this program as if by
\fB::release\fR.
.RE

.sp
.ne 2
.na
\fB\fB::set\fR [ \fB-wF\fR ] [ \fB-/\fR\fB-o\fR \fIoption\fR ] [ \fB-s\fR
\fIdistance\fR ] [ \fB-I\fR \fIpath\fR ]\fR
.ad
.br
.na
\fB#sp;#sp;[ \fB-L\fR \fIpath\fR ] [ \fB-P\fR \fIprompt\fR ]\fR
.ad
.sp .6
.RS 4n
Get or set miscellaneous debugger properties. If no options are specified, the
current set of debugger properties is displayed. The \fB::set\fR dcmd
recognizes the following options:
.sp
.ne 2
.na
\fB\fB-F\fR\fR
.ad
.RS 6n
Forcibly takes over the next user process that \fB::attach\fR is applied to, as
if \fBmdb\fR had been executed with the \fB-F\fR option on the command line.
.RE

.sp
.ne 2
.na
\fB\fB-I\fR\fR
.ad
.RS 6n
Sets the default path for locating macro files. The path argument can contain
any of the special tokens described for the \fB-I\fR command-line option under
OPTIONS.
.RE

.sp
.ne 2
.na
\fB\fB-L\fR\fR
.ad
.RS 6n
Sets the default path for locating debugger modules. The path argument can
contain any of the special tokens described for the \fB-I\fR command-line
option under OPTIONS.
.RE

.sp
.ne 2
.na
\fB\fB-o\fR\fR
.ad
.RS 6n
Enables the specified debugger option. If the \fB-o\fR form is used, the option
is disabled. The option strings are described along with the \fB-o\fR
command-line option under OPTIONS.
.RE

.sp
.ne 2
.na
\fB\fB-P\fR\fR
.ad
.RS 6n
Sets the command prompt to the specified prompt string.
.RE

.sp
.ne 2
.na
\fB\fB-s\fR\fR
.ad
.RS 6n
Sets the symbol matching distance to the specified distance. Refer to the
description of the \fB-s\fR command-line option under OPTIONS for more
information.
.RE

.sp
.ne 2
.na
\fB\fB-w\fR\fR
.ad
.RS 6n
Re-opens the target for writing, as if \fBmdb\fR had been executed with the
\fB-w\fR option on the command line.
.RE

.RE

.sp
.ne 2
.na
\fB\fB::showrev\fR [ \fB-pv\fR ]\fR
.ad
.sp .6
.RS 4n
Display revision information for the hardware and software. With no options
specified, general system information is displayed. The \fB-v\fR option
displays version information for all load objects, whereas the \fB-p\fR 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 \fB-p\fR option and is listed as having a
version of "\fBUnknown\fR" in the output for the \fB-v\fR option.
.RE

.sp
.ne 2
.na
\fB[\fIsignal\fR] \fB::sigbp\fR [\fB-/\fR\fB-dDestT\fR] [\fB-c\fR \fIcmd\fR]
[\fB-n\fR \fIcount\fR] \fISIG\fR ...\fR
.ad
.br
.na
\fB[\fIsignal\fR] \fB:t\fR [\fB-/\fR\fB-dDestT\fR] [\fB-c\fR \fIcmd\fR]
[\fB-n\fR \fIcount\fR] \fISIG\fR ...\fR
.ad
.sp .6
.RS 4n
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 \fBsignal.h\fR(3HEAD)) following the dcmd. The \fB-d\fR, \fB-D\fR,
\fB-e\fR, \fB-s\fR, \fB-t\fR, \fB-T\fR, \fB-c\fR, and \fB-n\fR options have the
same meaning as they do for the \fB::evset\fR dcmd. Initially, the set of
signals that cause the process to dump core by default (see
\fBsignal.h\fR(3HEAD)) and \fBSIGINT\fR are traced.
.RE

.sp
.ne 2
.na
\fB\fB::sizeof\fR \fItype\fR \fR
.ad
.sp .6
.RS 4n
Print the size of the specified \fItype\fR in bytes. The \fItype\fR 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 (\fB`\fR) scoping operator
described under \fBSymbol Name Resolution\fR, above. The \fB::sizeof\fR dcmd
can only be used with objects that contain symbolic debugging information
designed for use with \fBmdb\fR. Refer to NOTES, \fBSymbolic Debugging
Information\fR, below for more information.
.RE

.sp
.ne 2
.na
\fB[ \fIaddress\fR ] \fB::stack \fR [ \fIcount\fR ]\fR
.ad
.br
.na
\fB[ \fI address\fR ] \fB$c\fR [ \fIcount\fR ]\fR
.ad
.sp .6
.RS 4n
Print a C stack backtrace. If the dcmd is preceded by an explicit
\fIaddress\fR, 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 \fIcount\fR
arguments are displayed for each stack frame in the output.
.RE

.sp
.ne 2
.na
\fB\fB::status\fR\fR
.ad
.sp .6
.RS 4n
Print a summary of information related to the current target.
.RE

.sp
.ne 2
.na
\fB\fB::step\fR [ \fBover\fR | \fBout\fR ] [ \fISIG\fR ]\fR
.ad
.br
.na
\fB\fB:s\fR [ \fISIG\fR ]\fR
.ad
.br
.na
\fB\fB:u\fR [ \fISIG\fR ]\fR
.ad
.sp .6
.RS 4n
Step the target program one instruction. If an optional signal name or number
(see \fBsignal.h\fR(3HEAD)) is specified as an argument, the signal is
immediately delivered to the target as part of resuming its execution. If the
optional "\fBover\fR" argument is specified, \fB::step\fR steps over subroutine
calls. The \fB::step\fR \fBover\fR argument is the same as the \fB::next\fR
dcmd. If the optional "\fBout\fR" argument is specified, the target program
continues until the representative thread returns from the current function. If
no target program is currently running, \fB::step\fR \fBout\fR starts a new
program running as if by \fB::run\fR and stop at the first instruction. The
\fB:s\fR dcmd is the same as \fB::step\fR. The \fB:u\fR dcmd is the same as
\fB::step\fR \fBout\fR.
.RE

.sp
.ne 2
.na
\fB[ \fIsyscall\fR ] \fB::sysbp\fR [ \fB-/\fR\fB-dDestT\fR ] [ \fB-io\fR ] [
\fB-c\fR \fIcmd\fR ]\fR
.ad
.br
.na
\fB#sp;#sp;[ \fB-n\fR \fIcount\fR ] \fIsyscall\fR...\fR
.ad
.sp .6
.RS 4n
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 \fB<sys/syscall.h>\fR) following the dcmd.
If the \fB-i\fR option is specified (the default), the event specifiers trigger
on entry into the kernel for each system call. If the \fB-o\fR option is
specified, the event specifiers trigger on exit out from the kernel. The
\fB-d\fR, \fB-D\fR, \fB-e\fR, \fB-s\fR, \fB-t\fR, \fB-T\fR, \fB-c\fR, and
\fB-n\fR options have the same meaning as they do for the \fB::evset\fR dcmd.
.RE

.sp
.ne 2
.na
\fB\fIthread\fR \fB::tls\fR \fIsymbol\fR\fR
.ad
.sp .6
.RS 4n
Print the address of the storage for the specified thread-local storage
(\fBTLS\fR) symbol in the context of the specified thread. The thread
expression should be one of the thread identifiers described under \fBThread
Support\fR, above. The symbol name can use any of the scoping operators
described under \fBSymbol Name Resolution\fR, above.
.RE

.sp
.ne 2
.na
\fB\fB::typeset\fR [ \fB-/\fR\fB-t\fR] \fIvariable-name\fR . . .\fR
.ad
.sp .6
.RS 4n
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 \fB-t\fR option
is present, the user-defined tag associated with each variable is set. If the
\fB-t\fR option is present, the tag is cleared. If no variable names are
specified, the list of variables and their values is printed.
.RE

.sp
.ne 2
.na
\fB\fB::unload\fR \fImodule-name\fR\fR
.ad
.sp .6
.RS 4n
Unload the specified dmod. The list of active dmods can be printed using the
\fB::dmods\fR dcmd. Built-in modules can not be unloaded. Modules that are busy
(that is, provide dcmds that are currently executing) can not be unloaded.
.RE

.sp
.ne 2
.na
\fB\fB::unset\fR \fIvariable-name\fR . . .\fR
.ad
.sp .6
.RS 4n
Unset (remove) the specified variable(s) from the list of defined variables.
Some variables exported by \fBmdb\fR are marked as persistent, and can not be
unset by the user.
.RE

.sp
.ne 2
.na
\fB\fB::vars\fR [ \fB-npt\fR] \fR
.ad
.sp .6
.RS 4n
Print a listing of named variables. If the \fB-n\fR option is present, the
output is restricted to variables that currently have non-zero values. If the
\fB-p\fR option is present, the variables are printed in a form suitable for
re-processing by the debugger using the \fB$<\fR dcmd. This option can be used
to record the variables to a macro file and then restore these values later. If
the \fB-t\fR option is present, only the tagged variables are printed.
Variables can be tagged using the \fB-t\fR option of the \fB::typeset\fR dcmd.
.RE

.sp
.ne 2
.na
\fB\fB::version\fR\fR
.ad
.sp .6
.RS 4n
Print the debugger version number.
.RE

.sp
.ne 2
.na
\fB\fIaddress\fR \fB::vtop\fR [\fB-a\fR \fIas\fR]\fR
.ad
.sp .6
.RS 4n
Print the physical address mapping for the specified virtual address, if
possible. The \fB::vtop\fR dcmd is only available when examining a kernel
target, or when examining a user process inside a kernel crash dump (after a
\fB::context\fR dcmd has been issued).
.sp
When examining a kernel target from the kernel context, the \fB-a\fR option can
be used to specify the address (\fIas\fR) 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.
.RE

.sp
.ne 2
.na
\fB[ \fIaddress\fR ] \fB::walk\fR \fIwalker-name\fR [ \fIvariable-name\fR ]\fR
.ad
.sp .6
.RS 4n
Walk through the elements of a data structure using the specified walker. The
available walkers can be listed using the \fB::walkers\fR dcmd. Some walkers
operate on a global data structure and do not require a starting address. For
example, walk the list of proc structures in the kernel. Other walkers operate
on a specific data structure whose address must be specified explicitly. For
example, given a pointer to an address space, walk the list of segments. When
used interactively, the \fB::walk\fR 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
(\fB`\fR) scoping operator described under \fBdcmd and Walker Name
Resolution\fR, above. If the optional \fIvariable-name\fR is specified, the
specified variable is assigned the value returned at each step of the walk when
\fBmdb\fR invokes the next stage of the pipeline.
.RE

.sp
.ne 2
.na
\fB\fB::walkers\fR\fR
.ad
.sp .6
.RS 4n
List the available walkers and print a brief description for each one.
.RE

.sp
.ne 2
.na
\fB\fB::whence\fR [ \fB-v\fR ] \fIname\fR . . .\fR
.ad
.br
.na
\fB\fB::which\fR [ \fB-v\fR ] \fIname\fR ...\fR
.ad
.sp .6
.RS 4n
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 \fBdcmd and Walker Name
Resolution\fR above for more information on global name resolution. The
\fB-v\fR option causes the dcmd to print the alternate definitions of each dcmd
and walker in order of precedence.
.RE

.sp
.ne 2
.na
\fB\fIaddr\fR [ ,\fIlen\fR ]\fB::wp\fR  [ \fB-/\fR\fB-dDestT\fR ] [ \fB-rwx\fR
] [ \fB-c\fR \fIcmd\fR ]\fR
.ad
.br
.na
\fB#sp;#sp; [ \fB-n\fR \fIcount\fR ]\fR
.ad
.br
.na
\fB\fIaddr\fR [ ,\fIlen\fR ] \fB:a\fR [ \fIcmd\fR . . . ]\fR
.ad
.br
.na
\fB\fIaddr\fR [ ,\fIlen\fR ] \fB:p\fR [ \fIcmd\fR . \&. . ]\fR
.ad
.br
.na
\fB\fIaddr\fR [ ,\fIlen\fR ] \fB:w\fR [ \fIcmd\fR . . . ]\fR
.ad
.sp .6
.RS 4n
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 \fB::wp\fR dcmd
allows the watchpoint to be configured to trigger on any combination of read
(\fB-r\fR option), write (\fB-w\fR option), or execute (\fB-x\fR option)
access. The \fB-d\fR, \fB-D\fR, \fB-e\fR, \fB-s\fR, \fB-t\fR, \fB-T\fR,
\fB-c\fR, and \fB-n\fR options have the same meaning as they do for the
\fB::evset\fR dcmd. The \fB:a\fR dcmd sets a read access watchpoint at the
specified address. The \fB:p\fR dcmd sets an execute access watchpoint at the
specified address. The \fB:w\fR dcmd sets a write access watchpoint at the
specified address. The arguments following the \fB:a\fR, \fB:p\fR, and \fB:w\fR
dcmds are concatenated together to form the callback string. If this string
contains meta-characters, it must be quoted.
.RE

.sp
.ne 2
.na
\fB\fB::xdata\fR\fR
.ad
.sp .6
.RS 4n
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 \fISolaris Modular Debugger Guide\fR.
.RE

.sp
.ne 2
.na
\fB\fB:z\fR\fR
.ad
.sp .6
.RS 4n
Delete all event specifiers from the list of traced software events. Event
specifiers can also be deleted using \fB::delete\fR.
.RE

.SH OPTIONS
.sp
.LP
The following options are supported:
.sp
.ne 2
.na
\fB\fB-A\fR\fR
.ad
.RS 15n
Disables automatic loading of \fBmdb\fR modules. By default, \fBmdb\fR 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.
.RE

.sp
.ne 2
.na
\fB\fB-e\fR \fIexpr\fR\fR
.ad
.RS 15n
Causes \fBmdb\fR to ignore standard input and instead evaluate the \fBmdb\fR
expression \fIexpr\fR. Upon completing evaluation, \fBmdb\fR terminates and
returns a status code. A non-zero return code from \fBmdb\fR indicates that
either \fBmdb\fR or the evaluation of \fIexpr\fR failed.
.RE

.sp
.ne 2
.na
\fB\fB-f\fR\fR
.ad
.RS 15n
Forces raw file debugging mode. By default, \fBmdb\fR attempts to infer whether
the object and core file operands refer to a user executable and core dump or
to a pair of operating system crash dump files. If the file type cannot be
inferred, the debugger defaults to examining the files as plain binary data.
The \fB-f\fR option forces \fBmdb\fR to interpret the arguments as a set of raw
files to examine.
.RE

.sp
.ne 2
.na
\fB\fB-F\fR\fR
.ad
.RS 15n
Forcibly takes over the specified user process, if necessary. By default,
\fBmdb\fR refuses to attach to a user process that is already under the control
of another debugging tool, such as \fBtruss\fR(1). With the \fB-F\fR option,
\fBmdb\fR attaches to these processes anyway. This can produce unexpected
interactions between \fBmdb\fR and the other tools attempting to control the
process.
.RE

.sp
.ne 2
.na
\fB\fB-I\fR \fIpath\fR\fR
.ad
.RS 15n
Sets default path for locating macro files. Macro files are read using the
\fB$<\fR or \fB$<<\fR dcmds. The path is a sequence of directory names
delimited by colon (\fB:\fR) characters. The \fB-I\fR \fBinclude\fR path and
\fB-L\fR \fBlibrary\fR path (see below) can also contain any of the following
tokens:
.sp
.ne 2
.na
\fB%i\fR
.ad
.RS 6n
Expands to the current instruction set architecture (\fBISA\fR) name
('sparc', 'sparcv9', or 'i386').
.RE

.sp
.ne 2
.na
\fB%o\fR
.ad
.RS 6n
Expands to the old value of the path being modified. This is useful for
appending or prepending directories to an existing path.
.RE

.sp
.ne 2
.na
\fB%p\fR
.ad
.RS 6n
Expands to the current platform string (either \fBuname\fR \fB-i\fR or the
platform string stored in the process core file or crash dump).
.RE

.sp
.ne 2
.na
\fB%r\fR
.ad
.RS 6n
Expands to the pathname of the root directory. An alternate root directory can
be specified using the \fB-R\fR option. If no \fB-R\fR option is present, the
root directory is derived dynamically from the path to the \fBmdb\fR executable
itself. For example, if \fB/bin/mdb\fR is executed, the root directory is
\fB/\fR. If \fB/net/hostname/bin/mdb\fR were executed, the root directory would
be derived as \fB/net/hostname\fR.
.RE

.sp
.ne 2
.na
\fB%t\fR
.ad
.RS 6n
Expands to the name of the current target. This is either be the literal
string '\fBproc\fR' (a user process or user process core file), '\fBkvm\fR' (a kernel
crash dump or the live operating system), or '\fBraw\fR' (a raw file).
.RE

The default include path for 32-bit \fBmdb\fR is:
.sp
.in +2
.nf
%r/usr/platform/%p/lib/adb:%r/usr/lib/adb
.fi
.in -2
.sp

The default include path for 64-bit \fBmdb\fR is:
.sp
.in +2
.nf
%r/usr/platform/%p/lib/adb/%i:%r/usr/lib/adb/%i
.fi
.in -2
.sp

.RE

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

.sp
.ne 2
.na
\fB\fB-K\fR\fR
.ad
.RS 15n
Load \fBkmdb\fR, stop the live running operating system kernel, and proceed to
the \fBkmdb\fR debugger prompt. This option should only be used on the system
console, as the subsequent \fBkmdb\fR prompt appears on the system console.
.RE

.sp
.ne 2
.na
\fB\fB-L\fR \fIpath\fR\fR
.ad
.RS 15n
Sets default path for locating debugger modules. Modules are loaded
automatically on startup or using the \fB::load\fR dcmd. The path is a sequence
of directory names delimited by colon (\fB:\fR) characters. The \fB-L\fR
library path can also contain any of the tokens shown for \fB-I\fR above.
.RE

.sp
.ne 2
.na
\fB\fB-m\fR\fR
.ad
.RS 15n
Disables demand-loading of kernel module symbols. By default, \fBmdb\fR
processes the list of loaded kernel modules and performs demand loading of
per-module symbol tables. If the \fB-m\fR option is specified, \fBmdb\fR does
not attempt to process the kernel module list or provide per-module symbol
tables. As a result, \fBmdb\fR modules corresponding to active kernel modules
are not loaded on startup.
.RE

.sp
.ne 2
.na
\fB\fB-M\fR\fR
.ad
.RS 15n
Preloads all kernel module symbols. By default, \fBmdb\fR 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 \fB-M\fR option, \fBmdb\fR loads the complete symbol table
of all kernel modules during startup.
.RE

.sp
.ne 2
.na
\fB\fB-o\fR \fIoption\fR\fR
.ad
.RS 15n
Enables the specified debugger option. If the \fB-o\fR form of the option is
used, the specified \fIoption\fR is disabled. Unless noted below, each option
is off by default. \fBmdb\fR recognizes the following \fIoption\fR arguments:
.sp
.ne 2
.na
\fB\fBadb\fR\fR
.ad
.RS 25n
Enables stricter \fBadb\fR(1) compatibility. The prompt is set to the empty
string and many \fBmdb\fR features, such as the output pager, is disabled.
.RE

.sp
.ne 2
.na
\fB\fBarray_mem_limit=\fR\fIlimit\fR\fR
.ad
.RS 25n
Sets the default limit on the number of array members that \fB::print\fR
displays. If \fIlimit\fR is the special token \fBnone\fR, all array members are
displayed by default.
.RE

.sp
.ne 2
.na
\fB\fBarray_str_limit=\fR\fIlimit\fR\fR
.ad
.RS 25n
Sets the default limit on the number of characters that \fB::print\fR attempts
to display as an ASCII string when printing a char array. If \fIlimit\fR is the
special token \fBnone\fR, the entire char array is displayed as a string by
default.
.RE

.sp
.ne 2
.na
\fB\fBfollow_exec_mode=\fR\fImode\fR\fR
.ad
.RS 25n
Sets the debugger behavior for following an \fBexec\fR(2) system call. The
\fImode\fR should be one of the following named constants:
.sp
.ne 2
.na
\fB\fBask\fR\fR
.ad
.RS 10n
If stdout is a terminal device, the debugger stops after the \fBexec\fR(2)
system call has returned and then prompts the user to decide whether to follow
the exec or stop. If stdout is not a terminal device, the \fBask\fR mode
defaults to \fBstop\fR.
.RE

.sp
.ne 2
.na
\fB\fBfollow\fR\fR
.ad
.RS 10n
The debugger follows the exec by automatically continuing the target process
and resetting all of its mappings and symbol tables based on the new
executable. The \fBfollow\fR behavior is discussed in more detail under NOTES,
\fBInteraction with Exec\fR, below.
.RE

.sp
.ne 2
.na
\fB\fBstop\fR\fR
.ad
.RS 10n
The debugger stops following return from the exec system call. The \fBstop\fR
behavior is discussed in more detail under NOTES, \fBInteraction with Exec\fR,
below.
.RE

.RE

.sp
.ne 2
.na
\fB\fBfollow_fork_mode=\fR\fImode\fR\fR
.ad
.RS 25n
Sets the debugger behavior for following a \fBfork\fR(2), \fBfork1\fR(2), or
\fBvfork\fR(2) system call. The \fImode\fR should be one of the following named
constants:
.sp
.ne 2
.na
\fB\fBask\fR\fR
.ad
.RS 10n
If stdout is a terminal device, the debugger stops after the \fBfork\fR(2)
system call has returned and then prompts the user to decide whether to follow
the parent or child. If stdout is not a terminal device, the \fBask\fR mode
defaults to \fBparent\fR.
.RE

.sp
.ne 2
.na
\fB\fBparent\fR\fR
.ad
.RS 10n
The debugger follows the parent process, and detaches from the child process
and sets it running.
.RE

.sp
.ne 2
.na
\fB\fBchild\fR\fR
.ad
.RS 10n
The debugger follows the child process, and detaches from the parent process
and sets it running.
.RE

.RE

.sp
.ne 2
.na
\fB\fBignoreeof\fR\fR
.ad
.RS 25n
The debugger does not exit when an \fBEOF\fR sequence (\fB^D\fR) is entered at
the terminal. The \fB::quit\fR dcmd must be used to quit.
.RE

.sp
.ne 2
.na
\fB\fBnostop\fR\fR
.ad
.RS 25n
Does not stop a user process when attaching to it when the \fB-p\fR option is
specified or when the \fB::attach\fR or \fB:A\fR dcmds are applied. The
\fBnostop\fR behavior is described in more detail under NOTES, \fBProcess
Attach and Release\fR, below.
.RE

.sp
.ne 2
.na
\fB\fBpager\fR\fR
.ad
.RS 25n
Enables the output pager (default).
.RE

.sp
.ne 2
.na
\fB\fBrepeatlast\fR\fR
.ad
.RS 25n
If a \fINEWLINE\fR is entered as the complete command at the terminal,
\fBmdb\fR repeats the previous command with the current value of dot. This
option is implied by \fB-o\fR \fBadb\fR.
.RE

.sp
.ne 2
.na
\fB\fBshowlmid\fR\fR
.ad
.RS 25n
\fBmdb\fR provides support for symbol naming and identification in user
applications that make use of link maps other than \fILM_ID_BASE\fR and
\fILM_ID_LDSO\fR, as described in \fBSymbol Name Resolution\fR, above. Symbols
on link maps other than \fILM_ID_BASE\fR or \fILM_ID_LDSO\fR is shown as
\fBLMlmid`library`symbol\fR, where \fBlmid\fR is the link-map \fBID\fR in the
default output radix (16). The user can optionally configure \fBmdb\fR to show
the link-map \fBID\fR scope of all symbols and objects, including those
associated with \fILM_ID_BASE\fR and \fILM_ID_LDSO\fR, by enabling the
\fBshowlmid\fR option. Built-in dcmds that deal with object file names displays
link-map \fBID\fRs according to the value of \fBshowlmid\fR above, including
\fB::nm\fR, \fB::mappings\fR, \fB$m\fR, and \fB::objects\fR.
.RE

.RE

.sp
.ne 2
.na
\fB\fB-p\fR \fIpid\fR\fR
.ad
.RS 15n
Attaches to and stops the specified process-id. \fBmdb\fR uses the
\fB/proc/\fIpid\fR/object/a.out\fR file as the executable file pathname.
.RE

.sp
.ne 2
.na
\fB\fB-P\fR \fIprompt\fR\fR
.ad
.RS 15n
Sets the command prompt. The default prompt is '\fB>\fR '.
.RE

.sp
.ne 2
.na
\fB\fB-R\fR \fIroot\fR\fR
.ad
.RS 15n
Sets root directory for pathname expansion. By default, the root directory is
derived from the pathname of the \fBmdb\fR executable itself. The root
directory is substituted in place of the \fB%r\fR token during pathname
expansion.
.RE

.sp
.ne 2
.na
\fB\fB-s\fR \fIdistance\fR\fR
.ad
.RS 15n
Sets the symbol matching distance for address-to-symbol-name conversions to the
specified \fIdistance\fR. By default, \fBmdb\fR sets the distance to zero,
which enables a smart-matching mode. Each \fBELF\fR symbol table entry includes
a value V and size S, representing the size of the function or data object in
bytes. In smart mode, \fBmdb\fR 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.
.RE

.sp
.ne 2
.na
\fB\fB-S\fR\fR
.ad
.RS 15n
Suppresses processing of the user's \fB~/.mdbrc\fR file. By default, \fBmdb\fR
reads and processes the macro file \fB\&.mdbrc\fR if one is present in the
user's home directory, as defined by $\fBHOME\fR. If the \fB-S\fR option is
present, this file is not read.
.RE

.sp
.ne 2
.na
\fB\fB-u\fR\fR
.ad
.RS 15n
Forces user debugging mode. By default, \fBmdb\fR attempts to infer whether the
object and core file operands refer to a user executable and core dump, or to a
pair of operating system crash dump files. The \fB-u\fR option forces \fBmdb\fR
to assume these files are not operating system crash dump files.
.RE

.sp
.ne 2
.na
\fB\fB-U\fR\fR
.ad
.RS 15n
Unload \fBkmdb\fR if it is loaded. You should unload \fBkmdb\fR when it is not
in use to release the memory used by the kernel debugger back to the free
memory available to the operating system.
.RE

.sp
.ne 2
.na
\fB\fB-V\fR \fIversion\fR\fR
.ad
.RS 15n
Sets disassembler version. By default, \fBmdb\fR attempts to infer the
appropriate disassembler version for the debug target. The disassembler can be
set explicitly using the \fB-V\fR option. The \fB::disasms\fR dcmd lists the
available disassembler versions.
.RE

.sp
.ne 2
.na
\fB\fB-w\fR\fR
.ad
.RS 15n
Opens the specified object and core files for writing.
.RE

.sp
.ne 2
.na
\fB\fB-W\fR\fR
.ad
.RS 15n
Permit access to memory addresses that are mapped to I/O devices. By default,
\fBmdb\fR 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.
.RE

.sp
.ne 2
.na
\fB\fB-y\fR\fR
.ad
.RS 15n
Sends explicit terminal initialization sequences for tty mode. Some terminals,
such as \fBcmdtool\fR(1), require explicit initialization sequences to switch
into a tty mode. Without this initialization sequence, terminal features such
as standout mode can not be available to \fBmdb\fR.
.RE

.SH OPERANDS
.sp
.LP
The following operands are supported:
.sp
.ne 2
.na
\fB\fIobject\fR\fR
.ad
.RS 10n
Specifies an \fBELF\fR format object file to examine. \fBmdb\fR provides the
ability to examine and edit \fBELF\fR format executables (\fBET_EXEC\fR),
\fBELF\fR dynamic library files (\fBET_DYN\fR), \fBELF\fR relocatable object
files (\fBET_REL\fR), and operating system unix.X symbol table files.
.RE

.sp
.ne 2
.na
\fB\fIcore\fR\fR
.ad
.RS 10n
Specifies an \fBELF\fR process core file (\fBET_CORE\fR), or an operating
system crash dump vmcore.X file. If an \fBELF\fR core file operand is provided
without a corresponding object file, \fBmdb\fR attempts to infer the name of
the executable file that produced the core using several different algorithms.
If no executable is found, \fBmdb\fR still executes, but some symbol
information can be unavailable.
.RE

.sp
.ne 2
.na
\fB\fIsuffix\fR\fR
.ad
.RS 10n
Specifies the numerical suffix representing a pair of operating system crash
dump files. For example, if the suffix is '\fB3\fR', \fBmdb\fR infers that it
should examine the files '\fBunix.3\fR' and '\fBvmcore.3\fR'. The string of
digits are not interpreted as a suffix if an actual file of the same name is
present in the current directory.
.RE

.SH USAGE
.sp
.LP
\fBmdb\fR processes all input files (including scripts, object files, core
files, and raw data files) in a large file aware fashion. See
\fBlargefile\fR(5) for more information about the processing of large files,
which are files greater than or equal to 2 Gbytes (2^31 bytes).
.SH EXIT STATUS
.sp
.LP
The following exit values are returned:
.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.RS 5n
Debugger completed execution successfully.
.RE

.sp
.ne 2
.na
\fB\fB1\fR\fR
.ad
.RS 5n
A fatal error occurred.
.RE

.sp
.ne 2
.na
\fB\fB2\fR\fR
.ad
.RS 5n
Invalid command line options were specified.
.RE

.SH ENVIRONMENT VARIABLES
.sp
.ne 2
.na
\fB\fBHISTSIZE\fR\fR
.ad
.RS 12n
This variable is used to determine the maximum length of the command history
list. If this variable is not present, the default length is \fB128\fR.
.RE

.sp
.ne 2
.na
\fB\fBHOME\fR\fR
.ad
.RS 12n
This variable is used to determine the pathname of the user's home directory,
where a \fB\&.mdbrc\fR file can reside. If this variable is not present, no
\fB\&.mdbrc\fR processing occurs.
.RE

.sp
.ne 2
.na
\fB\fBSHELL\fR\fR
.ad
.RS 12n
This variable is used to determine the pathname of the shell used to process
shell escapes requested using the \fB!\fR meta-character. If this variable is
not present, \fB/bin/sh\fR is used.
.RE

.SH FILES
.sp
.ne 2
.na
\fB\fB$HOME/.mdbrc\fR\fR
.ad
.sp .6
.RS 4n
User \fBmdb\fR initialization file. The \fB\&.mdbrc\fR 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.
.RE

.sp
.ne 2
.na
\fB\fB/dev/kmem\fR\fR
.ad
.sp .6
.RS 4n
Kernel virtual memory image device. This device special file is used as the
core file when examining the live operating system.
.RE

.sp
.ne 2
.na
\fB\fB/dev/ksyms\fR\fR
.ad
.sp .6
.RS 4n
Kernel symbol table device. This device special file is used as the object file
when examining the live operating system.
.RE

.sp
.ne 2
.na
\fB\fB/proc/\fIpid\fR/*\fR\fR
.ad
.sp .6
.RS 4n
Process information files that are read when examining and controlling user
processes.
.RE

.sp
.ne 2
.na
\fB\fB/usr/lib/adb\fR\fR
.ad
.br
.na
\fB\fB/usr/platform/\fIplatform-name\fR/lib/adb\fR\fR
.ad
.sp .6
.RS 4n
Default directories for macro files that are read with the \fB$<\fR and
\fB$<<\fR dcmds. \fIplatform-name\fR 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 \fBuname\fR \fB-i\fR (see \fBuname\fR(1)).
.RE

.sp
.ne 2
.na
\fB\fB/usr/lib/mdb\fR\fR
.ad
.br
.na
\fB\fB/usr/platform/\fIplatform-name\fR/lib/mdb\fR\fR
.ad
.sp .6
.RS 4n
Default directories for debugger modules that are loaded using the \fB::load\fR
dcmd. \fIplatform-name\fR 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
\fBuname\fR \fB-i\fR (see \fBuname\fR(1)).
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Evolving
.TE

.SH SEE ALSO
.sp
.LP
\fBadb\fR(1), \fBcmdtool\fR(1), \fBgcore\fR(1), \fBproc\fR(1), \fBpgrep\fR(1),
\fBps\fR(1), \fBstty\fR(1), \fBtruss\fR(1), \fBuname\fR(1), \fBcoreadm\fR(1M),
\fBdumpadm\fR(1M), \fBlargefile\fR(5), \fBsavecore\fR(1M), \fBexec\fR(2),
\fBfork\fR(2), \fB_lwp_self\fR(2), \fBpipe\fR(2), \fBvfork\fR(2),
\fBdlopen\fR(3C), \fBelf\fR(3ELF), \fBlibc_db\fR(3LIB), \fBlibkvm\fR(3LIB),
\fBlibthread\fR(3LIB), \fBsignal\fR(3C), \fBsignal.h\fR(3HEAD),
\fBthr_self\fR(3C), \fBcore\fR(4), \fBproc\fR(4), \fBattributes\fR(5),
\fBlargefile\fR(5), \fBthreads\fR(5), \fBksyms\fR(7D), \fBmem\fR(7D)
.sp
.LP
\fILinker and Libraries Guide\fR
.sp
.LP
\fISolaris Modular Debugger Guide\fR
.SH WARNINGS
.SS "Use of the Error Recovery Mechanism"
.sp
.LP
The debugger and its dmods execute in the same address space, and thus it is
quite possible that a buggy dmod can cause \fBmdb\fR to dump core or otherwise
misbehave. The \fBmdb\fR resume capability, described above under \fBSignal
Handling\fR, provides a limited recovery mechanism for these situations.
However, it is not possible for \fBmdb\fR 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.
.SS "Use of the Debugger to Modify the Live Operating System"
.sp
.LP
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.
.SH NOTES
.SS "Limitations on Examining Process Core Files"
.sp
.LP
\fBmdb\fR does not provide support for examining process core files that were
generated by a release of Solaris preceding Solaris 2.6. When debugging core
files generated by a release of Solaris 9 or an earlier release, symbol
information might not be available. Since the text section and read-only data
is not present in those core files, the symbol information might not match the
data present in the process at the time it dumped core. In releases later than
Solaris 9, text sections and read-only data are included in core files by
default. Users can configure their processes to exclude that information from
core files using \fBcoreadm\fR(1M). Thus, the information presented by
\fBmdb\fR 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.
.SS "Limitations on Examining Crash Dump Files"
.sp
.LP
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 implementation can
prevent some dcmds or walkers from working properly. \fBmdb\fR issues a warning
message if it detects this condition. Crash dumps from Solaris x86 systems can
not be examined on Solaris SPARC systems, and vice-versa.
.SS "Relationship Between 32-bit and 64-bit Debugger"
.sp
.LP
\fBmdb\fR provides support for debugging both 32-bit and 64-bit programs. Once
it has examined the target and determined its data model, \fBmdb\fR
automatically re-executes the \fBmdb\fR 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.
.sp
.LP
The debugger can also need to re-execute itself when debugging a 32-bit process
that execs a 64-bit process, or vice-versa. The handling of this situation is
discussed in more detail under \fBInteraction with Exec\fR, below.
.SS "Interaction with Exec"
.sp
.LP
When a controlled process performs a successful \fBexec\fR(2), the behavior of
the debugger is controlled by the \fB::set\fR \fB-o\fR \fBfollow_exec_mode\fR
option, as described above. If the debugger and victim process have the same
data model, then the "\fBstop\fR" and "\fBfollow\fR" modes determine whether
\fBmdb\fR automatically continues the target or returns to the debugger prompt
following the exec. If the debugger and victim process have a different data
model, then the "\fBfollow\fR" behavior causes \fBmdb\fR to automatically
re-exec the \fBmdb\fR 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.
.sp
.LP
If a 32-bit victim process execs a 64-bit program, then "\fBstop\fR" 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
\fB::release\fR \fB-a\fR dcmd, quit \fBmdb\fR, and then execute \fBmdb\fR
\fB-p\fR \fIpid\fR to re-attach the 64-bit debugger to the process.
.sp
.LP
If a 64-bit victim process execs a 32-bit program, then "\fBstop\fR" 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.
.SS "Interaction with Job Control"
.sp
.LP
If the debugger is attached to a process that is stopped by job control (that
is, it stopped in response to \fBSIGTSTP\fR, \fBSIGTTIN\fR, or \fBSIGTTOU\fR),
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 \fBmdb\fR), \fBmdb\fR attempts to
bring the associated process group to the foreground and to continue the
process with \fBSIGCONT\fR to resume it from job control stop. When \fBmdb\fR
is detached from such a process, it restores the process group to the
background before exiting. If the victim process is not a member of the same
session, \fBmdb\fR 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. \fBmdb\fR prints a warning in this case, and the user
must issue an "\fBfg\fR" command from the appropriate shell in order to resume
the process.
.SS "Process Attach and Release"
.sp
.LP
When \fBmdb\fR 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 \fB-o\fR \fBnostop\fR option is enabled prior to attaching the
debugger to a process with \fB-p\fR, or prior to issuing an \fB::attach\fR or
\fB:A\fR command, \fBmdb\fR attaches to the process but does not stop it. While
the process is still running, it can be inspected as usual (albeit with
inconsistent results) and breakpoints or other tracing flags might be enabled.
If the \fB:c\fR or \fB::cont\fR dcmds are executed while the process is
running, the debugger waits for the process to stop. If no traced software
events occur, the user can send an interrupt (\fB^C\fR) after \fB:c\fR or
\fB::cont\fR to force the process to stop and return control to the debugger.
.sp
.LP
\fBmdb\fR releases the current running process (if any) when the \fB:R\fR,
\fB::release\fR, \fB:r\fR, \fB::run\fR, \fB$q\fR, or \fB::quit\fR dcmds are
executed, or when the debugger terminates as the result of an \fBEOF\fR or
signal. If the process was originally created by the debugger using \fB:r\fR or
\fB::run\fR, it is forcibly terminated as if by \fBSIGKILL\fR when it is
released. If the process was already running prior to attaching \fBmdb\fR to
it, it is set running again when it is released. A process can be released and
left stopped and abandoned using the \fB::release\fR \fB-a\fR option.
.SS "Symbolic Debugging Information"
.sp
.LP
The \fB::list\fR, \fB::offsetof\fR, \fB::print\fR, and \fB::sizeof\fR dcmds
require that one or more load objects contain compressed symbolic debugging
information suitable for use with \fBmdb\fR. This information is currently only
available for certain Solaris kernel modules.
.SS "Developer Information"
.sp
.LP
The \fISolaris Modular Debugger Guide\fR provides a more detailed description
of \fBmdb\fR features, as well as information for debugger module developers.
.sp
.LP
The header file \fB<sys/mdb_modapi.h>\fR contains prototypes for the functions
in the MDB Module \fBAPI\fR, and the SUNWmdbdm package provides source code for
an example module in the directory \fB/usr/demo/mdb\fR.