1mdb(1) User Commands mdb(1)
2
6 mdb - modular debugger
7
9 mdb [-fkmuwyAFKMSUW] [±o option] [-p pid] [-s distance]
10 [-I path] [-L path] [-P prompt] [-R root]
11 [-V dis-version] [object [core] | core | suffix]
12
15 Introduction
16 The mdb utility is an extensible utility for low-level debugging and
17 editing of the live operating system, operating system crash dumps,
18 user processes, user process core dumps, and object files. For a more
19 detailed description of mdb features, refer to the manual, Solaris Mod‐
20 ular Debugger Guide.
21 Debugging is the process of analyzing the execution and state of a
24 software program in order to remove defects. Traditional debugging
25 tools provide facilities for execution control so that programmers can
26 re-execute programs in a controlled environment and display the current
27 state of program data or evaluate expressions in the source language
28 used to develop the program.
29 Unfortunately, these techniques are often inappropriate for debugging
32 complex software systems such as an operating system, where bugs might
33 not be reproducible and program state is massive and distributed, for
34 programs that are highly optimized, have had their debug information
35 removed, or are themselves low-level debugging tools, or for customer
36 situations where the developer can only access post-mortem information.
37 mdb provides a completely customizable environment for debugging these
40 programs and scenarios, including a dynamic module facility that pro‐
41 grammers can use to implement their own debugging commands to perform
42 program-specific analysis. Each mdb module can be used to examine the
43 program in several different contexts, including live and post-mortem.
44 Definitions
46 The target is the program being inspected by the debugger. mdb cur‐
47 rently provides support for the following types of targets: user pro‐
48 cesses, user process core files, the live operating system (via
49 /dev/kmem and /dev/ksyms), operating system crash dumps, user process
50 images recorded inside an operating system crash dump, ELF object
51 files, and raw binary files. Each target exports a standard set of
52 properties, including one or more address spaces, one or more symbol
53 tables, a set of load objects, and a set of threads that can be exam‐
54 ined using the debugger commands described below.
55 A debugger command, or dcmd (pronounced dee-command) in mdb terminol‐
58 ogy, is a routine in the debugger that can access any of the properties
59 of the current target. mdb parses commands from standard input, and
60 then executes the corresponding dcmds. Each dcmd can also accept a list
61 of string or numerical arguments, as shown in the syntax description
62 below. mdb contains a set of built-in dcmds, described below, that are
63 always available. You can also extend the capabilities of mdb itself by
64 writing your own dcmds, as described in the Solaris Modular Debugger
65 Guide.
66 A walker is a set of routines that describe how to walk, or iterate,
69 through the elements of a particular program data structure. A walker
70 encapsulates the data structure's implementation from dcmds and from
71 mdb itself. You can use walkers interactively, or use them as a primi‐
72 tive to build other dcmds or walkers. As with dcmds, you can extend mdb
73 by implementing your own walkers as part of a debugger module.
74 A debugger module, or dmod (pronounced dee-mod), is a dynamically
77 loaded library containing a set of dcmds and walkers. During initial‐
78 ization, mdb attempts to load dmods corresponding to the load objects
79 present in the target. You can subsequently load or unload dmods at any
80 time while running mdb. mdb ships with a set of standard dmods for
81 debugging the Solaris kernel. The Solaris Modular Debugger Guide con‐
82 tains more information on developing your own debugger modules.
83 A macro file is a text file containing a set of commands to execute.
86 Macro files are typically used to automate the process of displaying a
87 simple data structure. mdb provides complete backward compatibility for
88 the execution of macro files written for adb(1), and the Solaris
89 installation includes a set of macro files for debugging the Solaris
90 kernel that can be used with either tool.
91 Syntax
93 The debugger processes commands from standard input. If standard input
94 is a terminal, mdb provides terminal editing capabilities. mdb can also
95 process commands from macro files and from dcmd pipelines, described
96 below. The language syntax is designed around the concept of computing
97 the value of an expression (typically a memory address in the target),
98 and then applying a dcmd to that address. The current address location
99 is referred to as dot, and its value is referenced using ``.''.
100 A metacharacter is one of the following characters:
103 [ ] | ! / \ ? = > $ : ;
105 NEWLINE SPACE TAB
106 A blank is a TAB or a SPACE. A word is a sequence of characters sepa‐
111 rated by one or more non-quoted metacharacters. Some of the metacharac‐
112 ters only function as delimiters in certain contexts, as described
113 below. An identifier is a sequence of letters, digits, underscores,
114 periods, or backquotes beginning with a letter, underscore, or period.
115 Identifiers are used as the names of symbols, variables, dcmds, and
116 walkers. Commands are delimited by a NEWLINE or semicolon ( ; ).
117 A dcmd is denoted by one of the following words or metacharacters:
120 / \ ? = > $character :character ::identifier
122 dcmds named by metacharacters or prefixed by a single $ or : are pro‐
127 vided as built-in operators, and implement complete compatibility with
128 the command set of the legacy adb(1) utility. Once a dcmd has been
129 parsed, the /, \, ?, =, >, $, and : characters are no longer recognized
130 as metacharacters until the termination of the argument list.
131 A simple-command is a dcmd followed by a sequence of zero or more
134 blank-separated words. The words are passed as arguments to the invoked
135 dcmd, except as specified under Quoting and Arithmetic Expansion below.
136 Each dcmd returns an exit status that indicates it was either success‐
137 ful, failed, or was invoked with invalid arguments.
138 A pipeline is a sequence of one or more simple commands separated by |.
141 Unlike the shell, dcmds in mdb pipelines are not executed as separate
142 processes. After the pipeline has been parsed, each dcmd is invoked in
143 order from left to right. Each dcmd's output is processed and stored as
144 described under dcmd Pipelines below. Once the left-hand dcmd is com‐
145 plete, its processed output is used as input for the next dcmd in the
146 pipeline. If any dcmd does not return a successful exit status, the
147 pipeline is aborted.
148 An expression is a sequence of words that is evaluated to compute a
151 64-bit unsigned integer value. The words are evaluated using the rules
152 described under Arithmetic Expansion below.
153 Commands
155 A command is one of the following:
156 pipeline [! word ...] [ ; ]
158 A simple-command or pipeline can be optionally suffixed with the !
160 character, indicating that the debugger should open a pipe(2) and
161 send the standard output of the last dcmd in the mdb pipeline to an
162 external process created by executing $SHELL -c followed by the
163 string formed by concatenating the words after the ! character. For
164 more details, refer to Shell Escapes below.
165 expression pipeline [! word ...] [ ; ]
168 A simple-command or pipeline can be prefixed with an expression.
170 Before execution of the pipeline, the value of dot (the variable
171 denoted by ``.'') is set to the value of the expression.
172 expression , expression pipeline [! word ...] [ ; ]
175 A simple-command or pipeline can be prefixed with two expressions.
177 The first is evaluated to determine the new value of dot, and the
178 second is evaluated to determine a repeat count for the first dcmd
179 in the pipeline. This dcmd is executed count times before the next
180 dcmd in the pipeline is executed. The repeat count only applies to
181 the first dcmd in the pipeline.
182 , expression pipeline [! word ...] [ ; ]
185 If the initial expression is omitted, dot is not modified but the
187 first dcmd in the pipeline is repeated according to the value of
188 the expression.
189 expression [! word ...] [ ; ]
192 A command can consist only of an arithmetic expression. The expres‐
194 sion is evaluated and the dot variable is set to its value, and
195 then the previous dcmd and arguments are executed using the new
196 value of dot.
197 expression, expression [! word ...] [ ; ]
200 A command can consist only of a dot expression and repeat count
202 expression. After dot is set to the value of the first expression,
203 the previous dcmd and arguments are repeatedly executed the number
204 of times specified by the value of the second expression.
205 , expression [! word ...] [ ; ]
208 If the initial expression is omitted, dot is not modified but the
210 previous dcmd and arguments are repeatedly executed the number of
211 times specified by the value of the count expression.
212 ! word ... [ ; ]
215 If the command begins with the ! character, no dcmds are executed
217 and the debugger simply executes $SHELL -c followed by the string
218 formed by concatenating the words after the ! character.
219 Comments
222 A word beginning with // causes that word and all the subsequent char‐
223 acters up to a NEWLINE to be ignored.
224 Arithmetic Expansion
226 Arithmetic expansion is performed when an mdb command is preceded by an
227 optional expression representing a start address, or a start address
228 and a repeat count. Arithmetic expansion can also be performed to com‐
229 pute a numerical argument for a dcmd. An arithmetic expression can
230 appear in an argument list enclosed in square brackets preceded by a
231 dollar sign ($[ expression ]), and is replaced by the value of the
232 expression.
233 Expressions can contain any of the following special words:
236 integer The specified integer value. Integer values can
238 be prefixed with 0i or 0I to indicate binary val‐
239 ues, 0o or 0O to indicate octal values, 0t or 0T
240 to indicate decimal values, and 0x or 0X to indi‐
241 cate hexadecimal values (the default).
242 0[tT][0-9]+.[0-9]+ The specified decimal floating point value, con‐
245 verted to its IEEE double-precision floating
246 point representation.
247 'cccccccc' The integer value computed by converting each
250 character to a byte equal to its ASCII value. Up
251 to eight characters can be specified in a charac‐
252 ter constant. Characters are packed into the
253 integer in reverse order (right-to-left) begin‐
254 ning at the least significant byte.
255 <identifier The value of the variable named by identifier.
258 identifier The value of the symbol named by identifier.
261 (expression) The value of expression.
264 . The value of dot.
267 & The most recent value of dot used to execute a
270 dcmd.
271 + The value of dot incremented by the current
274 increment.
275 ^ The value of dot decremented by the current
278 increment.
279 The increment is a global variable that stores the total bytes read by
283 the last formatting dcmd. For more information on the increment, refer
284 to the discussion of Formatting dcmds below.
285 Unary operators are right associative and have higher precedence than
288 binary operators. The unary operators are:
289 #expression Logical negation.
291 ~expression Bitwise complement.
294 -expression Integer negation.
297 %expression The value of a pointer-sized quantity at the
300 object file location corresponding to virtual
301 address expression in the target's virtual
302 address space.
303 %/[csil]/expression The value of a char, short, int, or long-sized
306 quantity at the object file location correspond‐
307 ing to virtual address expression in the tar‐
308 get's virtual address space.
309 %/[1248]/expression The value of a one, two, four, or eight-byte
312 quantity at the object file location correspond‐
313 ing to virtual address expression in the tar‐
314 get's virtual address space.
315 *expression The value of a pointer-sized quantity at virtual
318 address expression in the target's virtual
319 address space.
320 */[csil]/expression The value of a char, short, int, or long-sized
323 quantity at virtual address expression in the
324 target's virtual address space.
325 */[1248]/expression The value of a one, two, four, or eight-byte
328 quantity at virtual address expression in the
329 target's virtual address space.
330 Binary operators are left associative and have lower precedence than
334 unary operators. The binary operators, in order of precedence from
335 highest to lowest, are:
336 * Integer multiplication.
338 % Integer division.
341 # Left-hand side rounded up to next multiple of right-hand side.
344 + Integer addition.
347 - Integer subtraction.
350 << Bitwise shift left.
353 >> Bitwise shift right.
356 == Logical equality.
359 != Logical inequality.
362 & Bitwise AND.
365 ^ Bitwise exclusive OR.
368 | Bitwise inclusive OR.
371 Quoting
374 Each metacharacter described above (see Syntax) terminates a word
375 unless quoted. Characters can be quoted (forcing mdb to interpret each
376 character as itself without any special significance) by enclosing them
377 in a pair of single (' ') or double (" ") quote marks. A single quote
378 cannot appear within single quotes. Inside double quotes, mdb recog‐
379 nizes the C programming language character escape sequences.
380 Shell Escapes
382 The ! character can be used to create a pipeline between an mdb command
383 and the user's shell. If the $SHELL environment variable is set, mdb
384 forks and execs this program for shell escapes; otherwise /bin/sh is
385 used. The shell is invoked with the -c option followed by a string
386 formed by concatenating the words after the ! character. The ! charac‐
387 ter takes precedence over all other metacharacters, except semicolon
388 (;) and NEWLINE. Once a shell escape is detected, the remaining charac‐
389 ters up to the next semicolon or NEWLINE are passed as is to the shell.
390 The output of shell commands can not be piped to mdb dcmds. Commands
391 executed by a shell escape have their output sent directly to the ter‐
392 minal, not to mdb.
393 Variables
395 A variable is a variable name, a corresponding integer value, and a set
396 of attributes. A variable name is a sequence of letters, digits, under‐
397 scores, or periods. A variable can be assigned a value using the > dcmd
398 or ::typeset dcmd, and its attributes can be manipulated using the
399 ::typeset dcmd. Each variable's value is represented as a 64-bit
400 unsigned integer. A variable can have one or more of the following
401 attributes: read-only (cannot be modified by the user), persistent
402 (cannot be unset by the user), and tagged (user-defined indicator).
403 The following variables are defined as persistent:
406 0 The most recent value printed using the /, \, ?, or = dcmd.
408 9 The most recent count used with the $< dcmd.
411 b The virtual address of the base of the data section.
414 d The size of the data section in bytes.
417 e The virtual address of the entry point.
420 m The initial bytes (magic number) of the target's primary
423 object file, or zero if no object file has been read yet.
424 t The size of the text section in bytes.
427 hits The count of the number of times the matched software event
430 specifier has been matched. See Event Callbacks, below.
431 thread The thread identifier of the current representative thread.
434 The value of the identifier depends on the threading model
435 used by the current target. See Thread Support, below.
436 In addition, the mdb kernel and process targets export the current val‐
440 ues of the representative thread's register set as named variables. The
441 names of these variables depend on the target's platform and instruc‐
442 tion set architecture.
443 Symbol Name Resolution
445 As explained in the Syntax description above, a symbol identifier
446 present in an expression context evaluates to the value of this symbol.
447 The value typically denotes the virtual address of the storage associ‐
448 ated with the symbol in the target's virtual address space. A target
449 can support multiple symbol tables including, but not limited to, a
450 primary executable symbol table, a primary dynamic symbol table, a run-
451 time link-editor symbol table, and standard and dynamic symbol tables
452 for each of a number of load objects (such as shared libraries in a
453 user process, or kernel modules in the Solaris kernel). The target typ‐
454 ically searches the primary executable's symbol tables first, and then
455 one or more of the other symbol tables. Notice that ELF symbol tables
456 only contain entries for external, global, and static symbols; auto‐
457 matic symbols do not appear in the symbol tables processed by mdb.
458 Additionally, mdb provides a private user-defined symbol table that is
461 searched prior to any of the target symbol tables. The private symbol
462 table is initially empty, and can be manipulated using the ::nmadd and
463 ::nmdel dcmds. The ::nm -P option can be used to display the contents
464 of the private symbol table. The private symbol table allows the user
465 to create symbol definitions for program functions or data that were
466 either missing from the original program or stripped out. These defini‐
467 tions are then used whenever mdb converts a symbolic name to an
468 address, or an address to the nearest symbol.
469 As targets contain multiple symbol tables, and each symbol table can
472 include symbols from multiple object files, different symbols with the
473 same name can exist. mdb uses the backquote (`) character as a symbol
474 name scoping operator to allow the programmer to obtain the value of
475 the desired symbol in this situation. The programmer can specify the
476 scope used to resolve a symbol name as either: object`name, or
477 file`name, or object`file`name. The object identifier refers to the
478 name of a load object. The file identifier refers to the basename of a
479 source file that has a symbol of type STT_FILE in the specified
480 object's symbol table. The object identifier's interpretation depends
481 on the target type.
482 The mdb kernel target expects object to specify the basename of a
485 loaded kernel module. For example, the symbol name
486 specfs`_init
488 evaluates to the value of the _init symbol in the specfs kernel module.
493 The mdb process target expects object to specify the name of the exe‐
496 cutable or of a loaded shared library. It can take any of the following
497 forms:
498 1. An exact match (that is, a full pathname):
500 /usr/lib/libc.so.1
501 2. An exact basename match: libc.so.1
503 3. An initial basename match up to a ``.'' suffix: libc.so or
505 libc
506 4. The literal string a.out is accepted as an alias for the
508 executable.
509 The process target also accepts any of the four forms described above
512 preceded by an optional link-map id (lmid). The lmid prefix is speci‐
513 fied by an initial "LM" followed by the link-map id in hexadecimal fol‐
514 lowed by an additional backquote. For example, the symbol name
515 LM0`libc.so.1`_init
517 evaluates to the value of the _init symbol in the libc.so.1 library
522 that is loaded on link-map 0 (LM_ID_BASE). The link-map specifier can
523 be necessary to resolve symbol naming conflicts in the event that the
524 same library is loaded on more than one link map. For more information
525 on link maps, refer to the Linker and Libraries Guide and dlopen(3C).
526 Link-map identifiers are displayed when symbols are printed according
527 to the setting of the showlmid option, as described under OPTIONS.
528 In the case of a naming conflict between symbols and hexadecimal inte‐
531 ger values, mdb attempts to evaluate an ambiguous token as a symbol
532 first, before evaluating it as an integer value. For example, the token
533 f can either refer to the decimal integer value 15 specified in hexa‐
534 decimal (the default base), or to a global variable named f in the tar‐
535 get's symbol table. If a symbol with an ambiguous name is present, the
536 integer value can be specified by using an explicit 0x or 0X prefix.
537 dcmd and Walker Name Resolution
539 As described earlier, each mdb dmod provides a set of dcmds and walk‐
540 ers. dcmds and walkers are tracked in two distinct, global namespaces.
541 mdb also keeps track of a dcmd and walker namespace associated with
542 each dmod. Identically named dcmds or walkers within a given dmod are
543 not allowed: a dmod with this type of naming conflict fails to load.
544 Name conflicts between dcmds or walkers from different dmods are
545 allowed in the global namespace. In the case of a conflict, the first
546 dcmd or walker with that particular name to be loaded is given prece‐
547 dence in the global namespace. Alternate definitions are kept in a list
548 in load order. The backquote character (`) can be used in a dcmd or
549 walker name as a scoping operator to select an alternate definition.
550 For example, if dmods m1 and m2 each provide a dcmd d, and m1 is loaded
551 prior to m2, then:
552 ::d Executes m1's definition of d.
554 ::m1`d Executes m1's definition of d.
557 ::m2`d Executes m2's definition of d.
560 If module m1 were now unloaded, the next dcmd on the global definition
564 list (m2`d) would be promoted to global visibility. The current defini‐
565 tion of a dcmd or walker can be determined using the ::which dcmd,
566 described below. The global definition list can be displayed using the
567 ::which -v option.
568 dcmd Pipelines
570 dcmds can be composed into a pipeline using the | operator. The purpose
571 of a pipeline is to pass a list of values, typically virtual addresses,
572 from one dcmd or walker to another. Pipeline stages might be used to
573 map a pointer from one type of data structure to a pointer to a corre‐
574 sponding data structure, to sort a list of addresses, or to select the
575 addresses of structures with certain properties.
576 mdb executes each dcmd in the pipeline in order from left to right. The
579 leftmost dcmd is executed using the current value of dot, or using the
580 value specified by an explicit expression at the start of the command.
581 When a | operator is encountered, mdb creates a pipe (a shared buffer)
582 between the output of the dcmd to its left and the mdb parser, and an
583 empty list of values. As the dcmd executes, its standard output is
584 placed in the pipe and then consumed and evaluated by the parser, as if
585 mdb were reading this data from standard input. Each line must consist
586 of an arithmetic expression terminated by a NEWLINE or semicolon (;).
587 The value of the expression is appended to the list of values associ‐
588 ated with the pipe. If a syntax error is detected, the pipeline is
589 aborted.
590 When the dcmd to the left of a | operator completes, the list of values
593 associated with the pipe is then used to invoke the dcmd to the right
594 of the | operator. For each value in the list, dot is set to this value
595 and the right-hand dcmd is executed. Only the rightmost dcmd in the
596 pipeline has its output printed to standard output. If any dcmd in the
597 pipeline produces output to standard error, these messages are printed
598 directly to standard error and are not processed as part of the pipe‐
599 line.
600 Signal Handling
602 The debugger ignores the PIPE and QUIT signals. The INT signal aborts
603 the command that is currently executing. The debugger intercepts and
604 provides special handling for the ILL, TRAP, EMT, FPE, BUS, and SEGV
605 signals. If any of these signals are generated asynchronously (that is,
606 delivered from another process using kill(2)), mdb restores the signal
607 to its default disposition and dump core. However, if any of these sig‐
608 nals are generated synchronously by the debugger process itself and a
609 dcmd from an externally loaded dmod is currently executing, and stan‐
610 dard input is a terminal, mdb provides a menu of choices allowing the
611 user to force a core dump, quit without producing a core dump, stop for
612 attach by a debugger, or attempt to resume. The resume option aborts
613 all active commands and unload the dmod whose dcmd was active at the
614 time the fault occurred. It can then be subsequently re-loaded by the
615 user. The resume option provides limited protection against buggy
616 dcmds. Refer to WARNINGS, Use of the Error Recovery Mechanism, below
617 for information about the risks associated with the resume option.
618 Command Re-entry
620 The text of the last HISTSIZE (default 128) commands entered from a
621 terminal device are saved in memory. The in-line editing facility,
622 described next, provides key mappings for searching and fetching ele‐
623 ments from the history list.
624 In-line Editing
626 If standard input is a terminal device, mdb provides some simple emacs-
627 style facilities for editing the command line. The search, previous,
628 and next commands in edit mode provide access to the history list. Only
629 strings, not patterns, are matched when searching. In the table below,
630 the notation for control characters is caret (^) followed by a charac‐
631 ter shown in upper case. The notation for escape sequences is M- fol‐
632 lowed by a character. For example, M-f (pronounced meta-eff) is entered
633 by depressing ESC followed by 'f', or by depressing Meta followed by
634 'f' on keyboards that support a Meta key. A command line is committed
635 and executed using RETURN or NEWLINE. The edit commands are:
636 ^F Move cursor forward (right) one character.
638 M-f Move cursor forward one word.
641 ^B Move cursor backward (left) one character.
644 M-b Move cursor backward one word.
647 ^A Move cursor to start of line.
650 ^E Move cursor to end of line.
653 ^D Delete current character, if the current line is not
656 empty. If the current line is empty, ^D denotes EOF and
657 the debugger exits.
658 M-^H (Meta-backspace) Delete previous word.
661 ^K Delete from the cursor to the end of the line.
664 ^L Clear the screen and reprint the current line.
667 ^T Transpose current character with next character.
670 ^N Fetch the next command from the history. Each time ^N is
673 entered, the next command forward in time is retrieved.
674 ^P Fetch the previous command from the history. Each time ^P
677 is entered, the next command backward in time is
678 retrieved.
679 ^R[string] Search backward in the history for a previous command
682 line containing string. The string should be terminated
683 by a RETURN or NEWLINE. If string is omitted, the previ‐
684 ous history element containing the most recent string is
685 retrieved.
686 The editing mode also interprets the following user-defined sequences
690 as editing commands. User defined sequences can be read or modified
691 using the stty(1) command.
692 erase User defined erase character (usually ^H or ^?). Delete pre‐
694 vious character.
695 intr User defined interrupt character (usually ^C). Abort the
698 current command and print a new prompt.
699 kill User defined kill character (usually ^U). Kill the entire
702 current command line.
703 quit User defined quit character (usually ^\). Quit the debugger.
706 suspend User defined suspend character (usually ^Z). Suspend the
709 debugger.
710 werase User defined word erase character (usually ^W). Erase the
713 preceding word.
714 On keyboards that support an extended keypad with arrow keys, mdb
718 interprets these keystrokes as editing commands:
719 up-arrow Fetch the previous command from the history (same as
721 ^P).
722 down-arrow Fetch the next command from the history (same as ^N).
725 left-arrow Move cursor backward one character (same as ^B).
728 right-arrow Move cursor forward one character (same as ^F).
731 Output Pager
734 mdb provides a built-in output pager. The output pager is enabled if
735 the debugger's standard output is a terminal device. Each time a com‐
736 mand is executed, mdb pauses after one screenful of output is produced
737 and displays a pager prompt:
738 >> More [<space>, <cr>, q, n, c, a] ?
740 The following key sequences are recognized by the pager:
745 SPACE Display the next screenful of output.
747 a, A Abort the current top-level command and return
750 to the prompt.
751 c, C Continue displaying output without pausing at
754 each screenful until the current top-level
755 command is complete.
756 n, N, NEWLINE, RETURN Display the next line of output.
759 q, Q, ^C, ^\ Quit (abort) the current dcmd only.
762 Formatting dcmds
765 The /, \, ?, and = metacharacters are used to denote the special output
766 formatting dcmds. Each of these dcmds accepts an argument list consist‐
767 ing of one or more format characters, repeat counts, or quoted strings.
768 A format character is one of the ASCII characters shown in the table
769 below. Format characters are used to read and format data from the tar‐
770 get. A repeat count is a positive integer preceding the format charac‐
771 ter that is always interpreted in base 10 (decimal). A repeat count can
772 also be specified as an expression enclosed in square brackets preceded
773 by a dollar sign ($[ ]). A string argument must be enclosed in double-
774 quotes (" "). No blanks are necessary between format arguments.
775 The formatting dcmds are:
778 / Display data from the target's virtual address space starting at
780 the virtual address specified by dot.
781 \ Display data from the target's physical address space starting at
784 the physical address specified by dot.
785 ? Display data from the target's primary object file starting at
788 the object file location corresponding to the virtual address
789 specified by dot.
790 = Display the value of dot itself in each of the specified data
793 formats. The = dcmd is therefore useful for converting between
794 bases and performing arithmetic.
795 In addition to dot, mdb keeps track of another global value called the
799 increment. The increment represents the distance between dot and the
800 address following all the data read by the last formatting dcmd. For
801 example, if a formatting dcmd is executed with dot equal to address A,
802 and displays a 4-byte integer, then after this dcmd completes, dot is
803 still A, but the increment is set to 4. The + character (described
804 under Arithmetic Expansion above) would now evaluate to the value A +
805 4, and could be used to reset dot to the address of the next data
806 object for a subsequent dcmd.
807 Most format characters increase the value of the increment by the num‐
810 ber of bytes corresponding to the size of the data format, shown in the
811 table. The table of format characters can be displayed from within mdb
812 using the ::formats dcmd. The format characters are:
813 + increment dot by the count (variable size)
818 - decrement dot by the count (variable size)
819 B hexadecimal int (1 byte)
820 C character using C character notation (1 byte)
821 D decimal signed int (4 bytes)
822 E decimal unsigned long long (8 bytes)
823 F double (8 bytes)
824 G octal unsigned long long (8 bytes)
825 H swap bytes and shorts (4 bytes)
826 I address and disassembled instruction (variable
827 size)
828 J hexadecimal long long (8 bytes)
829 K hexadecimal uintptr_t (4 or 8 bytes)
830 N newline
831 O octal unsigned int (4 bytes)
832 P symbol (4 or 8 bytes)
833 Q octal signed int (4 bytes)
834 R binary int (8 bytes)
835 S string using C string notation (variable size)
836 T horizontal tab
837 U decimal unsigned int (4 bytes)
838 V decimal unsigned int (1 byte)
839 W default radix unsigned int (4 bytes)
840 X hexadecimal int (4 bytes)
841 Y decoded time32_t (4 bytes)
842 Z hexadecimal long long (8 bytes)
843 ^ decrement dot by increment * count (variable
844 size)
845 a dot as symbol+offset
846 b octal unsigned int (1 byte)
847 c character (1 byte)
848 d decimal signed short (2 bytes)
849 e decimal signed long long (8 bytes)
850 f float (4 bytes)
851 g octal signed long long (8 bytes)
852 h swap bytes (2 bytes)
853 i disassembled instruction (variable size)
854 n newline
855 o octal unsigned short (2 bytes)
856 p symbol (4 or 8 bytes)
857 q octal signed short (2 bytes)
858 r whitespace
859 s raw string (variable size)
860 t horizontal tab
861 u decimal unsigned short (2 bytes)
862 v decimal signed int (1 byte)
863 w default radix unsigned short (2 bytes)
864 x hexadecimal short (2 bytes)
865 y decoded time64_t (8 bytes)
866 The /, \, and ? formatting dcmds can also be used to write to the tar‐
870 get's virtual address space, physical address space, or object file by
871 specifying one of the following modifiers as the first format charac‐
872 ter, and then specifying a list of words that are either immediate val‐
873 ues or expressions enclosed in square brackets preceded by a dollar
874 sign ($[ ]).
875 The write modifiers are:
878 v Write the lowest byte of the value of each expression to the tar‐
880 get beginning at the location specified by dot.
881 w Write the lowest two bytes of the value of each expression to the
884 target beginning at the location specified by dot.
885 W Write the lowest 4 bytes of the value of each expression to the
888 target beginning at the location specified by dot.
889 Z Write the complete 8 bytes of the value of each expression to the
892 target beginning at the location specified by dot.
893 The /, \, and ? formatting dcmds can also be used to search for a par‐
897 ticular integer value in the target's virtual address space, physical
898 address space, and object file, respectively, by specifying one of the
899 following modifiers as the first format character, and then specifying
900 a value and optional mask. The value and mask are each specified as
901 either immediate values or expressions enclosed in square brackets pre‐
902 ceded by a dollar sign. If only a value is specified, mdb reads inte‐
903 gers of the appropriate size and stops at the address containing the
904 matching value. If a value V and mask M are specified, mdb reads inte‐
905 gers of the appropriate size and stops at the address containing a
906 value X where (X & M) == V. At the completion of the dcmd, dot is
907 updated to the address containing the match. If no match is found, dot
908 is left at the last address that was read.
909 The search modifiers are:
912 l Search for the specified 2-byte value.
917 L Search for the specified 4-byte value.
918 M Search for the specified 8-byte value.
919 Notice that for both user and kernel targets, an address space is typi‐
923 cally composed of a set of discontiguous segments. It is not legal to
924 read from an address that does not have a corresponding segment. If a
925 search reaches a segment boundary without finding a match, it aborts
926 when the read past the end of the segment boundary fails.
927 Execution Control
929 mdb provides facilities for controlling and tracing the execution of a
930 live running program. Currently, only the user process target provides
931 support for execution control. mdb provides a simple model of execution
932 control: a target process can be started from within the debugger using
933 ::run, or mdb can attach to an existing process using :A, ::attach, or
934 the -p command-line option, as described below. A list of traced soft‐
935 ware events can be specified by the user. Each time a traced event
936 occurs in the target process, all threads in the target stop, the
937 thread that triggered the event is chosen as the representative thread,
938 and control returns to the debugger. Once the target program is set
939 running, control can be asynchronously returned to the debugger by typ‐
940 ing the user-defined interrupt character (typically ^C).
941 A software event is a state transition in the target program that is
944 observed by the debugger. For example, the debugger can observe the
945 transition of a program counter register to a value of interest (a
946 breakpoint) or the delivery of a particular signal.
947 A software event specifier is a description of a class of software
950 events that is used by the debugger to instrument the target program in
951 order to observe these events. The ::events dcmd is used to list the
952 software event specifiers. A set of standard properties is associated
953 with each event specifier, as described under ::events, below.
954 The debugger can observe a variety of different software events,
957 including breakpoints, watchpoints, signals, machine faults, and system
958 calls. New specifiers can be created using ::bp, ::fltbp, ::sigbp,
959 ::sysbp, or ::wp. Each specifier has an associated callback (an mdb
960 command string to execute as if it had been typed at the command
961 prompt) and a set of properties, as described below. Any number of
962 specifiers for the same event can be created, each with different call‐
963 backs and properties. The current list of traced events and the proper‐
964 ties of the corresponding event specifiers can be displayed using the
965 ::events dcmd. The event specifier properties are defined as part of
966 the description of the ::events and ::evset dcmds, below.
967 The execution control built-in dcmds, described below, are always
970 available, but issues an error message indicating they are not sup‐
971 ported if applied to a target that does not support execution control.
972 For more information about the interaction of exec, attach, release,
973 and job control with debugger execution control, refer to NOTES, below.
974 Event Callbacks
976 The ::evset dcmd and event tracing dcmds allow you to associate an
977 event callback (using the -c option) with each event specifier. The
978 event callbacks are strings that represent mdb commands to execute when
979 the corresponding event occurs in the target. These commands are exe‐
980 cuted as if they had been typed at the command prompt. Before executing
981 each callback, the dot variable is set to the value of the representa‐
982 tive thread's program counter and the "hits" variable is set to the
983 number of times this specifier has been matched, including the current
984 match.
985 If the event callbacks themselves contain one or more commands to con‐
988 tinue the target (for example, ::cont or ::step), these commands do not
989 immediately continue the target and wait for it to stop again. Instead,
990 inside of an event callback, the continue dcmds note that a continue
991 operation is now pending, and then return immediately. Therefore, if
992 multiple dcmds are included in an event callback, the step or continue
993 dcmd should be the last command specified. Following the execution of
994 all event callbacks, the target immediately resumes execution if all
995 matching event callbacks requested a continue. If conflicting continue
996 operations are requested, the operation with the highest precedence
997 determines what type of continue occurs. The order of precedence from
998 highest to lowest is: step, step-over (next), step-out, continue.
999 Thread Support
1001 mdb provides facilities to examine the stacks and registers of each
1002 thread associated with the target. The persistent "thread" variable
1003 contains the current representative thread identifier. The format of
1004 the thread identifier depends on the target. The ::regs and ::fpregs
1005 dcmds can be used to examine the register set of the representative
1006 thread, or of another thread if its register set is currently avail‐
1007 able. In addition, the register set of the representative thread is
1008 exported as a set of named variables. The user can modify the value of
1009 one or more registers by applying the > dcmd to the corresponding named
1010 variable.
1011 The mdb kernel target exports the virtual address of the corresponding
1014 internal thread structure as the identifier for a given thread. The
1015 Solaris Modular Debugger Guide provides more information on debugging
1016 support for threads in the Solaris kernel. The mdb process target pro‐
1017 vides proper support for examination of multi-threaded user processes
1018 that use the native lwp_* interfaces, /usr/lib/libthread.so or
1019 /usr/lib/lwp/libthread.so. When debugging a live user process, mdb
1020 detects if a single threaded process dlopens or closes libthread and
1021 automatically adjusts its view of the threading model on-the-fly. The
1022 process target thread identifiers corresponds to either the lwpid_t,
1023 thread_t, or pthread_t of the representative, depending on the thread‐
1024 ing model used by the application.
1025 If mdb is debugging a user process target and the target makes use of
1028 compiler-supported thread-local storage, mdb automatically evaluates
1029 symbol names referring to thread-local storage to the address of the
1030 storage corresponding to the current representative thread. The ::tls
1031 built-in dcmd can be used to display the value of the symbol for
1032 threads other than the representative thread.
1033 Built-in dcmds
1035 mdb provides a set of built-in dcmds that are always defined. Some of
1036 these dcmds are only applicable to certain targets: if a dcmd is not
1037 applicable to the current target, it fails and prints a message indi‐
1038 cating "command is not supported by current target". In many cases, mdb
1039 provides a mnemonic equivalent (::identifier) for the legacy adb(1)
1040 dcmd names. For example, ::quit is provided as the equivalent of $q.
1041 Programmers who are experienced with adb(1) or who appreciate brevity
1042 or arcana can prefer the $ or : forms of the built-ins. Programmers who
1043 are new to mdb might prefer the more verbose :: form. The built-ins are
1044 shown in alphabetical order. If a $ or : form has a ::identifier equiv‐
1045 alent, it is shown underneath the ::identifier form. The built-in dcmds
1046 are:
1047 > variable-name
1049 >/modifier/variable-name
1050 Assign the value of dot to the specified named variable. Some vari‐
1052 ables are read-only and can not be modified. If the > is followed
1053 by a modifier character surrounded by / /, then the value is modi‐
1054 fied as part of the assignment. The modifier characters are:
1055 c unsigned char quantity (1-byte)
1057 s unsigned short quantity (2-byte)
1060 i unsigned int quantity (4-byte)
1063 l unsigned long quantity (4-byte in 32-bit, 8-byte in 64-bit)
1066 Notice that these operators do not perform a cast. Instead, they
1068 fetch the specified number of low-order bytes (on little-endian
1069 architectures) or high-order bytes (big-endian architectures). Mod‐
1070 ifiers are provided for backwards compatibility; the mdb */modi‐
1071 fier/ and %/modifier/ syntax should be used instead.
1072 $< macro-name
1075 Read and execute commands from the specified macro file. The file‐
1077 name can be given as an absolute or relative path. If the filename
1078 is a simple name (that is, if it does not contain a '/'), mdb
1079 searches for it in the macro file include path. If another macro
1080 file is currently being processed, this file is closed and replaced
1081 with the new file.
1082 $<< macro-name
1085 Read and execute commands from the specified macro file (as with
1087 $<), but do not close the current open macro file.
1088 $?
1091 Print the process-ID and current signal of the target if it is a
1093 user process or core file, and then print the general register set
1094 of the representative thread.
1095 [ address ] $C [ count ]
1098 Print a C stack backtrace, including stack frame pointer informa‐
1100 tion. If the dcmd is preceded by an explicit address, a backtrace
1101 beginning at this virtual memory address is displayed. Otherwise
1102 the stack of the representative thread is displayed. If an optional
1103 count value is given as an argument, no more than count arguments
1104 are displayed for each stack frame in the output.
1105 [ base ] $d
1108 Get or set the default output radix. If the dcmd is preceded by an
1110 explicit expression, the default output radix is set to the given
1111 base; otherwise the current radix is printed in base 10 (decimal).
1112 The default radix is base 16 (hexadecimal).
1113 $e
1116 Print a list of all known external (global) symbols of type object
1118 or function, the value of the symbol, and the first 4 (32-bit mdb)
1119 or 8 (64-bit mdb) bytes stored at this location in the target's
1120 virtual address space. The ::nm dcmd provides more flexible options
1121 for displaying symbol tables.
1122 $P prompt-string
1125 Set the prompt to the specified prompt-string. The default prompt
1127 is '> '. The prompt can also be set using ::set -P or the -P com‐
1128 mand-line option.
1129 distance $s
1132 Get or set the symbol matching distance for address-to-symbol-name
1134 conversions. The symbol matching distance modes are discussed along
1135 with the -s command-line option under OPTIONS. The symbol matching
1136 distance can also be modified using the ::set -s option. If no dis‐
1137 tance is specified, the current setting is displayed.
1138 $v
1141 Print a list of the named variables that have non-zero values. The
1143 ::vars dcmd provides other options for listing variables.
1144 width $w
1147 Set the output page width to the specified value. Typically, this
1149 command is not necessary as mdb queries the terminal for its width
1150 and handles resize events.
1151 $W
1154 Re-open the target for writing, as if mdb had been executed with
1156 the -w option on the command line. Write mode can also be enabled
1157 with the ::set -w option.
1158 [ pid ] ::attach [ core | pid ]
1161 [ pid ] :A [ core | pid ]
1162 If the user process target is active, attach to and debug the spec‐
1164 ified process-ID or core file. The core file pathname should be
1165 specified as a string argument. The process-ID can be specified as
1166 the string argument, or as the value of the expression preceding
1167 the dcmd. Recall that the default base is hexadecimal, so decimal
1168 PIDs obtained using pgrep(1) or ps(1) should be preceded with "0t"
1169 when specified as expressions.
1170 [address] ::bp [-/-dDesT] [-c cmd] [-n count] sym ...
1173 address :b [cmd ...]
1174 Set a breakpoint at the specified locations. The ::bp dcmd sets a
1176 breakpoint at each address or symbol specified, including an
1177 optional address specified by an explicit expression preceding the
1178 dcmd, and each string or immediate value following the dcmd. The
1179 arguments can either be symbol names or immediate values denoting a
1180 particular virtual address of interest. If a symbol name is speci‐
1181 fied, it can refer to a symbol that cannot yet be evaluated in the
1182 target process. That is, it can consist of an object name and func‐
1183 tion name in a load object that has not yet been opened. In this
1184 case, the breakpoint is deferred and is not active in the target
1185 until an object matching the given name is loaded. The breakpoint
1186 is automatically enabled when the load object is opened. Break‐
1187 points on symbols defined in a shared library should always be set
1188 using a symbol name and not using an address expression, as the
1189 address can refer to the corresponding Procedure Linkage Table
1190 (PLT) entry instead of the actual symbol definition. Breakpoints
1191 set on PLT entries can be overwritten by the run-time link-editor
1192 when the PLT entry is subsequently resolved to the actual symbol
1193 definition. The -d, -D, -e, -s, -t, -T, -c, and -n options have the
1194 same meaning as they do for the ::evset dcmd, as described below.
1195 If the :b form of the dcmd is used, a breakpoint is only set at the
1196 virtual address specified by the expression preceding the dcmd. The
1197 arguments following the :b dcmd are concatenated together to form
1198 the callback string. If this string contains meta-characters, it
1199 must be quoted.
1200 ::cat filename ...
1203 Concatenate and display files. Each filename can be specified as a
1205 relative or absolute pathname. The file contents are printed to
1206 standard output, but are not passed to the output pager. This dcmd
1207 is intended to be used with the | operator; the programmer can ini‐
1208 tiate a pipeline using a list of addresses stored in an external
1209 file.
1210 ::cont [ SIG ]
1213 :c [ SIG ]
1214 Suspend the debugger, continue the target program, and wait for it
1216 to terminate or stop following a software event of interest. If the
1217 target is already running because the debugger was attached to a
1218 running program with the -o nostop option enabled, this dcmd simply
1219 waits for the target to terminate or stop after an event of inter‐
1220 est. If an optional signal name or number (see signal.h(3HEAD)) is
1221 specified as an argument, the signal is immediately delivered to
1222 the target as part of resuming its execution. If the SIGINT signal
1223 is traced, control can be asynchronously returned to the debugger
1224 by typing the user-defined interrupt character (usually ^C). This
1225 SIGINT signal is automatically cleared and is not observed by the
1226 target the next time it is continued. If no target program is cur‐
1227 rently running, ::cont starts a new program running as if by ::run.
1228 address ::context
1231 address $p
1232 Context switch to the specified process. A context switch operation
1234 is only valid when using the kernel target. The process context is
1235 specified using the address of its proc structure in the kernel's
1236 virtual address space. The special context address "0" is used to
1237 denote the context of the kernel itself. mdb can only perform a
1238 context switch when examining a crash dump if the dump contains the
1239 physical memory pages of the specified user process (as opposed to
1240 just kernel pages). The kernel crash dump facility can be config‐
1241 ured to dump all pages or the pages of the current user process
1242 using dumpadm(1M). The ::status dcmd can be used to display the
1243 contents of the current crash dump.
1244 When the user requests a context switch from the kernel target, mdb
1246 constructs a new target representing the specified user process.
1247 Once the switch occurs, the new target interposes its dcmds at the
1248 global level: thus the / dcmd now formats and displays data from
1249 the virtual address space of the user process, the ::mappings dcmd
1250 displays the mappings in the address space of the user process, and
1251 so on. The kernel target can be restored by executing 0::context.
1252 ::dcmds
1255 List the available dcmds and print a brief description for each
1257 one.
1258 [ address ] ::delete [ id | all ]
1261 [ address ] :d [ id | all ]
1262 Delete the event specifiers with the given id number. The id number
1264 argument is interpreted in decimal by default. If an optional
1265 address is specified preceding the dcmd, all event specifiers that
1266 are associated with the given virtual address are deleted (for
1267 example, all breakpoints or watchpoints affecting that address). If
1268 the special argument "all" is given, all event specifiers are
1269 deleted, except those that are marked sticky (T flag). The ::events
1270 dcmd displays the current list of event specifiers.
1271 [ address ] ::dis [ -fw ] [ -n count ] [ address ]
1274 Disassemble starting at or around the address specified by the
1276 final argument, or the current value of dot. If the address matches
1277 the start of a known function, the entire function is disassembled.
1278 Otherwise, a "window" of instructions before and after the speci‐
1279 fied address is printed in order to provide context. By default,
1280 instructions are read from the target's virtual address space. If
1281 the -f option is present, instructions are read from the target's
1282 object file instead. The -f option is enabled by default if the
1283 debugger is not currently attached to a live process, core file, or
1284 crash dump. The -w option can be used to force "window"-mode, even
1285 if the address is the start of a known function. The size of the
1286 window defaults to ten instructions; the number of instructions can
1287 be specified explicitly using the -n option.
1288 ::disasms
1291 List the available disassembler modes. When a target is initial‐
1293 ized, mdb attempts to select the appropriate disassembler mode. The
1294 user can change the mode to any of the modes listed using the
1295 ::dismode dcmd.
1296 ::dismode [ mode ]
1299 $V [ mode ]
1300 Get or set the disassembler mode. If no argument is specified,
1302 print the current disassembler mode. If a mode argument is speci‐
1303 fied, switch the disassembler to the specified mode. The list of
1304 available disassemblers can be displayed using the ::disasms dcmd.
1305 ::dmods [ -l ] [ module-name ]
1308 List the loaded debugger modules. If the -l option is specified,
1310 the list of the dcmds and walkers associated with each dmod is
1311 printed below its name. The output can be restricted to a particu‐
1312 lar dmod by specifying its name as an additional argument.
1313 [ address ] ::dump [ -eqrstu ] [ -f|-p ]
1316 #sp;#sp;[ -g bytes ] [ -w paragraphs ]
1317 Print a hexadecimal and ASCII memory dump of the 16-byte aligned
1319 region of memory containing the address specified by dot. If a
1320 repeat count is specified for ::dump, this is interpreted as a num‐
1321 ber of bytes to dump rather than a number of iterations. The ::dump
1322 dcmd also recognizes the following options:
1323 -e Adjusts for endian-ness. The -e option assumes
1325 4-byte words. The -g option can be used to change
1326 the default word size.
1327 -f Reads data from the object file location corre‐
1330 sponding to the given virtual address instead of
1331 from the target's virtual address space. The -f
1332 option is enabled by default if the debugger is
1333 not currently attached to a live process, core
1334 file, or crash dump.
1335 -g bytes Displays bytes in groups of bytes. The default
1338 group size is 4 bytes. The group size must be a
1339 power of two that divides the line width.
1340 -p Interprets address as a physical address location
1343 in the target's address space instead of a virtual
1344 address.
1345 -q Does not print an ASCII decoding of the data.
1348 -r Numbers lines relative to the start address
1351 instead of with the explicit address of each line.
1352 This option implies the -u option.
1353 -s Elides repeated lines.
1356 -t Only reads from and displays the contents of the
1359 specified addresses, instead of reading and print‐
1360 ing entire lines.
1361 -u Unaligns output instead of aligning the output at
1364 a paragraph boundary.
1365 -w paragraphs Displays paragraphs at 16-byte paragraphs per
1368 line. The default number of paragraphs is one. The
1369 maximum value accepted for -w is 16.
1370 ::echo [ string | value ...]
1374 Print the arguments separated by blanks and terminated by a NEWLINE
1376 to standard output. Expressions enclosed in $[ ] is evaluated to a
1377 value and printed in the default base.
1378 ::eval command
1381 Evaluate and execute the specified string as a command. If the com‐
1383 mand contains metacharacters or whitespace, it should be enclosed
1384 in double or single quotes.
1385 ::events [ -av ]
1388 $b [ -av ]
1389 Display the list of software event specifiers. Each event specifier
1391 is assigned a unique ID number that can be used to delete or modify
1392 it at a later time. The debugger can also have its own internal
1393 events enabled for tracing. These events are only be displayed if
1394 the -a option is present. If the -v option is present, a more ver‐
1395 bose display, including the reason for any specifier inactivity,
1396 are shown. Here is some sample output:
1397 > ::events
1399 ID S TA HT LM Description Action
1400 ----- - -- -- -- -------------------------------- ------
1401 [ 1 ] - T 1 0 stop on SIGINT -
1402 [ 2 ] - T 0 0 stop on SIGQUIT -
1403 [ 3 ] - T 0 0 stop on SIGILL -
1404 ...
1405 [ 11] - T 0 0 stop on SIGXCPU -
1406 [ 12] - T 0 0 stop on SIGXFSZ -
1407 [ 13] - 2 0 stop at libc`printf ::echo printf
1408 >
1409 The following table explains the meaning of each column. A summary
1412 of this information is available using ::help events.
1413 ID The event specifier identifier. The identifier is
1415 shown in square brackets [ ] if the specifier is
1416 enabled, in parentheses ( ) if the specifier is dis‐
1417 abled, or in angle brackets < > if the target pro‐
1418 gram is currently stopped on an event that matches
1419 the given specifier.
1420 S The event specifier state. The state is one of the
1423 following symbols:
1424 - The event specifier is idle. When no target
1426 program is running, all specifiers are idle.
1427 When the target program is running, a specifier
1428 can be idle if it cannot be evaluated (for
1429 example, a deferred breakpoint in a shared
1430 object that is not yet loaded).
1431 + The event specifier is active. When the target
1434 is continued, events of this type is detected
1435 by the debugger.
1436 * The event specifier is armed. This state means
1439 that the target is currently running with
1440 instrumentation for this type of event. This
1441 state is only visible if the debugger is
1442 attached to a running program with the -o nos‐
1443 top option.
1444 ! The event specifier was not armed due to an
1447 operating system error. The ::events -v option
1448 can be used to display more information about
1449 the reason the instrumentation failed.
1450 TA The Temporary, Sticky, and Automatic event specifier
1454 properties. One or more of the following symbols can
1455 be shown:
1456 t The event specifier is temporary, and is
1458 deleted the next time the target stops, regard‐
1459 less of whether it is matched.
1460 T The event specifier is sticky, and is not be
1463 deleted by ::delete all or :z. The specifier
1464 can be deleted by explicitly specifying its id
1465 number to ::delete.
1466 d The event specifier is automatically disabled
1469 when the hit count is equal to the hit limit.
1470 D The event specifier is automatically deleted
1473 when the hit count is equal to the hit limit.
1474 s The target automatically stops when the hit
1477 count is equal to the hit limit.
1478 HT The current hit count. This column displays the num‐
1482 ber of times the corresponding software event has
1483 occurred in the target since the creation of this
1484 event specifier.
1485 LM The current hit limit. This column displays the
1488 limit on the hit count at which the auto-disable,
1489 auto-delete, or auto-stop behavior takes effect.
1490 These behaviors can be configured using the ::evset
1491 dcmd, described below.
1492 Description A description of the type of software event that is
1495 matched by the given specifier.
1496 Action The callback string to execute when the correspond‐
1499 ing software event occurs. This callback is executed
1500 as if it had been typed at the command prompt.
1501 [id] ::evset [-/-dDestT] [-c cmd] [-n count] id ...
1505 Modify the properties of one or more software event specifiers. The
1507 properties are set for each specifier identified by the optional
1508 expression preceding the dcmd and an optional list of arguments
1509 following the dcmd. The argument list is interpreted as a list of
1510 decimal integers, unless an explicit radix is specified. The
1511 ::evset dcmd recognizes the following options:
1512 -d Disables the event specifier when the hit count reaches the
1514 hit limit. If the -d form of the option is given, this behav‐
1515 ior is disabled. Once an event specifier is disabled, the
1516 debugger removes any corresponding instrumentation and
1517 ignores the corresponding software events until the specifier
1518 is subsequently re-enabled. If the -n option is not present,
1519 the specifier is disabled immediately.
1520 -D Deletes the event specifier when the hit count reaches the
1523 hit limit. If the -D form of the option is given, this behav‐
1524 ior is disabled. The -D option takes precedence over the -d
1525 option. The hit limit can be configured using the -n option.
1526 -e Enables the event specifier. If the -e form of the option is
1529 given, the specifier is disabled.
1530 -s Stops the target program when the hit count reaches the hit
1533 limit. If the -s form of the option is given, this behavior
1534 is disabled. The -s behavior tells the debugger to act as if
1535 the ::cont were issued following each execution of the speci‐
1536 fier's callback, except for the Nth execution, where N is the
1537 current value of the specifier's hit limit. The -s option
1538 takes precedence over both the -D option and the -d option.
1539 -t Marks the event specifier as temporary. Temporary specifiers
1542 are automatically deleted the next time the target stops,
1543 regardless of whether it stopped as the result of a software
1544 event corresponding to the given specifier. If the -t form of
1545 the option is given, the temporary marker is removed. The -t
1546 option takes precedence over the -T option.
1547 -T Marks the event specifier as sticky. Sticky specifiers are
1550 not deleted by ::delete all or :z. They can be deleted by
1551 specifying the corresponding specifier ID as an explicit
1552 argument to ::delete. If the -T form of the option is given,
1553 the sticky property is removed. The default set of event
1554 specifiers are all initially marked sticky.
1555 -c Executes the specified cmd string each time the corresponding
1558 software event occurs in the target program. The current
1559 callback string can be displayed using ::events.
1560 -n Sets the current value of the hit limit to count. If no hit
1563 limit is currently set and the -n option does not accompany
1564 -s or D, the hit limit is set to one.
1565 A summary of this information is available using ::help evset.
1567 ::files
1570 $f
1571 Print a list of the known source files (symbols of type STT_FILE
1573 present in the various target symbol tables).
1574 [flt] ::fltbp [-/-dDestT] [-c cmd] [-n count] flt ...
1577 Trace the specified machine faults. The faults are identified using
1579 an optional fault number preceding the dcmd, or a list of fault
1580 names or numbers (see <sys/fault.h>) following the dcmd. The -d,
1581 -D, -e, -s, -t, -T, -c, and -n options have the same meaning as
1582 they do for the ::evset dcmd.
1583 [ thread ] ::fpregs
1586 [ thread ] $x, $X, $y, $Y
1587 Print the floating-point register set of the representative thread.
1589 If a thread is specified, the floating point registers of that
1590 thread are displayed. The thread expression should be one of the
1591 thread identifiers described under Thread Support, above.
1592 ::formats
1595 List the available output format characters for use with the /, \,
1597 ?, and = formatting dcmds. The formats and their use is described
1598 under Formatting dcmds, above.
1599 ::grep command
1602 Evaluate the specified command string, and then print the old value
1604 of dot if the new value of dot is non-zero. If the command contains
1605 whitespace or metacharacters, it must be quoted. The ::grep dcmd
1606 can be used in pipelines to filter a list of addresses.
1607 ::help [ dcmd-name ]
1610 With no arguments, the ::help dcmd prints a brief overview of the
1612 help facilities available in mdb. If a dcmd-name is specified, mdb
1613 prints a usage summary for that dcmd.
1614 signal :i
1617 If the target is a live user process, ignore the specified signal
1619 and allow it to be delivered transparently to the target. All event
1620 specifiers that are tracing delivery of the specified signal is
1621 deleted from the list of traced events. By default, the set of
1622 ignored signals is initialized to the complement of the set of sig‐
1623 nals that cause a process to dump core by default (see sig‐
1624 nal.h(3HEAD)), except for SIGINT, which is traced by default.
1625 $i
1628 Display the list of signals that are ignored by the debugger and
1630 that is handled directly by the target. More information on traced
1631 signals can be obtained using the ::events dcmd.
1632 ::kill
1635 :k
1636 Forcibly terminate the target if it is a live user process. The
1638 target is also forcibly terminated when the debugger exits if it
1639 was created by the debugger using ::run.
1640 $l
1643 Print the LWPID of the representative thread, if the target is a
1645 user process.
1646 $L
1649 Print the LWPIDs of each LWP in the target, if the target is a user
1651 process.
1652 [ address ] ::list type member [ variable-name ]
1655 Walk through the elements of a linked list data structure and print
1657 the address of each element in the list. The address of the first
1658 element in the list can be specified using an optional address.
1659 Otherwise, the list is assumed to start at the current value of
1660 dot. The type parameter must name a C struct or union type and is
1661 used to describe the type of the list elements so that mdb can read
1662 in objects of the appropriate size. The member parameter is used to
1663 name the member of type that contains a pointer to the next list
1664 element. The ::list dcmd continues iterating until a NULL pointer
1665 is encountered, the first element is reached again (a circular
1666 list), or an error occurs while reading an element. If the optional
1667 variable-name is specified, the specified variable is assigned the
1668 value returned at each step of the walk when mdb invokes the next
1669 stage of a pipeline. The ::list dcmd can only be used with objects
1670 that contain symbolic debugging information designed for use with
1671 mdb. Refer to NOTES, Symbolic Debugging Information, below for more
1672 information.
1673 ::load [ -s ] module-name
1676 Load the specified dmod. The module name can be given as an abso‐
1678 lute or relative path. If module-name is a simple name (that is,
1679 does not contain a '/'), mdb searches for it in the module library
1680 path. Modules with conflicting names can not be loaded; the exist‐
1681 ing module must be unloaded first. If the -s option is present, mdb
1682 remains silent and not issue any error messages if the module is
1683 not found or could not be loaded.
1684 ::log [ -d | [ -e ] filename ]
1687 $> [ filename ]
1688 Enable or disable the output log. mdb provides an interactive log‐
1690 ging facility where both the input commands and standard output can
1691 be logged to a file while still interacting with the user. The -e
1692 option enables logging to the specified file, or re-enables logging
1693 to the previous log file if no filename is given. The -d option
1694 disables logging. If the $> dcmd is used, logging is enabled if a
1695 filename argument is specified; otherwise, logging is disabled. If
1696 the specified log file already exists, mdb appends any new log out‐
1697 put to the file.
1698 ::map command
1701 Map the value of dot to a corresponding value using the command
1703 specified as a string argument, and then print the new value of
1704 dot. If the command contains whitespace or metacharacters, it must
1705 be quoted. The ::map dcmd can be used in pipelines to transform the
1706 list of addresses into a new list of addresses.
1707 [ address ] ::mappings [ name ]
1710 [ address ] $m [ name ]
1711 Print a list of each mapping in the target's virtual address space,
1713 including the address, size, and description of each mapping. If
1714 the dcmd is preceded by an address, mdb only shows the mapping that
1715 contains the given address. If a string name argument is given, mdb
1716 only shows the mapping matching that description.
1717 ::next [ SIG ]
1720 :e [ SIG ]
1721 Step the target program one instruction, but step over subroutine
1723 calls. If an optional signal name or number (see signal.h(3HEAD))
1724 is specified as an argument, the signal is immediately delivered to
1725 the target as part of resuming its execution. If no target program
1726 is currently running, ::next starts a new program running as if by
1727 ::run and stop at the first instruction.
1728 [ address ] ::nm [ -DPdghnopuvx ] [ -t types ]
1731 #sp;#sp;[ -f format ] [ object ]
1732 Print the symbol tables associated with the current target. If an
1734 optional address preceding the dcmd is specified, only the symbol
1735 table entry for the symbol corresponding to address is displayed.
1736 If an object is specified, only the symbol table for this load
1737 object is displayed. The ::nm dcmd also recognizes the following
1738 options:
1739 -D Prints .dynsym (dynamic symbol table)
1741 instead of .symtab.
1742 -P Prints the private symbol table instead
1745 of .symtab.
1746 -d Prints value and size fields in decimal.
1749 -g Prints only global symbols.
1752 -h Suppresses the header line.
1755 -n Sorts symbols by name.
1758 -o Prints value and size fields in octal.
1761 -p Prints symbols as a series of ::nmadd
1764 commands. This option can be used with
1765 -P to produce a macro file that can be
1766 subsequently read into the debugger with
1767 $<.
1768 -u Prints only undefined symbols.
1771 -v Sorts symbols by value.
1774 -x Prints value and size fields in hexadec‐
1777 imal.
1778 -t type[,type ... ] Prints only symbols of the specified
1781 type(s). The valid type argument strings
1782 are:
1783 noty STT_NOTYPE
1785 objt STT_OBJECT
1788 func STT_FUNC
1791 sect STT_SECTION
1794 file STT_FILE
1797 comm STT_COMMON
1800 tls STT_TLS
1803 regi STT_SPARC_REGISTER
1806 -f format[,format ... ] Prints only the specified symbol infor‐
1810 mation. The valid format argument
1811 strings are:
1812 ndx symbol table index
1814 val symbol value
1817 size size in bytes
1820 type symbol type
1823 bind binding
1826 oth other
1829 shndx section index
1832 name symbol name
1835 ctype C type for symbol (if known)
1838 obj object which defines symbol
1841 value ::nmadd [ -fo ] [ -e end ] [ -s size ] name
1846 Add the specified symbol name to the private symbol table. mdb pro‐
1848 vides a private, configurable symbol table that can be used to
1849 interpose on the target's symbol table, as described under Symbol
1850 Name Resolution above. The ::nmadd dcmd also recognizes the follow‐
1851 ing options:
1852 -e Sets the size of the symbol to end - value.
1854 -f Sets the type of the symbol to STT_FUNC.
1857 -o Sets the type of the symbol to STT_OBJECT.
1860 -s Sets the size of the symbol to size.
1863 ::nmdel name
1867 Delete the specified symbol name from the private symbol table.
1869 ::objects [ -v ]
1872 Print a map of the target's virtual address space, showing only
1874 those mappings that correspond to the primary mapping (usually the
1875 text section) of each of the known load objects. The -v option dis‐
1876 plays the version of each load object. Version information is not
1877 available for all load objects. Load objects without version infor‐
1878 mation is listed as having a version of "Unknown" in the output for
1879 the -v option.
1880 ::offsetof type member
1883 Print the offset of the specified member of the specified type. The
1885 type should be the name of a C structure. The offset is printed in
1886 bytes, unless the member is a bit-field, in which case the offset
1887 can be printed in bits. The output is always suffixed with the
1888 appropriate units for clarity. The type name can use the backquote
1889 (`) scoping operator described under Symbol Name Resolution, above.
1890 The ::offsetof dcmd can only be used with objects that contain sym‐
1891 bolic debugging information designed for use with mdb. Refer to
1892 NOTES, Symbolic Debugging Information, below for more information.
1893 address ::print [ -aCdiLptx ] [ -c lim ]
1896 #sp;#sp;[ -l lim ] [ type [ member ... ] ]
1897 Print the data structure at the specified virtual address using the
1899 given type information. The type parameter can name a C struct,
1900 union, enum, fundamental integer type, or a pointer to any of these
1901 types. If the type name contains whitespace (for example, "struct
1902 foo"), it must be enclosed in single or double quotes. The type
1903 name can use the backquote (`) scoping operator described under
1904 Symbol Name Resolution, above. If the type is a structured type,
1905 the ::print dcmd recursively prints each member of the struct or
1906 union. If the type argument is not present and a static or global
1907 STT_OBJECT symbol matches the address, ::print infers the appropri‐
1908 ate type automatically. If the type argument is specified, it can
1909 be followed by an optional list of member expressions, in which
1910 case only those members and submembers of the specified type are
1911 displayed. If type contains other structured types, each member
1912 string can refer to a sub-structure element by forming a list of
1913 member names separated by period ('.') delimiters. The ::print dcmd
1914 can only be used with objects that contain symbolic debugging
1915 information designed for use with mdb. Refer to NOTES, Symbolic
1916 Debugging Information, below for more information. After displaying
1917 the data structure, ::print increments dot by the size of type in
1918 bytes.
1919 If the -a option is present, the address of each member is dis‐
1921 played. If the -p option is present, ::print interprets address as
1922 a physical memory address instead of a virtual memory address. If
1923 the -t option is present, the type of each member is displayed. If
1924 the -d or -x options are present, all integers are displayed in
1925 decimal (-d) or hexadecimal (-x). By default, a heuristic is used
1926 to determine if the value should be displayed in decimal or hexa‐
1927 decimal. The number of characters in a character array that is read
1928 and displayed as a string can be limited with the -c option. If the
1929 -C option is present, no limit is enforced. The number of elements
1930 in a standard array that is read and displayed can be limited with
1931 the -l option. If the -L option is present, no limit is enforced
1932 and all array elements are shown. The default values for -c and -l
1933 can be modified using ::set or the -o command-line option as
1934 described under OPTIONS.
1935 If the -i option is specified, the address value is interpreted as
1937 an immediate value to be printed. You must give a type with which
1938 to interpret the value. If the type is smaller than 64 bits, the
1939 immediate value is interpreted as if it were the size of the type.
1940 The -i option cannot be used in conjunction with the -p option. If
1941 the -a option is given, the addresses shown are byte offsets start‐
1942 ing at zero.
1943 ::quit
1946 $q
1947 Quit the debugger.
1949 [ thread ] ::regs
1952 [ thread ] $r
1953 Print the general purpose register set of the representative
1955 thread. If a thread is specified, the general purpose register set
1956 of that thread is displayed. The thread expression should be one of
1957 the thread identifiers described under Thread Support, above.
1958 ::release [ -a ]
1961 :R [ -a ]
1962 Release the previously attached process or core file. If the -a
1964 option is present, the process is released and left stopped and
1965 abandoned. It can subsequently be continued by prun(1) (see
1966 proc(1)) or it can be resumed by applying mdb or another debugger.
1967 By default, a released process is forcibly terminated if it was
1968 created by mdb using ::run, or it is released and set running if it
1969 was attached to by mdb using the -p option or using the ::attach or
1970 :A dcmds.
1971 ::run [ args . . . ]
1974 :r [ args . . . ]
1975 Start a new target program running with the specified arguments and
1977 attach to it. The arguments are not interpreted by the shell. If
1978 the debugger is already examining a live running program, it first
1979 detaches from this program as if by ::release.
1980 ::set [ -wF ] [ -/-o option ] [ -s distance ] [ -I path ]
1983 #sp;#sp;[ -L path ] [ -P prompt ]
1984 Get or set miscellaneous debugger properties. If no options are
1986 specified, the current set of debugger properties is displayed. The
1987 ::set dcmd recognizes the following options:
1988 -F Forcibly takes over the next user process that ::attach is
1990 applied to, as if mdb had been executed with the -F option on
1991 the command line.
1992 -I Sets the default path for locating macro files. The path
1995 argument can contain any of the special tokens described for
1996 the -I command-line option under OPTIONS.
1997 -L Sets the default path for locating debugger modules. The path
2000 argument can contain any of the special tokens described for
2001 the -I command-line option under OPTIONS.
2002 -o Enables the specified debugger option. If the -o form is
2005 used, the option is disabled. The option strings are
2006 described along with the -o command-line option under
2007 OPTIONS.
2008 -P Sets the command prompt to the specified prompt string.
2011 -s Sets the symbol matching distance to the specified distance.
2014 Refer to the description of the -s command-line option under
2015 OPTIONS for more information.
2016 -w Re-opens the target for writing, as if mdb had been executed
2019 with the -w option on the command line.
2020 ::showrev [ -pv ]
2024 Display revision information for the hardware and software. With no
2026 options specified, general system information is displayed. The -v
2027 option displays version information for all load objects, whereas
2028 the -p option displays the version information only for the load
2029 objects that have been installed on the system as part of a patch.
2030 Version information is not available for all load objects. Load
2031 objects without version information is omitted from the output for
2032 the -p option and is listed as having a version of "Unknown" in the
2033 output for the -v option.
2034 [signal] ::sigbp [-/-dDestT] [-c cmd] [-n count] SIG ...
2037 [signal] :t [-/-dDestT] [-c cmd] [-n count] SIG ...
2038 Trace delivery of the specified signals. The signals are identified
2040 using an optional signal number preceding the dcmd, or a list of
2041 signal names or numbers (see signal.h(3HEAD)) following the dcmd.
2042 The -d, -D, -e, -s, -t, -T, -c, and -n options have the same mean‐
2043 ing as they do for the ::evset dcmd. Initially, the set of signals
2044 that cause the process to dump core by default (see sig‐
2045 nal.h(3HEAD)) and SIGINT are traced.
2046 ::sizeof type
2049 Print the size of the specified type in bytes. The type parameter
2051 can name a C struct, union, enum, fundamental integer type, or a
2052 pointer to any of these types. The type name can use the backquote
2053 (`) scoping operator described under Symbol Name Resolution, above.
2054 The ::sizeof dcmd can only be used with objects that contain sym‐
2055 bolic debugging information designed for use with mdb. Refer to
2056 NOTES, Symbolic Debugging Information, below for more information.
2057 [ address ] ::stack [ count ]
2060 [ address ] $c [ count ]
2061 Print a C stack backtrace. If the dcmd is preceded by an explicit
2063 address, a backtrace beginning at this virtual memory address is
2064 displayed. Otherwise the stack of the representative thread is dis‐
2065 played. If an optional count value is given as an argument, no more
2066 than count arguments are displayed for each stack frame in the out‐
2067 put.
2068 ::status
2071 Print a summary of information related to the current target.
2073 ::step [ over | out ] [ SIG ]
2076 :s [ SIG ]
2077 :u [ SIG ]
2078 Step the target program one instruction. If an optional signal name
2080 or number (see signal.h(3HEAD)) is specified as an argument, the
2081 signal is immediately delivered to the target as part of resuming
2082 its execution. If the optional "over" argument is specified, ::step
2083 steps over subroutine calls. The ::step over argument is the same
2084 as the ::next dcmd. If the optional "out" argument is specified,
2085 the target program continues until the representative thread
2086 returns from the current function. If no target program is cur‐
2087 rently running, ::step out starts a new program running as if by
2088 ::run and stop at the first instruction. The :s dcmd is the same as
2089 ::step. The :u dcmd is the same as ::step out.
2090 [ syscall ] ::sysbp [ -/-dDestT ] [ -io ] [ -c cmd ]
2093 #sp;#sp;[ -n count ] syscall...
2094 Trace entry to or exit from the specified system calls. The system
2096 calls are identified using an optional system call number preceding
2097 the dcmd, or a list of system call names or numbers (see
2098 <sys/syscall.h>) following the dcmd. If the -i option is specified
2099 (the default), the event specifiers trigger on entry into the ker‐
2100 nel for each system call. If the -o option is specified, the event
2101 specifiers trigger on exit out from the kernel. The -d, -D, -e, -s,
2102 -t, -T, -c, and -n options have the same meaning as they do for the
2103 ::evset dcmd.
2104 thread ::tls symbol
2107 Print the address of the storage for the specified thread-local
2109 storage (TLS) symbol in the context of the specified thread. The
2110 thread expression should be one of the thread identifiers described
2111 under Thread Support, above. The symbol name can use any of the
2112 scoping operators described under Symbol Name Resolution, above.
2113 ::typeset [ -/-t] variable-name . . .
2116 Set attributes for named variables. If one or more variable names
2118 are specified, they are defined and set to the value of dot. If the
2119 -t option is present, the user-defined tag associated with each
2120 variable is set. If the -t option is present, the tag is cleared.
2121 If no variable names are specified, the list of variables and their
2122 values is printed.
2123 ::unload module-name
2126 Unload the specified dmod. The list of active dmods can be printed
2128 using the ::dmods dcmd. Built-in modules can not be unloaded. Mod‐
2129 ules that are busy (that is, provide dcmds that are currently exe‐
2130 cuting) can not be unloaded.
2131 ::unset variable-name . . .
2134 Unset (remove) the specified variable(s) from the list of defined
2136 variables. Some variables exported by mdb are marked as persistent,
2137 and can not be unset by the user.
2138 ::vars [ -npt]
2141 Print a listing of named variables. If the -n option is present,
2143 the output is restricted to variables that currently have non-zero
2144 values. If the -p option is present, the variables are printed in a
2145 form suitable for re-processing by the debugger using the $< dcmd.
2146 This option can be used to record the variables to a macro file and
2147 then restore these values later. If the -t option is present, only
2148 the tagged variables are printed. Variables can be tagged using the
2149 -t option of the ::typeset dcmd.
2150 ::version
2153 Print the debugger version number.
2155 address ::vtop [-a as]
2158 Print the physical address mapping for the specified virtual
2160 address, if possible. The ::vtop dcmd is only available when exam‐
2161 ining a kernel target, or when examining a user process inside a
2162 kernel crash dump (after a ::context dcmd has been issued).
2163 When examining a kernel target from the kernel context, the -a
2165 option can be used to specify the address (as) of an alternate
2166 address space structure that should be used for the virtual to
2167 physical translation. By default, the kernel's address space is
2168 used for translation. This option is available for active address
2169 spaces even when the dump content only contains kernel pages.
2170 [ address ] ::walk walker-name [ variable-name ]
2173 Walk through the elements of a data structure using the specified
2175 walker. The available walkers can be listed using the ::walkers
2176 dcmd. Some walkers operate on a global data structure and do not
2177 require a starting address. For example, walk the list of proc
2178 structures in the kernel. Other walkers operate on a specific data
2179 structure whose address must be specified explicitly. For example,
2180 given a pointer to an address space, walk the list of segments.
2181 When used interactively, the ::walk dcmd prints the address of each
2182 element of the data structure in the default base. The dcmd can
2183 also be used to provide a list of addresses for a pipeline. The
2184 walker name can use the backquote (`) scoping operator described
2185 under dcmd and Walker Name Resolution, above. If the optional vari‐
2186 able-name is specified, the specified variable is assigned the
2187 value returned at each step of the walk when mdb invokes the next
2188 stage of the pipeline.
2189 ::walkers
2192 List the available walkers and print a brief description for each
2194 one.
2195 ::whence [ -v ] name . . .
2198 ::which [ -v ] name ...
2199 Print the dmod that exports the specified dcmds and walkers. These
2201 dcmds can be used to determine which dmod is currently providing
2202 the global definition of the given dcmd or walker. Refer to the
2203 section on dcmd and Walker Name Resolution above for more informa‐
2204 tion on global name resolution. The -v option causes the dcmd to
2205 print the alternate definitions of each dcmd and walker in order of
2206 precedence.
2207 addr [ ,len ]::wp [ -/-dDestT ] [ -rwx ] [ -c cmd ]
2210 #sp;#sp; [ -n count ]
2211 addr [ ,len ] :a [ cmd . . . ]
2212 addr [ ,len ] :p [ cmd . . . ]
2213 addr [ ,len ] :w [ cmd . . . ]
2214 Set a watchpoint at the specified address. The length in bytes of
2216 the watched region can be set by specifying an optional repeat
2217 count preceding the dcmd. If no length is explicitly set, the
2218 default is one byte. The ::wp dcmd allows the watchpoint to be con‐
2219 figured to trigger on any combination of read (-r option), write
2220 (-w option), or execute (-x option) access. The -d, -D, -e, -s, -t,
2221 -T, -c, and -n options have the same meaning as they do for the
2222 ::evset dcmd. The :a dcmd sets a read access watchpoint at the
2223 specified address. The :p dcmd sets an execute access watchpoint at
2224 the specified address. The :w dcmd sets a write access watchpoint
2225 at the specified address. The arguments following the :a, :p, and
2226 :w dcmds are concatenated together to form the callback string. If
2227 this string contains meta-characters, it must be quoted.
2228 ::xdata
2231 List the external data buffers exported by the current target.
2233 External data buffers represent information associated with the
2234 target that can not be accessed through standard target facilities
2235 (that is, an address space, symbol table, or register set). These
2236 buffers can be consumed by dcmds; for more information, refer to
2237 the Solaris Modular Debugger Guide.
2238 :z
2241 Delete all event specifiers from the list of traced software
2243 events. Event specifiers can also be deleted using ::delete.
2244
2247 The following options are supported:
2248 -A Disables automatic loading of mdb modules. By default,
2250 mdb attempts to load debugger modules corresponding to
2251 the active shared libraries in a user process or core
2252 file, or to the loaded kernel modules in the live oper‐
2253 ating system or an operating system crash dump.
2254 -f Forces raw file debugging mode. By default, mdb attempts
2257 to infer whether the object and core file operands refer
2258 to a user executable and core dump or to a pair of oper‐
2259 ating system crash dump files. If the file type cannot
2260 be inferred, the debugger defaults to examining the
2261 files as plain binary data. The -f option forces mdb to
2262 interpret the arguments as a set of raw files to exam‐
2263 ine.
2264 -F Forcibly takes over the specified user process, if nec‐
2267 essary. By default, mdb refuses to attach to a user
2268 process that is already under the control of another
2269 debugging tool, such as truss(1). With the -F option,
2270 mdb attaches to these processes anyway. This can produce
2271 unexpected interactions between mdb and the other tools
2272 attempting to control the process.
2273 -I path Sets default path for locating macro files. Macro files
2276 are read using the $< or $<< dcmds. The path is a
2277 sequence of directory names delimited by colon (:) char‐
2278 acters. The -I include path and -L library path (see
2279 below) can also contain any of the following tokens:
2280 %i Expands to the current instruction set architec‐
2282 ture (ISA) name ('sparc', 'sparcv9', or 'i386').
2283 %o Expands to the old value of the path being modi‐
2286 fied. This is useful for appending or prepending
2287 directories to an existing path.
2288 %p Expands to the current platform string (either
2291 uname -i or the platform string stored in the
2292 process core file or crash dump).
2293 %r Expands to the pathname of the root directory. An
2296 alternate root directory can be specified using
2297 the -R option. If no -R option is present, the
2298 root directory is derived dynamically from the
2299 path to the mdb executable itself. For example, if
2300 /bin/mdb is executed, the root directory is /. If
2301 /net/hostname/bin/mdb were executed, the root
2302 directory would be derived as /net/hostname.
2303 %t Expands to the name of the current target. This is
2306 either be the literal string 'proc' (a user
2307 process or user process core file), 'kvm' (a ker‐
2308 nel crash dump or the live operating system), or
2309 'raw' (a raw file).
2310 The default include path for 32-bit mdb is:
2312 %r/usr/platform/%p/lib/adb:%r/usr/lib/adb
2314 The default include path for 64-bit mdb is:
2317 %r/usr/platform/%p/lib/adb/%i:%r/usr/lib/adb/%i
2319 -k Forces kernel debugging mode. By default, mdb attempts
2324 to infer whether the object and core file operands refer
2325 to a user executable and core dump, or to a pair of
2326 operating system crash dump files. The -k option forces
2327 mdb to assume these files are operating system crash
2328 dump files. If no object or core operand is specified,
2329 but the -k option is specified, mdb defaults to an
2330 object file of /dev/ksyms and a core file of /dev/kmem.
2331 Read access to /dev/kmem is restricted to group sys.
2332 Write access requires ALL privileges.
2333 -K Load kmdb, stop the live running operating system ker‐
2336 nel, and proceed to the kmdb debugger prompt. This
2337 option should only be used on the system console, as the
2338 subsequent kmdb prompt appears on the system console.
2339 -L path Sets default path for locating debugger modules. Modules
2342 are loaded automatically on startup or using the ::load
2343 dcmd. The path is a sequence of directory names delim‐
2344 ited by colon (:) characters. The -L library path can
2345 also contain any of the tokens shown for -I above.
2346 -m Disables demand-loading of kernel module symbols. By
2349 default, mdb processes the list of loaded kernel modules
2350 and performs demand loading of per-module symbol tables.
2351 If the -m option is specified, mdb does not attempt to
2352 process the kernel module list or provide per-module
2353 symbol tables. As a result, mdb modules corresponding to
2354 active kernel modules are not loaded on startup.
2355 -M Preloads all kernel module symbols. By default, mdb per‐
2358 forms demand-loading for kernel module symbols: the com‐
2359 plete symbol table for a module is read when an address
2360 is that module's text or data section is referenced.
2361 With the -M option, mdb loads the complete symbol table
2362 of all kernel modules during startup.
2363 -o option Enables the specified debugger option. If the -o form of
2366 the option is used, the specified option is disabled.
2367 Unless noted below, each option is off by default. mdb
2368 recognizes the following option arguments:
2369 adb Enables stricter adb(1) compat‐
2371 ibility. The prompt is set to
2372 the empty string and many mdb
2373 features, such as the output
2374 pager, is disabled.
2375 array_mem_limit=limit Sets the default limit on the
2378 number of array members that
2379 ::print displays. If limit is
2380 the special token none, all
2381 array members are displayed by
2382 default.
2383 array_str_limit=limit Sets the default limit on the
2386 number of characters that
2387 ::print attempts to display as
2388 an ASCII string when printing a
2389 char array. If limit is the
2390 special token none, the entire
2391 char array is displayed as a
2392 string by default.
2393 follow_exec_mode=mode Sets the debugger behavior for
2396 following an exec(2) system
2397 call. The mode should be one of
2398 the following named constants:
2399 ask If stdout is a termi‐
2401 nal device, the
2402 debugger stops after
2403 the exec(2) system
2404 call has returned and
2405 then prompts the user
2406 to decide whether to
2407 follow the exec or
2408 stop. If stdout is
2409 not a terminal
2410 device, the ask mode
2411 defaults to stop.
2412 follow The debugger follows
2415 the exec by automati‐
2416 cally continuing the
2417 target process and
2418 resetting all of its
2419 mappings and symbol
2420 tables based on the
2421 new executable. The
2422 follow behavior is
2423 discussed in more
2424 detail under NOTES,
2425 Interaction with
2426 Exec, below.
2427 stop The debugger stops
2430 following return from
2431 the exec system call.
2432 The stop behavior is
2433 discussed in more
2434 detail under NOTES,
2435 Interaction with
2436 Exec, below.
2437 follow_fork_mode=mode Sets the debugger behavior for
2441 following a fork(2), fork1(2),
2442 or vfork(2) system call. The
2443 mode should be one of the fol‐
2444 lowing named constants:
2445 ask If stdout is a termi‐
2447 nal device, the
2448 debugger stops after
2449 the fork(2) system
2450 call has returned and
2451 then prompts the user
2452 to decide whether to
2453 follow the parent or
2454 child. If stdout is
2455 not a terminal
2456 device, the ask mode
2457 defaults to parent.
2458 parent The debugger follows
2461 the parent process,
2462 and detaches from the
2463 child process and
2464 sets it running.
2465 child The debugger follows
2468 the child process,
2469 and detaches from the
2470 parent process and
2471 sets it running.
2472 ignoreeof The debugger does not exit when
2476 an EOF sequence (^D) is entered
2477 at the terminal. The ::quit
2478 dcmd must be used to quit.
2479 nostop Does not stop a user process
2482 when attaching to it when the
2483 -p option is specified or when
2484 the ::attach or :A dcmds are
2485 applied. The nostop behavior is
2486 described in more detail under
2487 NOTES, Process Attach and
2488 Release, below.
2489 pager Enables the output pager
2492 (default).
2493 repeatlast If a NEWLINE is entered as the
2496 complete command at the termi‐
2497 nal, mdb repeats the previous
2498 command with the current value
2499 of dot. This option is implied
2500 by -o adb.
2501 showlmid mdb provides support for symbol
2504 naming and identification in
2505 user applications that make use
2506 of link maps other than
2507 LM_ID_BASE and LM_ID_LDSO, as
2508 described in Symbol Name Reso‐
2509 lution, above. Symbols on link
2510 maps other than LM_ID_BASE or
2511 LM_ID_LDSO is shown as
2512 LMlmid`library`symbol, where
2513 lmid is the link-map ID in the
2514 default output radix (16). The
2515 user can optionally configure
2516 mdb to show the link-map ID
2517 scope of all symbols and
2518 objects, including those asso‐
2519 ciated with LM_ID_BASE and
2520 LM_ID_LDSO, by enabling the
2521 showlmid option. Built-in dcmds
2522 that deal with object file
2523 names displays link-map IDs
2524 according to the value of
2525 showlmid above, including ::nm,
2526 ::mappings, $m, and ::objects.
2527 -p pid Attaches to and stops the specified process-id. mdb uses
2531 the /proc/pid/object/a.out file as the executable file
2532 pathname.
2533 -P prompt Sets the command prompt. The default prompt is '> '.
2536 -R root Sets root directory for pathname expansion. By default,
2539 the root directory is derived from the pathname of the
2540 mdb executable itself. The root directory is substituted
2541 in place of the %r token during pathname expansion.
2542 -s distance Sets the symbol matching distance for address-to-symbol-
2545 name conversions to the specified distance. By default,
2546 mdb sets the distance to zero, which enables a smart-
2547 matching mode. Each ELF symbol table entry includes a
2548 value V and size S, representing the size of the func‐
2549 tion or data object in bytes. In smart mode, mdb matches
2550 an address A with the given symbol if A is in the range
2551 [ V, V + S ). If any non-zero distance is specified, the
2552 same algorithm is used, but S in the expression above is
2553 always the specified absolute distance and the symbol
2554 size is ignored.
2555 -S Suppresses processing of the user's ~/.mdbrc file. By
2558 default, mdb reads and processes the macro file .mdbrc
2559 if one is present in the user's home directory, as
2560 defined by $HOME. If the -S option is present, this file
2561 is not read.
2562 -u Forces user debugging mode. By default, mdb attempts to
2565 infer whether the object and core file operands refer to
2566 a user executable and core dump, or to a pair of operat‐
2567 ing system crash dump files. The -u option forces mdb to
2568 assume these files are not operating system crash dump
2569 files.
2570 -U Unload kmdb if it is loaded. You should unload kmdb when
2573 it is not in use to release the memory used by the ker‐
2574 nel debugger back to the free memory available to the
2575 operating system.
2576 -V version Sets disassembler version. By default, mdb attempts to
2579 infer the appropriate disassembler version for the debug
2580 target. The disassembler can be set explicitly using the
2581 -V option. The ::disasms dcmd lists the available disas‐
2582 sembler versions.
2583 -w Opens the specified object and core files for writing.
2586 -W Permit access to memory addresses that are mapped to I/O
2589 devices. By default, mdb does not allow such access
2590 because many devices do not provide hardware protection
2591 against invalid software manipulations. Use this option
2592 only when debugging device drivers and with caution.
2593 -y Sends explicit terminal initialization sequences for tty
2596 mode. Some terminals, such as cmdtool(1), require
2597 explicit initialization sequences to switch into a tty
2598 mode. Without this initialization sequence, terminal
2599 features such as standout mode can not be available to
2600 mdb.
2601
2604 The following operands are supported:
2605 object Specifies an ELF format object file to examine. mdb provides
2607 the ability to examine and edit ELF format executables
2608 (ET_EXEC), ELF dynamic library files (ET_DYN), ELF relocat‐
2609 able object files (ET_REL), and operating system unix.X sym‐
2610 bol table files.
2611 core Specifies an ELF process core file (ET_CORE), or an operating
2614 system crash dump vmcore.X file. If an ELF core file operand
2615 is provided without a corresponding object file, mdb attempts
2616 to infer the name of the executable file that produced the
2617 core using several different algorithms. If no executable is
2618 found, mdb still executes, but some symbol information can be
2619 unavailable.
2620 suffix Specifies the numerical suffix representing a pair of operat‐
2623 ing system crash dump files. For example, if the suffix is
2624 '3', mdb infers that it should examine the files 'unix.3' and
2625 'vmcore.3'. The string of digits are not interpreted as a
2626 suffix if an actual file of the same name is present in the
2627 current directory.
2628
2631 mdb processes all input files (including scripts, object files, core
2632 files, and raw data files) in a large file aware fashion. See large‐
2633 file(5) for more information about the processing of large files, which
2634 are files greater than or equal to 2 Gbytes (2^31 bytes).
2635
2637 The following exit values are returned:
2638 0 Debugger completed execution successfully.
2640 1 A fatal error occurred.
2643 2 Invalid command line options were specified.
2646
2649 HISTSIZE This variable is used to determine the maximum length of
2650 the command history list. If this variable is not present,
2651 the default length is 128.
2652 HOME This variable is used to determine the pathname of the
2655 user's home directory, where a .mdbrc file can reside. If
2656 this variable is not present, no .mdbrc processing occurs.
2657 SHELL This variable is used to determine the pathname of the
2660 shell used to process shell escapes requested using the !
2661 meta-character. If this variable is not present, /bin/sh is
2662 used.
2663
2666 $HOME/.mdbrc
2667 User mdb initialization file. The .mdbrc file, if present, is pro‐
2669 cessed after the debug target has been initialized, but before mod‐
2670 ule auto-loading is performed or any commands have been read from
2671 standard input.
2672 /dev/kmem
2675 Kernel virtual memory image device. This device special file is
2677 used as the core file when examining the live operating system.
2678 /dev/ksyms
2681 Kernel symbol table device. This device special file is used as the
2683 object file when examining the live operating system.
2684 /proc/pid/*
2687 Process information files that are read when examining and control‐
2689 ling user processes.
2690 /usr/lib/adb
2693 /usr/platform/platform-name/lib/adb
2694 Default directories for macro files that are read with the $< and
2696 $<< dcmds. platform-name is the name of the platform, derived
2697 either from information in a core file or crash dump, or from the
2698 current machine as if by uname -i (see uname(1)).
2699 /usr/lib/mdb
2702 /usr/platform/platform-name/lib/mdb
2703 Default directories for debugger modules that are loaded using the
2705 ::load dcmd. platform-name is the name of the platform, derived
2706 either from information in a core file or crash dump, or from the
2707 current machine as if by uname -i (see uname(1)).
2708
2711 See attributes(5) for descriptions of the following attributes:
2712 ┌─────────────────────────────┬─────────────────────────────┐
2717 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
2718 ├─────────────────────────────┼─────────────────────────────┤
2719 │Availability │SUNWmdb │
2720 ├─────────────────────────────┼─────────────────────────────┤
2721 │Interface Stability │Evolving │
2722 └─────────────────────────────┴─────────────────────────────┘
2723
2725 adb(1), cmdtool(1), gcore(1), proc(1), pgrep(1), ps(1), stty(1),
2726 truss(1), uname(1), coreadm(1M), dumpadm(1M), largefile(5),
2727 savecore(1M), exec(2), fork(2), _lwp_self(2), pipe(2), vfork(2),
2728 dlopen(3C), elf(3ELF), libc_db(3LIB), libkvm(3LIB), libthread(3LIB),
2729 signal(3C), signal.h(3HEAD), thr_self(3C), core(4), proc(4),
2730 attributes(5), largefile(5), threads(5), ksyms(7D), mem(7D)
2731 Linker and Libraries Guide
2734 Solaris Modular Debugger Guide
2737
2739 Use of the Error Recovery Mechanism
2740 The debugger and its dmods execute in the same address space, and thus
2741 it is quite possible that a buggy dmod can cause mdb to dump core or
2742 otherwise misbehave. The mdb resume capability, described above under
2743 Signal Handling, provides a limited recovery mechanism for these situa‐
2744 tions. However, it is not possible for mdb to know definitively whether
2745 the dmod in question has corrupted only its own state, or the debug‐
2746 ger's global state. Therefore a resume operation cannot be guaranteed
2747 to be safe, or to prevent a subsequent crash of the debugger. The
2748 safest course of action following a resume is to save any important
2749 debug information, and then quit and restart the debugger.
2750 Use of the Debugger to Modify the Live Operating System
2752 The use of the debugger to modify (that is, write to) the address space
2753 of live running operating system is extremely dangerous, and can result
2754 in a system panic in the event the user damages a kernel data struc‐
2755 ture.
2756
2758 Limitations on Examining Process Core Files
2759 mdb does not provide support for examining process core files that were
2760 generated by a release of Solaris preceding Solaris 2.6. When debugging
2761 core files generated by a release of Solaris 9 or an earlier release,
2762 symbol information might not be available. Since the text section and
2763 read-only data is not present in those core files, the symbol informa‐
2764 tion might not match the data present in the process at the time it
2765 dumped core. In releases later than Solaris 9, text sections and read-
2766 only data are included in core files by default. Users can configure
2767 their processes to exclude that information from core files using core‐
2768 adm(1M). Thus, the information presented by mdb for those core files
2769 can not match the data that was present at the time the process dumped
2770 core. Core files from Solaris x86 systems can not be examined on
2771 Solaris SPARC systems, and vice-versa.
2772 Limitations on Examining Crash Dump Files
2774 Crash dumps from Solaris 7 and earlier releases can only be examined
2775 with the aid of the libkvm from the corresponding operating system
2776 release. If a crash dump from one operating system release is examined
2777 using the dmods from a different operating system release, changes in
2778 the kernel implementation can prevent some dcmds or walkers from work‐
2779 ing properly. mdb issues a warning message if it detects this condi‐
2780 tion. Crash dumps from Solaris x86 systems can not be examined on
2781 Solaris SPARC systems, and vice-versa.
2782 Relationship Between 32-bit and 64-bit Debugger
2784 mdb provides support for debugging both 32-bit and 64-bit programs.
2785 Once it has examined the target and determined its data model, mdb
2786 automatically re-executes the mdb binary that has the same data model
2787 as the target, if necessary. This approach simplifies the task of writ‐
2788 ing debugger modules, because the modules that are loaded use the same
2789 data model as the primary target. Only the 64-bit debugger can be used
2790 to debug 64-bit target programs. The 64-bit debugger can only be used
2791 on a system that is running the 64-bit operating environment.
2792 The debugger can also need to re-execute itself when debugging a 32-bit
2795 process that execs a 64-bit process, or vice-versa. The handling of
2796 this situation is discussed in more detail under Interaction with Exec,
2797 below.
2798 Interaction with Exec
2800 When a controlled process performs a successful exec(2), the behavior
2801 of the debugger is controlled by the ::set -o follow_exec_mode option,
2802 as described above. If the debugger and victim process have the same
2803 data model, then the "stop" and "follow" modes determine whether mdb
2804 automatically continues the target or returns to the debugger prompt
2805 following the exec. If the debugger and victim process have a different
2806 data model, then the "follow" behavior causes mdb to automatically re-
2807 exec the mdb binary with the appropriate data model and to re-attach to
2808 the process, still stopped on return from the exec. Not all debugger
2809 state is preserved across this re-exec.
2810 If a 32-bit victim process execs a 64-bit program, then "stop" returns
2813 to the command prompt, but the debugger is no longer able to examine
2814 the process because it is now using the 64-bit data model. To resume
2815 debugging, execute the ::release -a dcmd, quit mdb, and then execute
2816 mdb -p pid to re-attach the 64-bit debugger to the process.
2817 If a 64-bit victim process execs a 32-bit program, then "stop" returns
2820 to the command prompt, but the debugger only provides limited capabili‐
2821 ties for examining the new process. All built-in dcmds work as adver‐
2822 tised, but loadable dcmds do not since they do not perform data model
2823 conversion of structures. The user should release and re-attach the
2824 debugger to the process as described above in order to restore full
2825 debugging capabilities.
2826 Interaction with Job Control
2828 If the debugger is attached to a process that is stopped by job control
2829 (that is, it stopped in response to SIGTSTP, SIGTTIN, or SIGTTOU), the
2830 process can not be able to be set running again when it is continued by
2831 a continue dcmd. If the victim process is a member of the same session
2832 (that is, it shares the same controlling terminal as mdb), mdb attempts
2833 to bring the associated process group to the foreground and to continue
2834 the process with SIGCONT to resume it from job control stop. When mdb
2835 is detached from such a process, it restores the process group to the
2836 background before exiting. If the victim process is not a member of the
2837 same session, mdb cannot safely bring the process group to the fore‐
2838 ground, so it continues the process with respect to the debugger, but
2839 the process remains stopped by job control. mdb prints a warning in
2840 this case, and the user must issue an "fg" command from the appropriate
2841 shell in order to resume the process.
2842 Process Attach and Release
2844 When mdb attaches to a running process, the process is stopped and
2845 remains stopped until one of the continue dcmds is applied, or the
2846 debugger quits. If the -o nostop option is enabled prior to attaching
2847 the debugger to a process with -p, or prior to issuing an ::attach or
2848 :A command, mdb attaches to the process but does not stop it. While the
2849 process is still running, it can be inspected as usual (albeit with
2850 inconsistent results) and breakpoints or other tracing flags might be
2851 enabled. If the :c or ::cont dcmds are executed while the process is
2852 running, the debugger waits for the process to stop. If no traced soft‐
2853 ware events occur, the user can send an interrupt (^C) after :c or
2854 ::cont to force the process to stop and return control to the debugger.
2855 mdb releases the current running process (if any) when the :R,
2858 ::release, :r, ::run, $q, or ::quit dcmds are executed, or when the
2859 debugger terminates as the result of an EOF or signal. If the process
2860 was originally created by the debugger using :r or ::run, it is
2861 forcibly terminated as if by SIGKILL when it is released. If the
2862 process was already running prior to attaching mdb to it, it is set
2863 running again when it is released. A process can be released and left
2864 stopped and abandoned using the ::release -a option.
2865 Symbolic Debugging Information
2867 The ::list, ::offsetof, ::print, and ::sizeof dcmds require that one or
2868 more load objects contain compressed symbolic debugging information
2869 suitable for use with mdb. This information is currently only available
2870 for certain Solaris kernel modules.
2871 Developer Information
2873 The Solaris Modular Debugger Guide provides a more detailed description
2874 of mdb features, as well as information for debugger module developers.
2875 The header file <sys/mdb_modapi.h> contains prototypes for the func‐
2878 tions in the MDB Module API, and the SUNWmdbdm package provides source
2879 code for an example module in the directory /usr/demo/mdb.
2880SunOS 5.11 30 Nov 2005 mdb(1)