Windows PowerShell command on Get-command mdb

Manual Pages for UNIX Operating System command usage for man mdb

User Commands mdb(1)

NAME

mdb - modular debugger

SYNOPSIS

mdb [-fkmuwyAFKMSUW] [+_o option] [-p pid] [-s distance]

[-I path] [-L path] [-P prompt] [-R root]

[-V dis-version] [object [core] | core | suffix]

DESCRIPTION

Introduction

The mdb utility is an extensible utility for low-level

debugging and editing of the live operating system, operat-

ing system crash dumps, user processes, user process core dumps, and object files. For a more detailed description of

mdb features, refer to the manual, Oracle Solaris Modular

Debugger Guide. Debugging is the process of analyzing the execution and state of a software program in order to remove defects. Traditional debugging tools provide facilities for execution

control so that programmers can re-execute programs in a

controlled environment and display the current state of pro-

gram data or evaluate expressions in the source language used to develop the program. Unfortunately, these techniques are often inappropriate for

debugging complex software systems such as an operating sys-

tem, where bugs might not be reproducible and program state is massive and distributed, for programs that are highly optimized, have had their debug information removed, or are

themselves low-level debugging tools, or for customer situa-

tions where the developer can only access post-mortem infor-

mation.

mdb provides a completely customizable environment for

debugging these programs and scenarios, including a dynamic module facility that programmers can use to implement their

own debugging commands to perform program-specific analysis.

Each mdb module can be used to examine the program in

several different contexts, including live and post-mortem.

Definitions The target is the program being inspected by the debugger.

mdb currently provides support for the following types of

targets: user processes, user process core files, the live operating system (via /dev/kmem and /dev/ksyms), operating system crash dumps, user process images recorded inside an operating system crash dump, ELF object files, and raw

SunOS 5.11 Last change: 14 Aug 2009 1

User Commands mdb(1)

binary files. Each target exports a standard set of proper-

ties, including one or more address spaces, one or more sym-

bol tables, a set of load objects, and a set of threads that can be examined using the debugger commands described below.

A debugger command, or dcmd (pronounced dee-command) in mdb

terminology, is a routine in the debugger that can access

any of the properties of the current target. mdb parses com-

mands from standard input, and then executes the correspond-

ing dcmds. Each dcmd can also accept a list of string or numerical arguments, as shown in the syntax description

below. mdb contains a set of built-in dcmds, described

below, that are always available. You can also extend the

capabilities of mdb itself by writing your own dcmds, as

described in the Oracle Solaris Modular Debugger Guide. A walker is a set of routines that describe how to walk, or iterate, through the elements of a particular program data

structure. A walker encapsulates the data structure's imple-

mentation from dcmds and from mdb itself. You can use walk-

ers interactively, or use them as a primitive to build other

dcmds or walkers. As with dcmds, you can extend mdb by

implementing your own walkers as part of a debugger module.

A debugger module, or dmod (pronounced dee-mod), is a dynam-

ically loaded library containing a set of dcmds and walkers.

During initialization, mdb attempts to load dmods

corresponding to the load objects present in the target. You

can subsequently load or unload dmods at any time while run-

ning mdb. mdb ships with a set of standard dmods for debug-

ging the Solaris kernel. The Oracle Solaris Modular Debugger Guide contains more information on developing your own debugger modules. A macro file is a text file containing a set of commands to

execute. Macro files are typically used to automate the pro-

cess of displaying a simple data structure. mdb provides

complete backward compatibility for the execution of macro files written for adb(1), and the Solaris installation

includes a set of macro files for debugging the Solaris ker-

nel that can be used with either tool. Syntax The debugger processes commands from standard input. If

standard input is a terminal, mdb provides terminal editing

capabilities. mdb can also process commands from macro files

and from dcmd pipelines, described below. The language syn-

tax is designed around the concept of computing the value of

SunOS 5.11 Last change: 14 Aug 2009 2

User Commands mdb(1)

an expression (typically a memory address in the target), and then applying a dcmd to that address. The current address location is referred to as dot, and its value is referenced using ``.''. A metacharacter is one of the following characters:

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

NEWLINE SPACE TAB

A blank is a TAB or a SPACE. A word is a sequence of charac-

ters separated by one or more non-quoted metacharacters.

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

A dcmd is denoted by one of the following words or metachar-

acters:

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

dcmds named by metacharacters or prefixed by a single $ or :

are provided as built-in operators, and implement complete

compatibility with the command set of the legacy adb(1)

utility. Once a dcmd has been parsed, the /, \, ?, =, >, $,

and : characters are no longer recognized as metacharacters until the termination of the argument list.

A simple-command is a dcmd followed by a sequence of zero or

more blank-separated words. The words are passed as argu-

ments to the invoked dcmd, except as specified under Quoting and Arithmetic Expansion below. Each dcmd returns an exit status that indicates it was either successful, failed, or was invoked with invalid arguments. A pipeline is a sequence of one or more simple commands

separated by |. Unlike the shell, dcmds in mdb pipelines are

not executed as separate processes. After the pipeline has

SunOS 5.11 Last change: 14 Aug 2009 3

User Commands mdb(1)

been parsed, each dcmd is invoked in order from left to right. Each dcmd's output is processed and stored as

described under dcmd Pipelines below. Once the left-hand

dcmd is complete, its processed output is used as input for the next dcmd in the pipeline. If any dcmd does not return a successful exit status, the pipeline is aborted. An expression is a sequence of words that is evaluated to

compute a 64-bit unsigned integer value. The words are

evaluated using the rules described under Arithmetic Expan-

sion below. Commands A command is one of the following: pipeline [! word ...] [ ; ]

A simple-command or pipeline can be optionally suffixed

with the ! character, indicating that the debugger should open a pipe(2) and send the standard output of

the last dcmd in the mdb pipeline to an external process

created by executing $SHELL -c followed by the string

formed by concatenating the words after the ! character. For more details, refer to Shell Escapes below. expression pipeline [! word ...] [ ; ]

A simple-command or pipeline can be prefixed with an

expression. Before execution of the pipeline, the value of dot (the variable denoted by ``.'') is set to the value of the expression. expression , expression pipeline [! word ...] [ ; ]

A simple-command or pipeline can be prefixed with two

expressions. The first is evaluated to determine the new value of dot, and the second is evaluated to determine a repeat count for the first dcmd in the pipeline. This dcmd is executed count times before the next dcmd in the pipeline is executed. The repeat count only applies to the first dcmd in the pipeline. , expression pipeline [! word ...] [ ; ]

If the initial expression is omitted, dot is not modi-

fied but the first dcmd in the pipeline is repeated according to the value of the expression.

SunOS 5.11 Last change: 14 Aug 2009 4

User Commands mdb(1)

expression [! word ...] [ ; ] A command can consist only of an arithmetic expression. The expression is evaluated and the dot variable is set to its value, and then the previous dcmd and arguments are executed using the new value of dot. expression, expression [! word ...] [ ; ] A command can consist only of a dot expression and repeat count expression. After dot is set to the value of the first expression, the previous dcmd and arguments are repeatedly executed the number of times specified by the value of the second expression. , expression [! word ...] [ ; ]

If the initial expression is omitted, dot is not modi-

fied but the previous dcmd and arguments are repeatedly executed the number of times specified by the value of the count expression. ! word ... [ ; ] If the command begins with the ! character, no dcmds are

executed and the debugger simply executes $SHELL -c fol-

lowed by the string formed by concatenating the words after the ! character. Comments

A word beginning with // causes that word and all the subse-

quent characters up to a NEWLINE to be ignored. Arithmetic Expansion

Arithmetic expansion is performed when an mdb command is

preceded by an optional expression representing a start address, or a start address and a repeat count. Arithmetic

expansion can also be performed to compute a numerical argu-

ment for a dcmd. An arithmetic expression can appear in an

argument list enclosed in square brackets preceded by a dol-

lar sign ($[ expression ]), and is replaced by the value of

the expression. Expressions can contain any of the following special words: integer

SunOS 5.11 Last change: 14 Aug 2009 5

User Commands mdb(1)

The specified integer value. Integer values can be pre-

fixed with 0i or 0I to indicate binary values, 0o or 0O to indicate octal values, 0t or 0T to indicate decimal values, and 0x or 0X to indicate hexadecimal values (the default).

0[tT][0-9]+.[0-9]+

The specified decimal floating point value, converted to

its IEEE double-precision floating point representation.

'cccccccc' The integer value computed by converting each character

to a byte equal to its ASCII value. Up to eight charac-

ters can be specified in a character constant. Charac-

ters are packed into the integer in reverse order

(right-to-left) beginning at the least significant byte.

SunOS 5.11 Last change: 14 Aug 2009 6

User Commands mdb(1)

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

Unary operators are right associative and have higher pre-

cedence than binary operators. The unary operators are:

#expression

Logical negation. ~expression Bitwise complement.

-expression

Integer negation.

%expression

The value of a pointer-sized quantity at the object file

location corresponding to virtual address expression in the target's virtual address space.

%/[csil]/expression

The value of a char, short, int, or long-sized quantity

at the object file location corresponding to virtual address expression in the target's virtual address space.

%/[1248]/expression

The value of a one, two, four, or eight-byte quantity at

the object file location corresponding to virtual address expression in the target's virtual address space.

SunOS 5.11 Last change: 14 Aug 2009 7

User Commands mdb(1)

*expression

The value of a pointer-sized quantity at virtual address

expression in the target's virtual address space. */[csil]/expression

The value of a char, short, int, or long-sized quantity

at virtual address expression in the target's virtual address space. */[1248]/expression

The value of a one, two, four, or eight-byte quantity at

virtual address expression in the target's virtual address space.

Binary operators are left associative and have lower pre-

cedence than unary operators. The binary operators, in order of precedence from highest to lowest, are: * Integer multiplication.

Integer division.

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

side. + Integer addition.

Integer subtraction.

SunOS 5.11 Last change: 14 Aug 2009 8

User Commands mdb(1)

<< Bitwise shift left. >> Bitwise shift right. == Logical equality. != Logical inequality. & Bitwise AND. ^ Bitwise exclusive OR. | Bitwise inclusive OR. Quoting Each metacharacter described above (see Syntax) terminates a

word unless quoted. Characters can be quoted (forcing mdb to

interpret each character as itself without any special sig-

nificance) by enclosing them in a pair of single (' ') or double (" ") quote marks. A single quote cannot appear

within single quotes. Inside double quotes, mdb recognizes

the C programming language character escape sequences. Shell Escapes The ! character can be used to create a pipeline between an

mdb command and the user's shell. If the $SHELL environment

variable is set, mdb forks and execs this program for shell

escapes; otherwise /bin/sh is used. The shell is invoked

with the -c option followed by a string formed by con-

catenating the words after the ! character. The ! character takes precedence over all other metacharacters, except

SunOS 5.11 Last change: 14 Aug 2009 9

User Commands mdb(1)

semicolon (;) and NEWLINE. Once a shell escape is detected, the remaining characters up to the next semicolon or NEWLINE are passed as is to the shell. The output of shell commands

can not be piped to mdb dcmds. Commands executed by a shell

escape have their output sent directly to the terminal, not

to mdb.

Variables A variable is a variable name, a corresponding integer value, and a set of attributes. A variable name is a sequence of letters, digits, underscores, or periods. A variable can be assigned a value using the > dcmd or ::typeset dcmd, and its attributes can be manipulated using the ::typeset dcmd. Each variable's value is represented as

a 64-bit unsigned integer. A variable can have one or more

of the following attributes: read-only (cannot be modified

by the user), persistent (cannot be unset by the user), and

tagged (user-defined indicator).

The following variables are defined as persistent: 0 The most recent value printed using the /, \, ?, or = dcmd. 9

The most recent count used with the $< dcmd.

b The virtual address of the base of the data section. d The size of the data section in bytes. e The virtual address of the entry point. m The initial bytes (magic number) of the target's primary object file, or zero if no object file has been read

SunOS 5.11 Last change: 14 Aug 2009 10

User Commands mdb(1)

yet. t The size of the text section in bytes. hits The count of the number of times the matched software event specifier has been matched. See Event Callbacks, below. thread The thread identifier of the current representative thread. The value of the identifier depends on the threading model used by the current target. See Thread Support, below.

In addition, the mdb kernel and process targets export the

current values of the representative thread's register set as named variables. The names of these variables depend on the target's platform and instruction set architecture. Symbol Name Resolution

As explained in the Syntax description above, a symbol iden-

tifier present in an expression context evaluates to the

value of this symbol. The value typically denotes the vir-

tual address of the storage associated with the symbol in the target's virtual address space. A target can support

multiple symbol tables including, but not limited to, a pri-

mary executable symbol table, a primary dynamic symbol

table, a run-time link-editor symbol table, and standard and

dynamic symbol tables for each of a number of load objects (such as shared libraries in a user process, or kernel modules in the Solaris kernel). The target typically searches the primary executable's symbol tables first, and then one or more of the other symbol tables. Notice that ELF symbol tables only contain entries for external, global, and

static symbols; automatic symbols do not appear in the sym-

bol tables processed by mdb.

Additionally, mdb provides a private user-defined symbol

table that is searched prior to any of the target symbol tables. The private symbol table is initially empty, and can be manipulated using the ::nmadd and ::nmdel dcmds. The ::nm

SunOS 5.11 Last change: 14 Aug 2009 11

User Commands mdb(1)

-P option can be used to display the contents of the private

symbol table. The private symbol table allows the user to create symbol definitions for program functions or data that were either missing from the original program or stripped

out. These definitions are then used whenever mdb converts a

symbolic name to an address, or an address to the nearest symbol. As targets contain multiple symbol tables, and each symbol

table can include symbols from multiple object files, dif-

ferent symbols with the same name can exist. mdb uses the

backquote (`) character as a symbol name scoping operator to

allow the programmer to obtain the value of the desired sym-

bol in this situation. The programmer can specify the scope used to resolve a symbol name as either: object`name, or file`name, or object`file`name. The object identifier refers to the name of a load object. The file identifier refers to the basename of a source file that has a symbol of type

STT_FILE in the specified object's symbol table. The object

identifier's interpretation depends on the target type.

The mdb kernel target expects object to specify the basename

of a loaded kernel module. For example, the symbol name

specfs`_init

evaluates to the value of the _init symbol in the specfs

kernel module.

The mdb process target expects object to specify the name of

the executable or of a loaded shared library. It can take any of the following forms: 1. An exact match (that is, a full pathname): /usr/lib/libc.so.1 2. An exact basename match: libc.so.1 3. An initial basename match up to a ``.'' suffix: libc.so or libc 4. The literal string a.out is accepted as an alias for the executable.

SunOS 5.11 Last change: 14 Aug 2009 12

User Commands mdb(1)

The process target also accepts any of the four forms

described above preceded by an optional link-map id (lmid).

The lmid prefix is specified by an initial "LM" followed by

the link-map id in hexadecimal followed by an additional

backquote. For example, the symbol name

LM0`libc.so.1`_init

evaluates to the value of the _init symbol in the libc.so.1

library that is loaded on link-map 0 (LM_ID_BASE). The

link-map specifier can be necessary to resolve symbol naming

conflicts in the event that the same library is loaded on more than one link map. For more information on link maps, refer to the Linker and Libraries Guide and dlopen(3C).

Link-map identifiers are displayed when symbols are printed

according to the setting of the showlmid option, as described under OPTIONS.

In the case of a naming conflict between symbols and hexade-

cimal integer values, mdb attempts to evaluate an ambiguous

token as a symbol first, before evaluating it as an integer value. For example, the token f can either refer to the decimal integer value 15 specified in hexadecimal (the default base), or to a global variable named f in the target's symbol table. If a symbol with an ambiguous name is present, the integer value can be specified by using an explicit 0x or 0X prefix. dcmd and Walker Name Resolution

As described earlier, each mdb dmod provides a set of dcmds

and walkers. dcmds and walkers are tracked in two distinct,

global namespaces. mdb also keeps track of a dcmd and walker

namespace associated with each dmod. Identically named dcmds or walkers within a given dmod are not allowed: a dmod with this type of naming conflict fails to load. Name conflicts between dcmds or walkers from different dmods are allowed in the global namespace. In the case of a conflict, the first dcmd or walker with that particular name to be loaded is

given precedence in the global namespace. Alternate defini-

tions are kept in a list in load order. The backquote char-

acter (`) can be used in a dcmd or walker name as a scoping operator to select an alternate definition. For example, if dmods m1 and m2 each provide a dcmd d, and m1 is loaded prior to m2, then: ::d Executes m1's definition of d.

SunOS 5.11 Last change: 14 Aug 2009 13

User Commands mdb(1)

::m1`d Executes m1's definition of d. ::m2`d Executes m2's definition of d. If module m1 were now unloaded, the next dcmd on the global

definition list (m2`d) would be promoted to global visibil-

ity. The current definition of a dcmd or walker can be

determined using the ::which dcmd, described below. The glo-

bal definition list can be displayed using the ::which -v

option. dcmd Pipelines dcmds can be composed into a pipeline using the | operator.

The purpose of a pipeline is to pass a list of values, typi-

cally virtual addresses, from one dcmd or walker to another. Pipeline stages might be used to map a pointer from one type of data structure to a pointer to a corresponding data structure, to sort a list of addresses, or to select the addresses of structures with certain properties.

mdb executes each dcmd in the pipeline in order from left to

right. The leftmost dcmd is executed using the current value

of dot, or using the value specified by an explicit expres-

sion at the start of the command. When a | operator is

encountered, mdb creates a pipe (a shared buffer) between

the output of the dcmd to its left and the mdb parser, and

an empty list of values. As the dcmd executes, its standard output is placed in the pipe and then consumed and evaluated

by the parser, as if mdb were reading this data from stan-

dard input. Each line must consist of an arithmetic expres-

sion terminated by a NEWLINE or semicolon (;). The value of the expression is appended to the list of values associated with the pipe. If a syntax error is detected, the pipeline is aborted. When the dcmd to the left of a | operator completes, the list of values associated with the pipe is then used to invoke the dcmd to the right of the | operator. For each

value in the list, dot is set to this value and the right-

hand dcmd is executed. Only the rightmost dcmd in the pipe-

line has its output printed to standard output. If any dcmd in the pipeline produces output to standard error, these messages are printed directly to standard error and are not

SunOS 5.11 Last change: 14 Aug 2009 14

User Commands mdb(1)

processed as part of the pipeline. Signal Handling

The debugger ignores the PIPE and QUIT signals. The INT sig-

nal aborts the command that is currently executing. The debugger intercepts and provides special handling for the ILL, TRAP, EMT, FPE, BUS, and SEGV signals. If any of these signals are generated asynchronously (that is, delivered

from another process using kill(2)), mdb restores the signal

to its default disposition and dump core. However, if any of these signals are generated synchronously by the debugger process itself and a dcmd from an externally loaded dmod is

currently executing, and standard input is a terminal, mdb

provides a menu of choices allowing the user to force a core dump, quit without producing a core dump, stop for attach by a debugger, or attempt to resume. The resume option aborts all active commands and unload the dmod whose dcmd was

active at the time the fault occurred. It can then be subse-

quently re-loaded by the user. The resume option provides

limited protection against buggy dcmds. Refer to WARNINGS, Use of the Error Recovery Mechanism, below for information about the risks associated with the resume option.

Command Re-entry

The text of the last HISTSIZE (default 128) commands entered

from a terminal device are saved in memory. The in-line

editing facility, described next, provides key mappings for searching and fetching elements from the history list.

In-line Editing

If standard input is a terminal device, mdb provides some

simple emacs-style facilities for editing the command line.

The search, previous, and next commands in edit mode provide access to the history list. Only strings, not patterns, are matched when searching. In the table below, the notation for control characters is caret (^) followed by a character

shown in upper case. The notation for escape sequences is M-

followed by a character. For example, M-f (pronounced meta-

eff) is entered by depressing ESC followed by 'f', or by depressing Meta followed by 'f' on keyboards that support a Meta key. A command line is committed and executed using RETURN or NEWLINE. The edit commands are: ^F Move cursor forward (right) one character.

M-f

Move cursor forward one word.

SunOS 5.11 Last change: 14 Aug 2009 15

User Commands mdb(1)

^B Move cursor backward (left) one character.

M-b

Move cursor backward one word. ^A Move cursor to start of line. ^E Move cursor to end of line. ^D Delete current character, if the current line is not empty. If the current line is empty, ^D denotes EOF and the debugger exits.

M-^H

(Meta-backspace) Delete previous word.

^K Delete from the cursor to the end of the line. ^L Clear the screen and reprint the current line. ^T Transpose current character with next character. ^N Fetch the next command from the history. Each time ^N is entered, the next command forward in time is retrieved.

SunOS 5.11 Last change: 14 Aug 2009 16

User Commands mdb(1)

^P Fetch the previous command from the history. Each time ^P is entered, the next command backward in time is retrieved. ^R[string] Search backward in the history for a previous command line containing string. The string should be terminated

by a RETURN or NEWLINE. If string is omitted, the previ-

ous history element containing the most recent string is retrieved.

The editing mode also interprets the following user-defined

sequences as editing commands. User defined sequences can be read or modified using the stty(1) command. erase User defined erase character (usually ^H or ^?). Delete previous character. intr User defined interrupt character (usually ^C). Abort the current command and print a new prompt. kill User defined kill character (usually ^U). Kill the entire current command line. quit User defined quit character (usually ^\). Quit the debugger. suspend User defined suspend character (usually ^Z). Suspend the debugger.

SunOS 5.11 Last change: 14 Aug 2009 17

User Commands mdb(1)

werase User defined word erase character (usually ^W). Erase the preceding word. On keyboards that support an extended keypad with arrow

keys, mdb interprets these keystrokes as editing commands:

up-arrow

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

down-arrow

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

left-arrow

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

right-arrow

Move cursor forward one character (same as ^F). Output Pager

mdb provides a built-in output pager. The output pager is

enabled if the debugger's standard output is a terminal dev-

ice. Each time a command is executed, mdb pauses after one

screenful of output is produced and displays a pager prompt: >> More [, , q, n, c, a] ? The following key sequences are recognized by the pager: SPACE Display the next screenful of output. a, A

Abort the current top-level command and return to the

SunOS 5.11 Last change: 14 Aug 2009 18

User Commands mdb(1)

prompt. c, C Continue displaying output without pausing at each

screenful until the current top-level command is com-

plete. n, N, NEWLINE, RETURN Display the next line of output. q, Q, ^C, ^\ Quit (abort) the current dcmd only. Formatting dcmds The /, \, ?, and = metacharacters are used to denote the special output formatting dcmds. Each of these dcmds accepts

an argument list consisting of one or more format charac-

ters, repeat counts, or quoted strings. A format character is one of the ASCII characters shown in the table below. Format characters are used to read and format data from the target. A repeat count is a positive integer preceding the format character that is always interpreted in base 10 (decimal). A repeat count can also be specified as an expression enclosed in square brackets preceded by a dollar

sign ($[ ]). A string argument must be enclosed in double-

quotes (" "). No blanks are necessary between format argu-

ments. The formatting dcmds are: / Display data from the target's virtual address space starting at the virtual address specified by dot. \ Display data from the target's physical address space starting at the physical address specified by dot. ?

SunOS 5.11 Last change: 14 Aug 2009 19

User Commands mdb(1)

Display data from the target's primary object file starting at the object file location corresponding to the virtual address specified by dot. = Display the value of dot itself in each of the specified

data formats. The = dcmd is therefore useful for con-

verting between bases and performing arithmetic.

In addition to dot, mdb keeps track of another global value

called the increment. The increment represents the distance between dot and the address following all the data read by the last formatting dcmd. For example, if a formatting dcmd

is executed with dot equal to address A, and displays a 4-

byte integer, then after this dcmd completes, dot is still A, but the increment is set to 4. The + character (described under Arithmetic Expansion above) would now evaluate to the value A + 4, and could be used to reset dot to the address of the next data object for a subsequent dcmd. Most format characters increase the value of the increment by the number of bytes corresponding to the size of the data format, shown in the table. The table of format characters

can be displayed from within mdb using the ::formats dcmd.

The format characters are: + increment dot by the count (variable size)

- decrement dot by the count (variable size)

B hexadecimal int (1 byte) C character using C character notation (1 byte) D decimal signed int (4 bytes) E decimal unsigned long long (8 bytes) F double (8 bytes) G octal unsigned long long (8 bytes) H swap bytes and shorts (4 bytes) I address and disassembled instruction (variable size) J hexadecimal long long (8 bytes)

K hexadecimal uintptr_t (4 or 8 bytes)

N newline O octal unsigned int (4 bytes) P symbol (4 or 8 bytes) Q octal signed int (4 bytes) R binary int (8 bytes)

SunOS 5.11 Last change: 14 Aug 2009 20

User Commands mdb(1)

S string using C string notation (variable size) T horizontal tab U decimal unsigned int (4 bytes) V decimal unsigned int (1 byte) W default radix unsigned int (4 bytes) X hexadecimal int (4 bytes)

Y decoded time32_t (4 bytes)

Z hexadecimal long long (8 bytes) ^ decrement dot by increment * count (variable size) a dot as symbol+offset b octal unsigned int (1 byte) c character (1 byte) d decimal signed short (2 bytes) e decimal signed long long (8 bytes) f float (4 bytes) g octal signed long long (8 bytes) h swap bytes (2 bytes) i disassembled instruction (variable size) n newline o octal unsigned short (2 bytes) p symbol (4 or 8 bytes) q octal signed short (2 bytes) r whitespace s raw string (variable size) t horizontal tab u decimal unsigned short (2 bytes) v decimal signed int (1 byte) w default radix unsigned short (2 bytes) x hexadecimal short (2 bytes)

y decoded time64_t (8 bytes)

The /, \, and ? formatting dcmds can also be used to write to the target's virtual address space, physical address space, or object file by specifying one of the following modifiers as the first format character, and then specifying

a list of words that are either immediate values or expres-

sions enclosed in square brackets preceded by a dollar sign

($[ ]).

The write modifiers are: v Write the lowest byte of the value of each expression to the target beginning at the location specified by dot.

SunOS 5.11 Last change: 14 Aug 2009 21

User Commands mdb(1)

Write the lowest two bytes of the value of each expres-

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

Write the complete 8 bytes of the value of each expres-

sion to the target beginning at the location specified by dot. The /, \, and ? formatting dcmds can also be used to search for a particular integer value in the target's virtual address space, physical address space, and object file, respectively, by specifying one of the following modifiers as the first format character, and then specifying a value and optional mask. The value and mask are each specified as either immediate values or expressions enclosed in square brackets preceded by a dollar sign. If only a value is

specified, mdb reads integers of the appropriate size and

stops at the address containing the matching value. If a

value V and mask M are specified, mdb reads integers of the

appropriate size and stops at the address containing a value X where (X & M) == V. At the completion of the dcmd, dot is updated to the address containing the match. If no match is found, dot is left at the last address that was read. The search modifiers are:

l Search for the specified 2-byte value.

L Search for the specified 4-byte value.

M Search for the specified 8-byte value.

Notice that for both user and kernel targets, an address

space is typically composed of a set of discontiguous seg-

ments. It is not legal to read from an address that does not

SunOS 5.11 Last change: 14 Aug 2009 22

User Commands mdb(1)

have a corresponding segment. If a search reaches a segment boundary without finding a match, it aborts when the read past the end of the segment boundary fails. Execution Control

mdb provides facilities for controlling and tracing the exe-

cution of a live running program. Currently, only the user

process target provides support for execution control. mdb

provides a simple model of execution control: a target pro-

cess can be started from within the debugger using ::run, or

mdb can attach to an existing process using :A, ::attach, or

the -p command-line option, as described below. A list of

traced software events can be specified by the user. Each time a traced event occurs in the target process, all threads in the target stop, the thread that triggered the event is chosen as the representative thread, and control

returns to the debugger. Once the target program is set run-

ning, control can be asynchronously returned to the debugger

by typing the user-defined interrupt character (typically

^C). A software event is a state transition in the target program that is observed by the debugger. For example, the debugger can observe the transition of a program counter register to

a value of interest (a breakpoint) or the delivery of a par-

ticular signal. A software event specifier is a description of a class of software events that is used by the debugger to instrument the target program in order to observe these events. The ::events dcmd is used to list the software event specifiers. A set of standard properties is associated with each event specifier, as described under ::events, below. The debugger can observe a variety of different software events, including breakpoints, watchpoints, signals, machine faults, and system calls. New specifiers can be created

using ::bp, ::fltbp, ::sigbp, ::sysbp, or ::wp. Each specif-

ier has an associated callback (an mdb command string to

execute as if it had been typed at the command prompt) and a

set of properties, as described below. Any number of specif-

iers for the same event can be created, each with different callbacks and properties. The current list of traced events and the properties of the corresponding event specifiers can be displayed using the ::events dcmd. The event specifier properties are defined as part of the description of the ::events and ::evset dcmds, below.

SunOS 5.11 Last change: 14 Aug 2009 23

User Commands mdb(1)

The execution control built-in dcmds, described below, are

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

The ::evset dcmd and event tracing dcmds allow you to asso-

ciate an event callback (using the -c option) with each

event specifier. The event callbacks are strings that

represent mdb commands to execute when the corresponding

event occurs in the target. These commands are executed as

if they had been typed at the command prompt. Before execut-

ing each callback, the dot variable is set to the value of the representative thread's program counter and the "hits" variable is set to the number of times this specifier has been matched, including the current match.

If the event callbacks themselves contain one or more com-

mands to continue the target (for example, ::cont or

::step), these commands do not immediately continue the tar-

get and wait for it to stop again. Instead, inside of an event callback, the continue dcmds note that a continue operation is now pending, and then return immediately.

Therefore, if multiple dcmds are included in an event call-

back, the step or continue dcmd should be the last command specified. Following the execution of all event callbacks, the target immediately resumes execution if all matching

event callbacks requested a continue. If conflicting con-

tinue operations are requested, the operation with the highest precedence determines what type of continue occurs. The order of precedence from highest to lowest is: step,

step-over (next), step-out, continue.

Thread Support

mdb provides facilities to examine the stacks and registers

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

The mdb kernel target exports the virtual address of the

corresponding internal thread structure as the identifier

SunOS 5.11 Last change: 14 Aug 2009 24

User Commands mdb(1)

for a given thread. The Oracle Solaris Modular Debugger Guide provides more information on debugging support for

threads in the Solaris kernel. The mdb process target pro-

vides proper support for examination of multi-threaded user

processes that use the native lwp_* interfaces,

/usr/lib/libthread.so or /usr/lib/lwp/libthread.so. When

debugging a live user process, mdb detects if a single

threaded process dlopens or closes libthread and automati-

cally adjusts its view of the threading model on-the-fly.

The process target thread identifiers corresponds to either

the lwpid_t, thread_t, or pthread_t of the representative,

depending on the threading model used by the application.

If mdb is debugging a user process target and the target

makes use of compiler-supported thread-local storage, mdb

automatically evaluates symbol names referring to thread-

local storage to the address of the storage corresponding to

the current representative thread. The ::tls built-in dcmd

can be used to display the value of the symbol for threads other than the representative thread.

Built-in dcmds

mdb provides a set of built-in dcmds that are always

defined. Some of these dcmds are only applicable to certain targets: if a dcmd is not applicable to the current target, it fails and prints a message indicating "command is not

supported by current target". In many cases, mdb provides a

mnemonic equivalent (::identifier) for the legacy adb(1) dcmd names. For example, ::quit is provided as the

equivalent of $q. Programmers who are experienced with

adb(1) or who appreciate brevity or arcana can prefer the $

or : forms of the built-ins. Programmers who are new to mdb

might prefer the more verbose :: form. The built-ins are

shown in alphabetical order. If a $ or : form has a ::iden-

tifier equivalent, it is shown underneath the ::identifier

form. The built-in dcmds are:

> variable-name

>/modifier/variable-name

Assign the value of dot to the specified named variable.

Some variables are read-only and can not be modified. If

the > is followed by a modifier character surrounded by

/ /, then the value is modified as part of the assign-

ment. The modifier characters are: c

unsigned char quantity (1-byte)

SunOS 5.11 Last change: 14 Aug 2009 25

User Commands mdb(1)

unsigned short quantity (2-byte)

unsigned int quantity (4-byte)

unsigned long quantity (4-byte in 32-bit, 8-byte in

64-bit)

Notice that these operators do not perform a cast.

Instead, they fetch the specified number of low-order

bytes (on little-endian architectures) or high-order

bytes (big-endian architectures). Modifiers are provided

for backwards compatibility; the mdb */modifier/ and

%/modifier/ syntax should be used instead.

$< macro-name

Read and execute commands from the specified macro file. The filename can be given as an absolute or relative path. If the filename is a simple name (that is, if it

does not contain a '/'), mdb searches for it in the

macro file include path. If another macro file is currently being processed, this file is closed and replaced with the new file.

$<< macro-name

Read and execute commands from the specified macro file

(as with $<), but do not close the current open macro

file.

Print the process-ID and current signal of the target if

it is a user process or core file, and then print the general register set of the representative thread.

[ address ] $C [ count ]

Print a C stack backtrace, including stack frame pointer information. If the dcmd is preceded by an explicit

SunOS 5.11 Last change: 14 Aug 2009 26

User Commands mdb(1)

address, a backtrace beginning at this virtual memory address is displayed. Otherwise the stack of the representative thread is displayed. If an optional count

value is given as an argument, no more than count argu-

ments are displayed for each stack frame in the output.

[ base ] $d

Get or set the default output radix. If the dcmd is pre-

ceded by an explicit expression, the default output radix is set to the given base; otherwise the current radix is printed in base 10 (decimal). The default radix is base 16 (hexadecimal).

Print a list of all known external (global) symbols of type object or function, the value of the symbol, and

the first 4 (32-bit mdb) or 8 (64-bit mdb) bytes stored

at this location in the target's virtual address space. The ::nm dcmd provides more flexible options for displaying symbol tables.

$P prompt-string

Set the prompt to the specified prompt-string. The

default prompt is '> '. The prompt can also be set using

::set -P or the -P command-line option.

distance $s

Get or set the symbol matching distance for address-to-

symbol-name conversions. The symbol matching distance

modes are discussed along with the -s command-line

option under OPTIONS. The symbol matching distance can

also be modified using the ::set -s option. If no dis-

tance is specified, the current setting is displayed.

Print a list of the named variables that have non-zero

values. The ::vars dcmd provides other options for list-

ing variables.

width $w

SunOS 5.11 Last change: 14 Aug 2009 27

User Commands mdb(1)

Set the output page width to the specified value. Typi-

cally, this command is not necessary as mdb queries the

terminal for its width and handles resize events.

Re-open the target for writing, as if mdb had been exe-

cuted with the -w option on the command line. Write mode

can also be enabled with the ::set -w option.

[ pid ] ::attach [ core | pid ] [ pid ] :A [ core | pid ] If the user process target is active, attach to and

debug the specified process-ID or core file. The core

file pathname should be specified as a string argument.

The process-ID can be specified as the string argument,

or as the value of the expression preceding the dcmd. Recall that the default base is hexadecimal, so decimal PIDs obtained using pgrep(1) or ps(1) should be preceded with "0t" when specified as expressions.

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

address :b [cmd ...] Set a breakpoint at the specified locations. The ::bp

dcmd sets a breakpoint at each address or symbol speci-

fied, including an optional address specified by an explicit expression preceding the dcmd, and each string or immediate value following the dcmd. The arguments can either be symbol names or immediate values denoting a particular virtual address of interest. If a symbol name is specified, it can refer to a symbol that cannot yet

be evaluated in the target process. That is, it can con-

sist of an object name and function name in a load object that has not yet been opened. In this case, the breakpoint is deferred and is not active in the target until an object matching the given name is loaded. The breakpoint is automatically enabled when the load object is opened. Breakpoints on symbols defined in a shared library should always be set using a symbol name and not using an address expression, as the address can refer to the corresponding Procedure Linkage Table (PLT) entry instead of the actual symbol definition. Breakpoints set

on PLT entries can be overwritten by the run-time link-

editor when the PLT entry is subsequently resolved to

the actual symbol definition. The -d, -D, -e, -s, -t,

-T, -c, and -n options have the same meaning as they do

for the ::evset dcmd, as described below. If the :b form

SunOS 5.11 Last change: 14 Aug 2009 28

User Commands mdb(1)

of the dcmd is used, a breakpoint is only set at the virtual address specified by the expression preceding

the dcmd. The arguments following the :b dcmd are con-

catenated together to form the callback string. If this

string contains meta-characters, it must be quoted.

::cat filename ... Concatenate and display files. Each filename can be specified as a relative or absolute pathname. The file contents are printed to standard output, but are not passed to the output pager. This dcmd is intended to be used with the | operator; the programmer can initiate a pipeline using a list of addresses stored in an external file. ::cont [ SIG ] :c [ SIG ] Suspend the debugger, continue the target program, and wait for it to terminate or stop following a software event of interest. If the target is already running because the debugger was attached to a running program

with the -o nostop option enabled, this dcmd simply

waits for the target to terminate or stop after an event of interest. If an optional signal name or number (see signal.h(3HEAD)) is specified as an argument, the signal

is immediately delivered to the target as part of resum-

ing its execution. If the SIGINT signal is traced, con-

trol can be asynchronously returned to the debugger by

typing the user-defined interrupt character (usually

^C). This SIGINT signal is automatically cleared and is

not observed by the target the next time it is contin-

ued. If no target program is currently running, ::cont starts a new program running as if by ::run. address ::context

address $p

Context switch to the specified process. A context switch operation is only valid when using the kernel target. The process context is specified using the address of its proc structure in the kernel's virtual address space. The special context address "0" is used

to denote the context of the kernel itself. mdb can only

perform a context switch when examining a crash dump if the dump contains the physical memory pages of the specified user process (as opposed to just kernel pages). The kernel crash dump facility can be configured

SunOS 5.11 Last change: 14 Aug 2009 29

User Commands mdb(1)

to dump all pages or the pages of the current user pro-

cess using dumpadm(1M). The ::status dcmd can be used to display the contents of the current crash dump. When the user requests a context switch from the kernel

target, mdb constructs a new target representing the

specified user process. Once the switch occurs, the new target interposes its dcmds at the global level: thus

the / dcmd now formats and displays data from the vir-

tual address space of the user process, the ::mappings dcmd displays the mappings in the address space of the user process, and so on. The kernel target can be restored by executing 0::context. ::dcmds List the available dcmds and print a brief description for each one. [ address ] ::delete [ id | all ] [ address ] :d [ id | all ] Delete the event specifiers with the given id number. The id number argument is interpreted in decimal by default. If an optional address is specified preceding the dcmd, all event specifiers that are associated with the given virtual address are deleted (for example, all breakpoints or watchpoints affecting that address). If

the special argument "all" is given, all event specif-

iers are deleted, except those that are marked sticky (T flag). The ::events dcmd displays the current list of event specifiers.

[ address ] ::dis [ -fw ] [ -n count ] [ address ]

Disassemble starting at or around the address specified by the final argument, or the current value of dot. If the address matches the start of a known function, the entire function is disassembled. Otherwise, a "window" of instructions before and after the specified address is printed in order to provide context. By default, instructions are read from the target's virtual address

space. If the -f option is present, instructions are

read from the target's object file instead. The -f

option is enabled by default if the debugger is not currently attached to a live process, core file, or

crash dump. The -w option can be used to force

"window"-mode, even if the address is the start of a

known function. The size of the window defaults to ten

SunOS 5.11 Last change: 14 Aug 2009 30

User Commands mdb(1)

instructions; the number of instructions can be speci-

fied explicitly using the -n option.

::disasms List the available disassembler modes. When a target is

initialized, mdb attempts to select the appropriate

disassembler mode. The user can change the mode to any of the modes listed using the ::dismode dcmd. ::dismode [ mode ]

$V [ mode ]

Get or set the disassembler mode. If no argument is specified, print the current disassembler mode. If a mode argument is specified, switch the disassembler to the specified mode. The list of available disassemblers can be displayed using the ::disasms dcmd.

::dmods [ -l ] [ module-name ]

List the loaded debugger modules. If the -l option is

specified, the list of the dcmds and walkers associated with each dmod is printed below its name. The output can be restricted to a particular dmod by specifying its name as an additional argument.

[ address ] ::dump [ -eqrstu ] [ -f|-p ]

[ -g bytes ] [ -w paragraphs ]

Print a hexadecimal and ASCII memory dump of the 16-byte

aligned region of memory containing the address speci-

fied by dot. If a repeat count is specified for ::dump, this is interpreted as a number of bytes to dump rather

than a number of iterations. The ::dump dcmd also recog-

nizes the following options:

-e

Adjusts for endian-ness. The -e option assumes 4-

byte words. The -g option can be used to change the

default word size.

-f

Reads data from the object file location correspond-

ing to the given virtual address instead of from the

SunOS 5.11 Last change: 14 Aug 2009 31

User Commands mdb(1)

target's virtual address space. The -f option is

enabled by default if the debugger is not currently attached to a live process, core file, or crash dump.

-g bytes

Displays bytes in groups of bytes. The default group size is 4 bytes. The group size must be a power of two that divides the line width.

-p

Interprets address as a physical address location in the target's address space instead of a virtual address.

-q

Does not print an ASCII decoding of the data.

-r

Numbers lines relative to the start address instead of with the explicit address of each line. This

option implies the -u option.

-s

Elides repeated lines.

-t

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

-u

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

-w paragraphs

SunOS 5.11 Last change: 14 Aug 2009 32

User Commands mdb(1)

Displays paragraphs at 16-byte paragraphs per line.

The default number of paragraphs is one. The maximum

value accepted for -w is 16.

::echo [ string | value ...] Print the arguments separated by blanks and terminated by a NEWLINE to standard output. Expressions enclosed in

$[ ] is evaluated to a value and printed in the default

base. ::eval command Evaluate and execute the specified string as a command. If the command contains metacharacters or whitespace, it should be enclosed in double or single quotes.

::events [ -av ]

$b [ -av ]

Display the list of software event specifiers. Each event specifier is assigned a unique ID number that can be used to delete or modify it at a later time. The debugger can also have its own internal events enabled for tracing. These events are only be displayed if the

-a option is present. If the -v option is present, a

more verbose display, including the reason for any specifier inactivity, are shown. Here is some sample output: > ::events ID S TA HT LM Description Action

----- - -- -- -- -------------------------------- ------

[ 1 ] - T 1 0 stop on SIGINT -

[ 2 ] - T 0 0 stop on SIGQUIT -

[ 3 ] - T 0 0 stop on SIGILL -

...

[ 11] - T 0 0 stop on SIGXCPU -

[ 12] - T 0 0 stop on SIGXFSZ -

[ 13] - 2 0 stop at libc`printf ::echo printf

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

SunOS 5.11 Last change: 14 Aug 2009 33

User Commands mdb(1)

ID The event specifier identifier. The identifier is shown in square brackets [ ] if the specifier is

enabled, in parentheses ( ) if the specifier is dis-

abled, or in angle brackets < > if the target pro-

gram is currently stopped on an event that matches the given specifier. S The event specifier state. The state is one of the following symbols:

The event specifier is idle. When no target pro-

gram is running, all specifiers are idle. When the target program is running, a specifier can be idle if it cannot be evaluated (for example, a deferred breakpoint in a shared object that is not yet loaded). + The event specifier is active. When the target is continued, events of this type is detected by the debugger. * The event specifier is armed. This state means that the target is currently running with instrumentation for this type of event. This state is only visible if the debugger is

attached to a running program with the -o nostop

option. ! The event specifier was not armed due to an

operating system error. The ::events -v option

can be used to display more information about the reason the instrumentation failed.

SunOS 5.11 Last change: 14 Aug 2009 34

User Commands mdb(1)

TA The Temporary, Sticky, and Automatic event specifier properties. One or more of the following symbols can be shown: t The event specifier is temporary, and is deleted the next time the target stops, regardless of whether it is matched. T The event specifier is sticky, and is not be deleted by ::delete all or :z. The specifier can be deleted by explicitly specifying its id number to ::delete. d The event specifier is automatically disabled when the hit count is equal to the hit limit. D The event specifier is automatically deleted when the hit count is equal to the hit limit. s The target automatically stops when the hit count is equal to the hit limit. HT The current hit count. This column displays the number of times the corresponding software event has occurred in the target since the creation of this event specifier. LM The current hit limit. This column displays the

limit on the hit count at which the auto-disable,

SunOS 5.11 Last change: 14 Aug 2009 35

User Commands mdb(1)

auto-delete, or auto-stop behavior takes effect.

These behaviors can be configured using the ::evset dcmd, described below. Description A description of the type of software event that is matched by the given specifier. Action

The callback string to execute when the correspond-

ing software event occurs. This callback is executed as if it had been typed at the command prompt.

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

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

-d

Disables the event specifier when the hit count

reaches the hit limit. If the -d form of the option

is given, this behavior is disabled. Once an event specifier is disabled, the debugger removes any corresponding instrumentation and ignores the corresponding software events until the specifier is

subsequently re-enabled. If the -n option is not

present, the specifier is disabled immediately.

-D

Deletes the event specifier when the hit count

reaches the hit limit. If the -D form of the option

is given, this behavior is disabled. The -D option

takes precedence over the -d option. The hit limit

can be configured using the -n option.

-e

SunOS 5.11 Last change: 14 Aug 2009 36

User Commands mdb(1)

Enables the event specifier. If the -e form of the

option is given, the specifier is disabled.

-s

Stops the target program when the hit count reaches

the hit limit. If the -s form of the option is

given, this behavior is disabled. The -s behavior

tells the debugger to act as if the ::cont were issued following each execution of the specifier's callback, except for the Nth execution, where N is the current value of the specifier's hit limit. The

-s option takes precedence over both the -D option

and the -d option.

-t

Marks the event specifier as temporary. Temporary specifiers are automatically deleted the next time the target stops, regardless of whether it stopped as the result of a software event corresponding to

the given specifier. If the -t form of the option is

given, the temporary marker is removed. The -t

option takes precedence over the -T option.

-T

Marks the event specifier as sticky. Sticky specif-

iers are not deleted by ::delete all or :z. They can be deleted by specifying the corresponding specifier

ID as an explicit argument to ::delete. If the -T

form of the option is given, the sticky property is removed. The default set of event specifiers are all initially marked sticky.

-c

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

-n

Sets the current value of the hit limit to count. If

no hit limit is currently set and the -n option does

not accompany -s or D, the hit limit is set to one.

SunOS 5.11 Last change: 14 Aug 2009 37

User Commands mdb(1)

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

Print a list of the known source files (symbols of type

STT_FILE present in the various target symbol tables).

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

Trace the specified machine faults. The faults are iden-

tified using an optional fault number preceding the dcmd, or a list of fault names or numbers (see

) following the dcmd. The -d, -D, -e, -s,

-t, -T, -c, and -n options have the same meaning as they

do for the ::evset dcmd. [ thread ] ::fpregs

[ thread ] $x, $X, $y, $Y

Print the floating-point register set of the representa-

tive thread. If a thread is specified, the floating point registers of that thread are displayed. The thread expression should be one of the thread identifiers described under Thread Support, above. ::formats List the available output format characters for use with the /, \, ?, and = formatting dcmds. The formats and their use is described under Formatting dcmds, above. ::grep command Evaluate the specified command string, and then print

the old value of dot if the new value of dot is non-

zero. If the command contains whitespace or metacharac-

ters, it must be quoted. The ::grep dcmd can be used in pipelines to filter a list of addresses.

::help [ dcmd-name ]

With no arguments, the ::help dcmd prints a brief over-

view of the help facilities available in mdb. If a

dcmd-name is specified, mdb prints a usage summary for

SunOS 5.11 Last change: 14 Aug 2009 38

User Commands mdb(1)

that dcmd. signal :i

If the target is a live user process, ignore the speci-

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

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

Forcibly terminate the target if it is a live user pro-

cess. The target is also forcibly terminated when the debugger exits if it was created by the debugger using ::run.

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

Print the LWPIDs of each LWP in the target, if the tar-

get is a user process.

[ address ] ::list type member [ variable-name ]

Walk through the elements of a linked list data struc-

ture and print the address of each element in the list. The address of the first element in the list can be specified using an optional address. Otherwise, the list is assumed to start at the current value of dot. The

SunOS 5.11 Last change: 14 Aug 2009 39

User Commands mdb(1)

type parameter must name a C struct or union type and is used to describe the type of the list elements so that

mdb can read in objects of the appropriate size. The

member parameter is used to name the member of type that contains a pointer to the next list element. The ::list

dcmd continues iterating until a NULL pointer is encoun-

tered, the first element is reached again (a circular list), or an error occurs while reading an element. If

the optional variable-name is specified, the specified

variable is assigned the value returned at each step of

the walk when mdb invokes the next stage of a pipeline.

The ::list dcmd can only be used with objects that con-

tain symbolic debugging information designed for use

with mdb. Refer to NOTES, Symbolic Debugging Informa-

tion, below for more information.

::load [ -s ] module-name

Load the specified dmod. The module name can be given as

an absolute or relative path. If module-name is a simple

name (that is, does not contain a '/'), mdb searches for

it in the module library path. Modules with conflicting names can not be loaded; the existing module must be

unloaded first. If the -s option is present, mdb remains

silent and not issue any error messages if the module is not found or could not be loaded.

::log [ -d | [ -e ] filename ]

$> [ filename ]

Enable or disable the output log. mdb provides an

interactive logging facility where both the input com-

mands and standard output can be logged to a file while

still interacting with the user. The -e option enables

logging to the specified file, or re-enables logging to

the previous log file if no filename is given. The -d

option disables logging. If the $> dcmd is used, logging

is enabled if a filename argument is specified; other-

wise, logging is disabled. If the specified log file

already exists, mdb appends any new log output to the

file. ::map command Map the value of dot to a corresponding value using the command specified as a string argument, and then print the new value of dot. If the command contains whitespace or metacharacters, it must be quoted. The ::map dcmd can be used in pipelines to transform the list of addresses

SunOS 5.11 Last change: 14 Aug 2009 40

User Commands mdb(1)

into a new list of addresses. [ address ] ::mappings [ name ]

[ address ] $m [ name ]

Print a list of each mapping in the target's virtual

address space, including the address, size, and descrip-

tion of each mapping. If the dcmd is preceded by an

address, mdb only shows the mapping that contains the

given address. If a string name argument is given, mdb

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

[ address ] ::nm [ -DPdghnopuvx ] [ -t types ]

[ -f format ] [ object ]

Print the symbol tables associated with the current tar-

get. If an optional address preceding the dcmd is speci-

fied, only the symbol table entry for the symbol corresponding to address is displayed. If an object is specified, only the symbol table for this load object is displayed. The ::nm dcmd also recognizes the following options:

-D

Prints .dynsym (dynamic symbol table) instead of .symtab.

-P

Prints the private symbol table instead of .symtab.

-d

Prints value and size fields in decimal.

SunOS 5.11 Last change: 14 Aug 2009 41

User Commands mdb(1)

-g

Prints only global symbols.

-h

Suppresses the header line.

-n

Sorts symbols by name.

-o

Prints value and size fields in octal.

-p

Prints symbols as a series of ::nmadd commands. This

option can be used with -P to produce a macro file

that can be subsequently read into the debugger with

$<.

-u

Prints only undefined symbols.

-v

Sorts symbols by value.

-x

Prints value and size fields in hexadecimal.

-t type[,type ... ]

Prints only symbols of the specified type(s). The valid type argument strings are: noty

STT_NOTYPE

SunOS 5.11 Last change: 14 Aug 2009 42

User Commands mdb(1)

objt

STT_OBJECT

func

STT_FUNC

sect

STT_SECTION

file

STT_FILE

comm

STT_COMMON

tls

STT_TLS

regi

STT_SPARC_REGISTER

-f format[,format ... ]

Prints only the specified symbol information. The valid format argument strings are: ndx symbol table index val symbol value

SunOS 5.11 Last change: 14 Aug 2009 43

User Commands mdb(1)

size size in bytes type symbol type bind binding oth other shndx section index name symbol name ctype C type for symbol (if known) obj object which defines symbol

value ::nmadd [ -fo ] [ -e end ] [ -s size ] name

Add the specified symbol name to the private symbol

table. mdb provides a private, configurable symbol table

that can be used to interpose on the target's symbol table, as described under Symbol Name Resolution above. The ::nmadd dcmd also recognizes the following options:

-e

SunOS 5.11 Last change: 14 Aug 2009 44

User Commands mdb(1)

Sets the size of the symbol to end - value.

-f

Sets the type of the symbol to STT_FUNC.

-o

Sets the type of the symbol to STT_OBJECT.

-s

Sets the size of the symbol to size. ::nmdel name Delete the specified symbol name from the private symbol table.

::objects [ -v ]

Print a map of the target's virtual address space, show-

ing only those mappings that correspond to the primary mapping (usually the text section) of each of the known

load objects. The -v option displays the version of each

load object. Version information is not available for

all load objects. Load objects without version informa-

tion is listed as having a version of "Unknown" in the

output for the -v option.

::offsetof type member

Print the offset of the specified member of the speci-

fied type. The type should be the name of a C structure. The offset is printed in bytes, unless the member is a

bit-field, in which case the offset can be printed in

bits. The output is always suffixed with the appropriate units for clarity. The type name can use the backquote

(`) scoping operator described under Symbol Name Resolu-

tion, above. The ::offsetof dcmd can only be used with objects that contain symbolic debugging information

designed for use with mdb. Refer to NOTES, Symbolic

Debugging Information, below for more information.

SunOS 5.11 Last change: 14 Aug 2009 45

User Commands mdb(1)

address ::print [ -aCdiLptx ] [ -c lim ]

[ -l lim ] [ type [ member ... ] ]

Print the data structure at the specified virtual address using the given type information. The type parameter can name a C struct, union, enum, fundamental integer type, or a pointer to any of these types. If the type name contains whitespace (for example, "struct foo"), it must be enclosed in single or double quotes. The type name can use the backquote (`) scoping operator described under Symbol Name Resolution, above. If the type is a structured type, the ::print dcmd recursively prints each member of the struct or union. If the type argument is not present and a static or global

STT_OBJECT symbol matches the address, ::print infers

the appropriate type automatically. If the type argument is specified, it can be followed by an optional list of member expressions, in which case only those members and submembers of the specified type are displayed. If type contains other structured types, each member string can

refer to a sub-structure element by forming a list of

member names separated by period ('.') delimiters. The ::print dcmd can only be used with objects that contain symbolic debugging information designed for use with

mdb. Refer to NOTES, Symbolic Debugging Information,

below for more information. After displaying the data structure, ::print increments dot by the size of type in bytes.

If the -a option is present, the address of each member

is displayed. If the -p option is present, ::print

interprets address as a physical memory address instead

of a virtual memory address. If the -t option is

present, the type of each member is displayed. If the -d

or -x options are present, all integers are displayed in

decimal (-d) or hexadecimal (-x). By default, a heuris-

tic is used to determine if the value should be

displayed in decimal or hexadecimal. The number of char-

acters in a character array that is read and displayed

as a string can be limited with the -c option. If the -C

option is present, no limit is enforced. The number of elements in a standard array that is read and displayed

can be limited with the -l option. If the -L option is

present, no limit is enforced and all array elements are

shown. The default values for -c and -l can be modified

using ::set or the -o command-line option as described

under OPTIONS.

If the -i option is specified, the address value is

interpreted as an immediate value to be printed. You must give a type with which to interpret the value. If the type is smaller than 64 bits, the immediate value is

SunOS 5.11 Last change: 14 Aug 2009 46

User Commands mdb(1)

interpreted as if it were the size of the type. The -i

option cannot be used in conjunction with the -p option.

If the -a option is given, the addresses shown are byte

offsets starting at zero. ::quit

Quit the debugger. [ thread ] ::regs

[ thread ] $r

Print the general purpose register set of the represen-

tative thread. If a thread is specified, the general purpose register set of that thread is displayed. The

thread expression should be one of the thread identif-

iers described under Thread Support, above.

::release [ -a ]

:R [ -a ]

Release the previously attached process or core file. If

the -a option is present, the process is released and

left stopped and abandoned. It can subsequently be con-

tinued by prun(1) (see proc(1)) or it can be resumed by

applying mdb or another debugger. By default, a released

process is forcibly terminated if it was created by mdb

using ::run, or it is released and set running if it was

attached to by mdb using the -p option or using the

::attach or :A dcmds. ::run [ args . . . ] :r [ args . . . ] Start a new target program running with the specified

arguments and attach to it. The arguments are not inter-

preted by the shell. If the debugger is already examin-

ing a live running program, it first detaches from this program as if by ::release.

::set [ -wF ] [ -/-o option ] [ -s distance ] [ -I path ]

[ -L path ] [ -P prompt ]

Get or set miscellaneous debugger properties. If no

options are specified, the current set of debugger pro-

perties is displayed. The ::set dcmd recognizes the

SunOS 5.11 Last change: 14 Aug 2009 47

User Commands mdb(1)

following options:

-F

Forcibly takes over the next user process that

::attach is applied to, as if mdb had been executed

with the -F option on the command line.

-I

Sets the default path for locating macro files. The path argument can contain any of the special tokens

described for the -I command-line option under

OPTIONS.

-L

Sets the default path for locating debugger modules. The path argument can contain any of the special

tokens described for the -I command-line option

under OPTIONS.

-o

Enables the specified debugger option. If the -o

form is used, the option is disabled. The option

strings are described along with the -o command-line

option under OPTIONS.

-P

Sets the command prompt to the specified prompt string.

-s

Sets the symbol matching distance to the specified

distance. Refer to the description of the -s

command-line option under OPTIONS for more informa-

tion.

-w

Re-opens the target for writing, as if mdb had been

executed with the -w option on the command line.

SunOS 5.11 Last change: 14 Aug 2009 48

User Commands mdb(1)

::showrev [ -pv ]

Display revision information for the hardware and software. With no options specified, general system

information is displayed. The -v option displays version

information for all load objects, whereas the -p option

displays the version information only for the load objects that have been installed on the system as part of a patch. Version information is not available for all load objects. Load objects without version information

is omitted from the output for the -p option and is

listed as having a version of "Unknown" in the output

for the -v option.

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

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

Trace delivery of the specified signals. The signals are identified using an optional signal number preceding the dcmd, or a list of signal names or numbers (see

signal.h(3HEAD)) following the dcmd. The -d, -D, -e, -s,

-t, -T, -c, and -n options have the same meaning as they

do for the ::evset dcmd. Initially, the set of signals that cause the process to dump core by default (see signal.h(3HEAD)) and SIGINT are traced. ::sizeof type Print the size of the specified type in bytes. The type parameter can name a C struct, union, enum, fundamental integer type, or a pointer to any of these types. The type name can use the backquote (`) scoping operator described under Symbol Name Resolution, above. The ::sizeof dcmd can only be used with objects that contain symbolic debugging information designed for use with

mdb. Refer to NOTES, Symbolic Debugging Information,

below for more information. [ address ] ::stack [ count ]

[ address ] $c [ count ]

Print a C stack backtrace. If the dcmd is preceded by an explicit address, a backtrace beginning at this virtual memory address is displayed. Otherwise the stack of the representative thread is displayed. If an optional count

value is given as an argument, no more than count argu-

ments are displayed for each stack frame in the output.

SunOS 5.11 Last change: 14 Aug 2009 49

User Commands mdb(1)

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

[ syscall ] ::sysbp [ -/-dDestT ] [ -io ] [ -c cmd ]

[ -n count ] syscall...

Trace entry to or exit from the specified system calls. The system calls are identified using an optional system call number preceding the dcmd, or a list of system call names or numbers (see ) following the

dcmd. If the -i option is specified (the default), the

event specifiers trigger on entry into the kernel for

each system call. If the -o option is specified, the

event specifiers trigger on exit out from the kernel.

The -d, -D, -e, -s, -t, -T, -c, and -n options have the

same meaning as they do for the ::evset dcmd. thread ::tls symbol Print the address of the storage for the specified

thread-local storage (TLS) symbol in the context of the

specified thread. The thread expression should be one of the thread identifiers described under Thread Support,

above. The symbol name can use any of the scoping opera-

tors described under Symbol Name Resolution, above.

::typeset [ -/-t] variable-name . . .

SunOS 5.11 Last change: 14 Aug 2009 50

User Commands mdb(1)

Set attributes for named variables. If one or more vari-

able names are specified, they are defined and set to

the value of dot. If the -t option is present, the

user-defined tag associated with each variable is set.

If the -t option is present, the tag is cleared. If no

variable names are specified, the list of variables and their values is printed.

::unload module-name

Unload the specified dmod. The list of active dmods can

be printed using the ::dmods dcmd. Built-in modules can

not be unloaded. Modules that are busy (that is, provide dcmds that are currently executing) can not be unloaded.

::unset variable-name . . .

Unset (remove) the specified variable(s) from the list

of defined variables. Some variables exported by mdb are

marked as persistent, and can not be unset by the user.

::vars [-npt]

Print a listing of named variables. If the -n option is

present, the output is restricted to variables that

currently have non-zero values. If the -p option is

present, the variables are printed in a form suitable

for re-processing by the debugger using the $< dcmd.

This option can be used to record the variables to a macro file and then restore these values later. If the

-t option is present, only the tagged variables are

printed. Variables can be tagged using the -t option of

the ::typeset dcmd. ::version Print the debugger version number.

address ::vtop [-a as]

Print the physical address mapping for the specified virtual address, if possible. The ::vtop dcmd is only

available when examining a kernel target, or when exa-

mining a user process inside a kernel crash dump (after a ::context dcmd has been issued). When examining a kernel target from the kernel context,

SunOS 5.11 Last change: 14 Aug 2009 51

User Commands mdb(1)

the -a option can be used to specify the address (as) of

an alternate address space structure that should be used for the virtual to physical translation. By default, the kernel's address space is used for translation. This option is available for active address spaces even when the dump content only contains kernel pages.

[ address ] ::walk walker-name [ variable-name ]

Walk through the elements of a data structure using the specified walker. The available walkers can be listed

using the ::walkers dcmd. Some walkers operate on a glo-

bal data structure and do not require a starting address. For example, walk the list of proc structures in the kernel. Other walkers operate on a specific data structure whose address must be specified explicitly. For example, given a pointer to an address space, walk the list of segments. When used interactively, the ::walk dcmd prints the address of each element of the data structure in the default base. The dcmd can also be used to provide a list of addresses for a pipeline. The walker name can use the backquote (`) scoping operator described under dcmd and Walker Name Resolution, above.

If the optional variable-name is specified, the speci-

fied variable is assigned the value returned at each

step of the walk when mdb invokes the next stage of the

pipeline. ::walkers List the available walkers and print a brief description for each one.

::whence [ -v ] name . . .

::which [ -v ] name ...

Print the dmod that exports the specified dcmds and walkers. These dcmds can be used to determine which dmod is currently providing the global definition of the given dcmd or walker. Refer to the section on dcmd and Walker Name Resolution above for more information on

global name resolution. The -v option causes the dcmd to

print the alternate definitions of each dcmd and walker in order of precedence.

addr [ ,len ]::wp [ -/-dDestT ] [ -rwx ] [ -c cmd ]

[ -n count ]

addr [ ,len ] :a [ cmd . . . ]

SunOS 5.11 Last change: 14 Aug 2009 52

User Commands mdb(1)

addr [ ,len ] :p [ cmd . . . ] addr [ ,len ] :w [ cmd . . . ] Set a watchpoint at the specified address. The length in bytes of the watched region can be set by specifying an optional repeat count preceding the dcmd. If no length is explicitly set, the default is one byte. The ::wp dcmd allows the watchpoint to be configured to trigger

on any combination of read (-r option), write (-w

option), or execute (-x option) access. The -d, -D, -e,

-s, -t, -T, -c, and -n options have the same meaning as

they do for the ::evset dcmd. The :a dcmd sets a read access watchpoint at the specified address. The :p dcmd sets an execute access watchpoint at the specified address. The :w dcmd sets a write access watchpoint at the specified address. The arguments following the :a, :p, and :w dcmds are concatenated together to form the

callback string. If this string contains meta-

characters, it must be quoted. ::xdata List the external data buffers exported by the current target. External data buffers represent information associated with the target that can not be accessed through standard target facilities (that is, an address space, symbol table, or register set). These buffers can be consumed by dcmds; for more information, refer to the Oracle Solaris Modular Debugger Guide. :z Delete all event specifiers from the list of traced software events. Event specifiers can also be deleted using ::delete. OPTIONS The following options are supported:

-A

Disables automatic loading of mdb modules. By default,

mdb attempts to load debugger modules corresponding to

the active shared 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.

SunOS 5.11 Last change: 14 Aug 2009 53

User Commands mdb(1)

-f

Forces raw file debugging mode. By default, mdb attempts

to infer whether the object and core file operands refer to a user executable and core dump or to a pair of

operating system crash dump files. If the file type can-

not be inferred, the debugger defaults to examining the

files as plain binary data. The -f option forces mdb to

interpret the arguments as a set of raw files to exam-

ine.

-F

Forcibly takes over the specified user process, if

necessary. By default, mdb refuses to attach to a user

process that is already under the control of another

debugging tool, such as truss(1). With the -F option,

mdb attaches to these processes anyway. This can produce

unexpected interactions between mdb and the other tools

attempting to control the process.

-I path

Sets default path for locating macro files. Macro files

are read using the $< or $<< dcmds. The path is a

sequence of directory names delimited by colon (:) char-

acters. The -I include path and -L library path (see

below) can also contain any of the following tokens:

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

Expands to the old value of the path being modified.

This is useful for appending or prepending direc-

tories to an existing path.

Expands to the current platform string (either uname

-i or the platform string stored in the process core

file or crash dump).

SunOS 5.11 Last change: 14 Aug 2009 54

User Commands mdb(1)

Expands to the pathname of the root directory. An alternate root directory can be specified using the

-R option. If no -R option is present, the root

directory is derived dynamically from the path to

the mdb executable itself. For example, if /bin/mdb

is executed, the root directory is /. If

/net/hostname/bin/mdb were executed, the root direc-

tory would be derived as /net/hostname.

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

The default include path for 32-bit mdb is:

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

The default include path for 64-bit mdb is:

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

-k

Forces kernel debugging mode. By default, mdb attempts

to infer whether the object and core file operands refer to a user executable and core dump, or to a pair of

operating system crash dump files. The -k option forces

mdb to assume these files are operating system crash

dump files. If no object or core operand is specified,

but the -k option is specified, mdb defaults to an

object file of /dev/ksyms and a core file of /dev/kmem. Read access to /dev/kmem is restricted to group sys. Write access requires ALL privileges.

-K

Load kmdb, stop the live running operating system ker-

nel, and proceed to the kmdb debugger prompt. This

option should only be used on the system console, as the

subsequent kmdb prompt appears on the system console.

SunOS 5.11 Last change: 14 Aug 2009 55

User Commands mdb(1)

-L path

Sets default path for locating debugger modules. Modules are loaded automatically on startup or using the ::load

dcmd. The path is a sequence of directory names delim-

ited by colon (:) characters. The -L library path can

also contain any of the tokens shown for -I above.

-m

Disables demand-loading of kernel module symbols. By

default, mdb processes the list of loaded kernel modules

and performs demand loading of per-module symbol tables.

If the -m option is specified, mdb does not attempt to

process the kernel module list or provide per-module

symbol tables. As a result, mdb modules corresponding to

active kernel modules are not loaded on startup.

-M

Preloads all kernel module symbols. By default, mdb per-

forms demand-loading for kernel module symbols: the com-

plete symbol table for a module is read when an address is that module's text or data section is referenced.

With the -M option, mdb loads the complete symbol table

of all kernel modules during startup.

-o option

Enables the specified debugger option. If the -o form of

the option is used, the specified option is disabled.

Unless noted below, each option is off by default. mdb

recognizes the following option arguments: adb Enables stricter adb(1) compatibility. The prompt is

set to the empty string and many mdb features, such

as the output pager, is disabled.

array_mem_limit=limit

Sets the default limit on the number of array

members that ::print displays. If limit is the spe-

cial token none, all array members are displayed by default.

SunOS 5.11 Last change: 14 Aug 2009 56

User Commands mdb(1)

array_str_limit=limit

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

follow_exec_mode=mode

Sets the debugger behavior for following an exec(2) system call. The mode should be one of the following named constants: ask If stdout is a terminal device, the debugger stops after the exec(2) system call has returned and then prompts the user to decide whether to

follow the exec or stop. If stdout is not a ter-

minal device, the ask mode defaults to stop. follow The debugger follows the exec by automatically continuing the target process and resetting all of its mappings and symbol tables based on the new executable. The follow behavior is discussed in more detail under NOTES, Interaction with Exec, below. stop The debugger stops following return from the exec system call. The stop behavior is discussed in more detail under NOTES, Interaction with Exec, below.

follow_fork_mode=mode

Sets the debugger behavior for following a fork(2), fork1(2), or vfork(2) system call. The mode should be one of the following named constants: ask If stdout is a terminal device, the debugger

SunOS 5.11 Last change: 14 Aug 2009 57

User Commands mdb(1)

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

detaches from the child process and sets it run-

ning. child The debugger follows the child process, and detaches from the parent process and sets it running. ignoreeof The debugger does not exit when an EOF sequence (^D) is entered at the terminal. The ::quit dcmd must be used to quit. nostop Does not stop a user process when attaching to it

when the -p option is specified or when the ::attach

or :A dcmds are applied. The nostop behavior is described in more detail under NOTES, Process Attach and Release, below. pager Enables the output pager (default). repeatlast If a NEWLINE is entered as the complete command at

the terminal, mdb repeats the previous command with

the current value of dot. This option is implied by

-o adb.

SunOS 5.11 Last change: 14 Aug 2009 58

User Commands mdb(1)

showlmid

mdb provides support for symbol naming and identifi-

cation in user applications that make use of link

maps other than LM_ID_BASE and LM_ID_LDSO, as

described in Symbol Name Resolution, above. Symbols

on link maps other than LM_ID_BASE or LM_ID_LDSO is

shown as LMlmid`library`symbol, where lmid is the

link-map ID in the default output radix (16). The

user can optionally configure mdb to show the link-

map ID scope of all symbols and objects, including

those associated with LM_ID_BASE and LM_ID_LDSO, by

enabling the showlmid option. Built-in dcmds that

deal with object file names displays link-map IDs

according to the value of showlmid above, including

::nm, ::mappings, $m, and ::objects.

-p pid

Attaches to and stops the specified process-id. mdb uses

the /proc/pid/object/a.out file as the executable file pathname.

-P prompt

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

-R root

Sets root directory for pathname expansion. By default, the root directory is derived from the pathname of the

mdb executable itself. The root directory is substituted

in place of the %r token during pathname expansion.

-s distance

Sets the symbol matching distance for address-to-

symbol-name conversions to the specified distance. By

default, mdb sets the distance to zero, which enables a

smart-matching mode. Each ELF symbol table entry

includes a value V and size S, representing the size of

the function or data object in bytes. In smart mode, mdb

matches an address A with the given symbol if A is in

the range [ V, V + S ). If any non-zero distance is

specified, the same algorithm is used, but S in the

expression above is always the specified absolute dis-

tance and the symbol size is ignored.

SunOS 5.11 Last change: 14 Aug 2009 59

User Commands mdb(1)

-S

Suppresses processing of the user's ~/.mdbrc file. By

default, mdb reads and processes the macro file .mdbrc

if one is present in the user's home directory, as

defined by $HOME. If the -S option is present, this file

is not read.

-u

Forces user debugging mode. By default, mdb attempts to

infer whether the object and core file operands refer to

a user executable and core dump, or to a pair of operat-

ing system crash dump files. The -u option forces mdb to

assume these files are not operating system crash dump files.

-U

Unload kmdb if it is loaded. You should unload kmdb when

it is not in use to release the memory used by the ker-

nel debugger back to the free memory available to the operating system.

-V version

Sets disassembler version. By default, mdb attempts to

infer the appropriate disassembler version for the debug target. The disassembler can be set explicitly using the

-V option. The ::disasms dcmd lists the available

disassembler versions.

-w

Opens the specified object and core files for writing.

-W

Permit access to memory addresses that are mapped to I/O

devices. By default, mdb does not allow such access

because many devices do not provide hardware protection against invalid software manipulations. Use this option only when debugging device drivers and with caution.

-y

SunOS 5.11 Last change: 14 Aug 2009 60

User Commands mdb(1)

Sends explicit terminal initialization sequences for tty

mode. Some terminals, such as cmdtool(1), require expli-

cit initialization sequences to switch into a tty mode. Without this initialization sequence, terminal features

such as standout mode can not be available to mdb.

OPERANDS The following operands are supported: object

Specifies an ELF format object file to examine. mdb pro-

vides the ability to examine and edit ELF format execut-

ables (ET_EXEC), ELF dynamic library files (ET_DYN), ELF

relocatable object files (ET_REL), and operating system

unix.X symbol table files. core

Specifies an ELF process core file (ET_CORE), or an

operating system crash dump vmcore.X file. If an ELF core file operand is provided without a corresponding

object file, mdb attempts to infer the name of the exe-

cutable file that produced the core using several dif-

ferent algorithms. If no executable is found, mdb still

executes, but some symbol information can be unavail-

able. suffix Specifies the numerical suffix representing a pair of operating system crash dump files. For example, if the

suffix is '3', mdb infers that it should examine the

files 'unix.3' and 'vmcore.3'. If these files do not exist, but 'vmdump.3' does exist, then a message is

printed indicating that savecore -f vmdump.3 must be run

first in order to uncompress the dump file. The string of digits are not interpreted as a suffix if an actual

file of the same name is present in the current direc-

tory.

USAGE

mdb processes all input files (including scripts, object

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

SunOS 5.11 Last change: 14 Aug 2009 61

User Commands mdb(1)

EXIT STATUS The following exit values are returned: 0 Debugger completed execution successfully. 1 A fatal error occurred. 2 Invalid command line options were specified. ENVIRONMENT VARIABLES HISTSIZE This variable is used to determine the maximum length of the command history list. If this variable is not present, the default length is 128. HOME This variable is used to determine the pathname of the

user's home directory, where a .mdbrc file can reside.

If this variable is not present, no .mdbrc processing

occurs. SHELL This variable is used to determine the pathname of the shell used to process shell escapes requested using the

! meta-character. If this variable is not present,

/bin/sh is used. FILES

$HOME/.mdbrc

User mdb initialization file. The .mdbrc file, if

present, is processed after the debug target has been

initialized, but before module auto-loading is performed

or any commands have been read from standard input.

SunOS 5.11 Last change: 14 Aug 2009 62

User Commands mdb(1)

/dev/kmem Kernel virtual memory image device. This device special file is used as the core file when examining the live operating system. /dev/ksyms Kernel symbol table device. This device special file is

used as the object file when examining the live operat-

ing system. /proc/pid/* Process information files that are read when examining and controlling user processes. /usr/lib/adb

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

Default directories for macro files that are read with

the $< and $<< dcmds. platform-name is the name of the

platform, derived either from information in a core file or crash dump, or from the current machine as if by

uname -i (see uname(1)).

/usr/lib/mdb

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

Default directories for debugger modules that are loaded

using the ::load dcmd. platform-name is the name of the

platform, derived either from information in a core file or crash dump, or from the current machine as if by

uname -i (see uname(1)).

ATTRIBUTES

See attributes(5) for descriptions of the following attri-

butes:

SunOS 5.11 Last change: 14 Aug 2009 63

User Commands mdb(1)

____________________________________________________________

| ATTRIBUTE TYPE | ATTRIBUTE VALUE |

|_____________________________|_____________________________|

| Availability | developer/debug/mdb |

|_____________________________|_____________________________|

| Interface Stability | Committed |

|_____________________________|_____________________________|

cause mdb to dump core or otherwise misbehave. The mdb

resume capability, described above under Signal Handling, provides a limited recovery mechanism for these situations.

However, it is not possible for mdb to know definitively

whether the dmod in question has corrupted only its own state, or the debugger's global state. Therefore a resume operation cannot be guaranteed to be safe, or to prevent a subsequent crash of the debugger. The safest course of action following a resume is to save any important debug information, and then quit and restart the debugger. Use of the Debugger to Modify the Live Operating System The use of the debugger to modify (that is, write to) the address space of live running operating system is extremely dangerous, and can result in a system panic in the event the user damages a kernel data structure. NOTES Limitations on Examining Process Core Files

mdb does not provide support for examining process core

files that were generated by a release of Solaris preceding Solaris 2.6. When debugging core files generated by a

release of Solaris 9 or an earlier release, symbol informa-

tion might not be available. Since the text section and

SunOS 5.11 Last change: 14 Aug 2009 64

User Commands mdb(1)

read-only data is not present in those core files, the sym-

bol information might not match the data present in the pro-

cess at the time it dumped core. In releases later than

Solaris 9, text sections and read-only data are included in

core files by default. Users can configure their processes to exclude that information from core files using

coreadm(1M). Thus, the information presented by mdb for

those core files can not match the data that was present at the time the process dumped core. Core files from Solaris x86 systems can not be examined on Solaris SPARC systems,

and vice-versa.

Limitations on Examining Crash Dump Files Crash dumps from Solaris 7 and earlier releases can only be examined with the aid of the libkvm from the corresponding operating system release. If a crash dump from one operating system release is examined using the dmods from a different

operating system release, changes in the kernel implementa-

tion can prevent some dcmds or walkers from working prop-

erly. mdb issues a warning message if it detects this condi-

tion. Crash dumps from Solaris x86 systems can not be exam-

ined on Solaris SPARC systems, and vice-versa.

Relationship Between 32-bit and 64-bit Debugger

mdb provides support for debugging both 32-bit and 64-bit

programs. Once it has examined the target and determined its

data model, mdb automatically re-executes the mdb binary

that has the same data model as the target, if necessary. This approach simplifies the task of writing debugger modules, because the modules that are loaded use the same

data model as the primary target. Only the 64-bit debugger

can be used to debug 64-bit target programs. The 64-bit

debugger can only be used on a system that is running the

64-bit operating environment.

The debugger can also need to re-execute itself when debug-

ging a 32-bit process that execs a 64-bit process, or vice-

versa. The handling of this situation is discussed in more detail under Interaction with Exec, below. Interaction with Exec When a controlled process performs a successful exec(2), the

behavior of the debugger is controlled by the ::set -o

follow_exec_mode option, as described above. If the debugger

and victim process have the same data model, then the "stop"

and "follow" modes determine whether mdb automatically con-

tinues the target or returns to the debugger prompt follow-

ing the exec. If the debugger and victim process have a dif-

ferent data model, then the "follow" behavior causes mdb to

automatically re-exec the mdb binary with the appropriate

data model and to re-attach to the process, still stopped on

SunOS 5.11 Last change: 14 Aug 2009 65

User Commands mdb(1)

return from the exec. Not all debugger state is preserved

across this re-exec.

If a 32-bit victim process execs a 64-bit program, then

"stop" returns to the command prompt, but the debugger is no longer able to examine the process because it is now using

the 64-bit data model. To resume debugging, execute the

::release -a dcmd, quit mdb, and then execute mdb -p pid to

re-attach the 64-bit debugger to the process.

If a 64-bit victim process execs a 32-bit program, then

"stop" returns to the command prompt, but the debugger only provides limited capabilities for examining the new process.

All built-in dcmds work as advertised, but loadable dcmds do

not since they do not perform data model conversion of

structures. The user should release and re-attach the

debugger to the process as described above in order to restore full debugging capabilities. Interaction with Job Control If the debugger is attached to a process that is stopped by job control (that is, it stopped in response to SIGTSTP, SIGTTIN, or SIGTTOU), the process can not be able to be set running again when it is continued by a continue dcmd. If the victim process is a member of the same session (that is,

it shares the same controlling terminal as mdb), mdb

attempts to bring the associated process group to the fore-

ground and to continue the process with SIGCONT to resume it

from job control stop. When mdb is detached from such a pro-

cess, it restores the process group to the background before exiting. If the victim process is not a member of the same

session, mdb cannot safely bring the process group to the

foreground, so it continues the process with respect to the debugger, but the process remains stopped by job control.

mdb prints a warning in this case, and the user must issue

an "fg" command from the appropriate shell in order to resume the process. Process Attach and Release

When mdb attaches to a running process, the process is

stopped and remains stopped until one of the continue dcmds

is applied, or the debugger quits. If the -o nostop option

is enabled prior to attaching the debugger to a process with

-p, or prior to issuing an ::attach or :A command, mdb

attaches to the process but does not stop it. While the pro-

cess is still running, it can be inspected as usual (albeit with inconsistent results) and breakpoints or other tracing

flags might be enabled. If the :c or ::cont dcmds are exe-

cuted while the process is running, the debugger waits for the process to stop. If no traced software events occur, the

SunOS 5.11 Last change: 14 Aug 2009 66

User Commands mdb(1)

user can send an interrupt (^C) after :c or ::cont to force the process to stop and return control to the debugger.

mdb releases the current running process (if any) when the

:R, ::release, :r, ::run, $q, or ::quit dcmds are executed,

or when the debugger terminates as the result of an EOF or signal. If the process was originally created by the debugger using :r or ::run, it is forcibly terminated as if by SIGKILL when it is released. If the process was already

running prior to attaching mdb to it, it is set running

again when it is released. A process can be released and

left stopped and abandoned using the ::release -a option.

Symbolic Debugging Information The ::list, ::offsetof, ::print, and ::sizeof dcmds require that one or more load objects contain compressed symbolic

debugging information suitable for use with mdb. This infor-

mation is currently only available for certain Solaris ker-

nel modules. Developer Information The Oracle Solaris Modular Debugger Guide provides a more

detailed description of mdb features, as well as information

for debugger module developers.

The header file contains prototypes for

the functions in the MDB Module API, and the SUNWmdbdm pack-

age provides source code for an example module in the direc-

tory /usr/demo/mdb.

SunOS 5.11 Last change: 14 Aug 2009 67