Reformatting page.  Please Wait... done


User Commands                                              MDB(1)


NAME
     mdb - modular debugger

SYNOPSIS
     mdb [-fkmuwyAFKMSUW] [_o option] [-p pid] [-s distance]
          [-I path] [-L path] [-P prompt] [-R root]
          [-V dis-version] [object [core] | core | suffix]


DESCRIPTION
  Introduction
     The mdb utility  is  an  extensible  utility  for  low-level
     debugging  and editing of the live operating system, operat-
     ing system crash dumps, user processes,  user  process  core
     dumps,  and object files. For a more detailed description of
     mdb features, refer to the manual, Solaris Modular  Debugger
     Guide.


     Debugging is the process  of  analyzing  the  execution  and
     state  of  a  software  program  in order to remove defects.
     Traditional debugging tools provide facilities for execution
     control  so  that  programmers  can re-execute programs in a
     controlled environment and display the current state of pro-
     gram  data  or  evaluate  expressions in the source language
     used to develop the program.


     Unfortunately, these techniques are often inappropriate  for
     debugging complex software systems such as an operating sys-
     tem, where bugs might not be reproducible and program  state
     is  massive  and  distributed,  for programs that are highly
     optimized, have had their debug information removed, or  are
     themselves low-level debugging tools, or for customer situa-
     tions where the developer can only access post-mortem infor-
     mation.


     mdb  provides  a  completely  customizable  environment  for
     debugging  these programs and scenarios, including a dynamic
     module facility that programmers can use to implement  their
     own debugging commands to perform program-specific analysis.
     Each mdb module can  be  used  to  examine  the  program  in
     several different contexts, including live and post-mortem.

  Definitions
     The target is the program being inspected by  the  debugger.
     mdb  currently  provides  support for the following types of
     targets: user processes, user process core files,  the  live
     operating  system  (via /dev/kmem and /dev/ksyms), operating
     system crash dumps, user process images recorded  inside  an
     operating  system  crash  dump,  ELF  object  files, and raw


Illumos             Last change: Nov 30, 2005                   1


User Commands                                              MDB(1)


     binary files. Each target exports a standard set of  proper-
     ties, including one or more address spaces, one or more sym-
     bol tables, a set of load objects, and a set of threads that
     can be examined using the debugger commands described below.


     A debugger command, or dcmd (pronounced dee-command) in  mdb
     terminology,  is  a  routine in the debugger that can access
     any of the properties of the current target. mdb parses com-
     mands from standard input, and then executes the correspond-
     ing dcmds. Each dcmd can also accept a  list  of  string  or
     numerical  arguments,  as  shown  in  the syntax description
     below. mdb contains  a  set  of  built-in  dcmds,  described
     below,  that  are always available.  You can also extend the
     capabilities of mdb itself by writing  your  own  dcmds,  as
     described in the Solaris Modular Debugger Guide.


     A walker is a set of routines that describe how to walk,  or
     iterate,  through  the elements of a particular program data
     structure. A walker encapsulates the data structure's imple-
     mentation  from dcmds and from mdb itself. You can use walk-
     ers interactively, or use them as a primitive to build other
     dcmds  or  walkers.  As  with  dcmds,  you can extend mdb by
     implementing your own walkers as part of a debugger module.


     A debugger module, or dmod (pronounced dee-mod), is a dynam-
     ically loaded library containing a set of dcmds and walkers.
     During  initialization,   mdb   attempts   to   load   dmods
     corresponding  to  the  load  objects present in the target.
     You can subsequently load or unload dmods at any time  while
     running  mdb.   mdb  ships  with a set of standard dmods for
     debugging the Solaris kernel.  The Solaris Modular  Debugger
     Guide  contains  more  information  on  developing  your own
     debugger modules.


     A macro file is a text file containing a set of commands  to
     execute.   Macro  files  are  typically used to automate the
     process of displaying a simple data structure. mdb  provides
     complete  backward  compatibility for the execution of macro
     files written  for  adb(1),  and  the  Solaris  installation
     includes a set of macro files for debugging the Solaris ker-
     nel that can be used with either tool.

  Syntax
     The debugger processes  commands  from  standard  input.  If
     standard  input is a terminal, mdb provides terminal editing
     capabilities. mdb can also process commands from macro files
     and  from dcmd pipelines, described below. The language syn-
     tax is designed around the concept of computing the value of


Illumos             Last change: Nov 30, 2005                   2


User Commands                                              MDB(1)


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


     A metacharacter is one of the following characters:

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


     A blank is a TAB or a SPACE. A word is a sequence of charac-
     ters  separated  by  one  or more non-quoted metacharacters.
     Some of the metacharacters only function  as  delimiters  in
     certain  contexts,  as  described  below. An identifier is a
     sequence  of  letters,  digits,  underscores,  periods,   or
     backquotes  beginning  with a letter, underscore, or period.
     Identifiers are used as the  names  of  symbols,  variables,
     dcmds,  and walkers.  Commands are delimited by a NEWLINE or
     semicolon ( ; ).


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

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


     dcmds named by metacharacters or prefixed by a single $ or :
     are  provided  as built-in operators, and implement complete
     compatibility with the command  set  of  the  legacy  adb(1)
     utility.  Once a dcmd has been parsed, the /, \, ?, =, >, $,
     and :  characters are no longer recognized as metacharacters
     until the termination of the argument list.


     A simple-command is a dcmd followed by a sequence of zero or
     more  blank-separated  words.  The words are passed as argu-
     ments to the invoked dcmd, except as specified under Quoting
     and  Arithmetic  Expansion  below. Each dcmd returns an exit
     status that indicates it was either successful,  failed,  or
     was invoked with invalid arguments.


     A pipeline is a sequence of  one  or  more  simple  commands
     separated by |. Unlike the shell, dcmds in mdb pipelines are
     not executed as separate processes. After the  pipeline  has


Illumos             Last change: Nov 30, 2005                   3


User Commands                                              MDB(1)


     been  parsed,  each  dcmd  is  invoked in order from left to
     right.  Each  dcmd's  output  is  processed  and  stored  as
     described  under  dcmd  Pipelines  below. Once the left-hand
     dcmd is complete, its processed output is used as input  for
     the next dcmd in the pipeline. If any dcmd does not return a
     successful exit status, the pipeline is aborted.


     An expression is a sequence of words that  is  evaluated  to
     compute  a  64-bit  unsigned  integer  value.  The words are
     evaluated using the rules described under Arithmetic  Expan-
     sion below.

  Commands
     A command is one of the following:

     pipeline [! word ...] [ ; ]

         A simple-command or pipeline can be optionally  suffixed
         with  the  !   character,  indicating  that the debugger
         should open a pipe(2) and send the  standard  output  of
         the last dcmd in the mdb pipeline to an external process
         created by executing $SHELL -c followed  by  the  string
         formed by concatenating the words after the ! character.
         For more details, refer to Shell Escapes below.


     expression  pipeline [! word ...] [ ; ]

         A simple-command or pipeline can  be  prefixed  with  an
         expression.  Before execution of the pipeline, the value
         of dot (the variable denoted by ``.'')  is  set  to  the
         value of the expression.


     expression , expression pipeline  [!  word ...] [ ; ]

         A simple-command or pipeline can be  prefixed  with  two
         expressions. The first is evaluated to determine the new
         value of dot, and the second is evaluated to determine a
         repeat  count  for  the first dcmd in the pipeline. This
         dcmd is executed count times before the next dcmd in the
         pipeline  is executed.  The repeat count only applies to
         the first dcmd in the pipeline.


     , expression pipeline [! word ...] [ ; ]

         If the initial expression is omitted, dot is  not  modi-
         fied  but  the  first  dcmd  in the pipeline is repeated
         according to the value of the expression.


Illumos             Last change: Nov 30, 2005                   4


User Commands                                              MDB(1)


     expression [! word ...] [ ; ]

         A command can consist only of an arithmetic  expression.
         The  expression is evaluated and the dot variable is set
         to its value, and then the previous dcmd  and  arguments
         are executed using the new value of dot.


     expression, expression  [!  word ...] [ ; ]

         A command can consist  only  of  a  dot  expression  and
         repeat  count expression.  After dot is set to the value
         of the first expression, the previous dcmd and arguments
         are repeatedly executed the number of times specified by
         the value of the second expression.


     , expression   [! word ...] [ ; ]

         If the initial expression is omitted, dot is  not  modi-
         fied  but the previous dcmd and arguments are repeatedly
         executed the number of times specified by the  value  of
         the count expression.


     ! word ... [ ; ]

         If the command begins with the ! character, no dcmds are
         executed and the debugger simply executes $SHELL -c fol-
         lowed by the string formed by  concatenating  the  words
         after the ! character.


  Comments
     A word beginning with // causes that word and all the subse-
     quent characters up to a NEWLINE to be ignored.

  Arithmetic Expansion
     Arithmetic expansion is performed when  an  mdb  command  is
     preceded  by  an  optional  expression  representing a start
     address, or a start address and a repeat  count.  Arithmetic
     expansion can also be performed to compute a numerical argu-
     ment for a dcmd. An arithmetic expression can appear  in  an
     argument list enclosed in square brackets preceded by a dol-
     lar sign ($[ expression ]), and is replaced by the value  of
     the expression.


     Expressions can contain any of the following special words:

     integer
                           The specified integer  value.  Integer


Illumos             Last change: Nov 30, 2005                   5


User Commands                                              MDB(1)


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


     0[tT][0-9]+.[0-9]+
                           The specified decimal  floating  point
                           value,  converted  to its IEEE double-
                           precision floating  point  representa-
                           tion.


     'cccccccc'
                           The integer value computed by convert-
                           ing  each character to a byte equal to
                           its ASCII value. Up to  eight  charac-
                           ters  can  be specified in a character
                           constant. Characters are  packed  into
                           the  integer  in reverse order (right-
                           to-left) beginning at the least signi-
                           ficant byte.


     <identifier
                           The value of  the  variable  named  by
                           identifier.


     identifier
                           The value of the symbol named by iden-
                           tifier.


     (expression)
                           The value of expression.


     .
                           The value of dot.


     &
                           The most recent value of dot  used  to
                           execute a dcmd.


     +
                           The value of dot  incremented  by  the
                           current increment.


Illumos             Last change: Nov 30, 2005                   6


User Commands                                              MDB(1)


     ^
                           The value of dot  decremented  by  the
                           current increment.


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


     Unary operators are right associative and have  higher  pre-
     cedence than binary operators. The unary operators are:

     #expression
                            Logical negation.


     ~expression
                            Bitwise complement.


     -expression
                            Integer negation.


     %expression
                            The value of a pointer-sized quantity
                            at    the    object   file   location
                            corresponding  to   virtual   address
                            expression  in  the  target's virtual
                            address space.


     %/[csil]/expression
                            The value of a char, short,  int,  or
                            long-sized  quantity  at  the  object
                            file location corresponding  to  vir-
                            tual   address   expression   in  the
                            target's virtual address space.


     %/[1248]/expression
                            The value of a  one,  two,  four,  or
                            eight-byte  quantity  at  the  object
                            file location corresponding  to  vir-
                            tual   address   expression   in  the
                            target's virtual address space.


Illumos             Last change: Nov 30, 2005                   7


User Commands                                              MDB(1)


     *expression
                            The value of a pointer-sized quantity
                            at  virtual address expression in the
                            target's virtual address space.


     */[csil]/expression
                            The value of a char, short,  int,  or
                            long-sized    quantity   at   virtual
                            address expression  in  the  target's
                            virtual address space.


     */[1248]/expression
                            The value of a  one,  two,  four,  or
                            eight-byte    quantity   at   virtual
                            address expression  in  the  target's
                            virtual address space.


     Binary operators are left associative and  have  lower  pre-
     cedence than unary operators. The binary operators, in order
     of precedence from highest to lowest, are:

     *
           Integer multiplication.


     %
           Integer division.


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


     +
           Integer addition.


     -
           Integer subtraction.


     <<
           Bitwise shift left.


     >>
           Bitwise shift right.


Illumos             Last change: Nov 30, 2005                   8


User Commands                                              MDB(1)


     ==
           Logical equality.


     !=
           Logical inequality.


     &
           Bitwise AND.


     ^
           Bitwise exclusive OR.


     |
           Bitwise inclusive OR.


  Quoting
     Each metacharacter described above (see Syntax) terminates a
     word unless quoted. Characters can be quoted (forcing mdb to
     interpret each character as itself without any special  sig-
     nificance)  by  enclosing  them in a pair of single (' ') or
     double (" ") quote  marks.  A  single  quote  cannot  appear
     within  single  quotes. Inside double quotes, mdb recognizes
     the C programming language character escape sequences.

  Shell Escapes
     The ! character can be used to create a pipeline between  an
     mdb  command and the user's shell. If the $SHELL environment
     variable is set, mdb forks and execs this program for  shell
     escapes;  otherwise  /bin/sh  is  used. The shell is invoked
     with the -c option followed  by  a  string  formed  by  con-
     catenating  the words after the ! character. The ! character
     takes precedence over all other metacharacters, except semi-
     colon  (;) and NEWLINE. Once a shell escape is detected, the
     remaining characters up to the next semicolon or NEWLINE are
     passed  as is to the shell. The output of shell commands can
     not be piped to mdb dcmds.  Commands  executed  by  a  shell
     escape  have their output sent directly to the terminal, not
     to mdb.

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


Illumos             Last change: Nov 30, 2005                   9


User Commands                                              MDB(1)


     of  the  following attributes: read-only (cannot be modified
     by the user), persistent (cannot be unset by the user),  and
     tagged (user-defined indicator).


     The following variables are defined as persistent:

     0
               The most recent value printed using the /,  \,  ?,
               or = dcmd.


     9
               The most recent count used with the $< dcmd.


     b
               The virtual address of the base of the  data  sec-
               tion.


     d
               The size of the data section in bytes.


     e
               The virtual address of the entry point.


     m
               The initial bytes (magic number) of  the  target's
               primary object file, or zero if no object file has
               been read yet.


     t
               The size of the text section in bytes.


     hits
               The count of  the  number  of  times  the  matched
               software  event  specifier  has  been matched. See
               Event Callbacks, below.


     thread
               The thread identifier of the  current  representa-
               tive  thread.  The value of the identifier depends
               on the threading model used by the current target.
               See Thread Support, below.


Illumos             Last change: Nov 30, 2005                  10


User Commands                                              MDB(1)


     In addition, the mdb kernel and process targets  export  the
     current  values  of the representative thread's register set
     as named variables. The names of these variables  depend  on
     the target's platform and instruction set architecture.

  Symbol Name Resolution
     As explained in the Syntax description above, a symbol iden-
     tifier  present  in  an  expression context evaluates to the
     value of this symbol. The value typically denotes  the  vir-
     tual  address  of  the storage associated with the symbol in
     the target's virtual address space.  A  target  can  support
     multiple symbol tables including, but not limited to, a pri-
     mary executable  symbol  table,  a  primary  dynamic  symbol
     table, a run-time link-editor symbol table, and standard and
     dynamic symbol tables for each of a number of  load  objects
     (such  as  shared  libraries  in  a  user process, or kernel
     modules  in  the  Solaris  kernel).  The  target   typically
     searches  the  primary executable's symbol tables first, and
     then one or more of the other symbol tables. Notice that ELF
     symbol tables only contain entries for external, global, and
     static symbols; automatic symbols do not appear in the  sym-
     bol tables processed by mdb.


     Additionally, mdb provides  a  private  user-defined  symbol
     table  that  is  searched  prior to any of the target symbol
     tables. The private symbol table is initially empty, and can
     be manipulated using the ::nmadd and ::nmdel dcmds. The ::nm
     -P option can be used to display the contents of the private
     symbol  table.  The  private symbol table allows the user to
     create symbol definitions for program functions or data that
     were  either  missing  from the original program or stripped
     out. These definitions are then used whenever mdb converts a
     symbolic  name  to  an address, or an address to the nearest
     symbol.


     As targets contain multiple symbol tables, and  each  symbol
     table  can  include symbols from multiple object files, dif-
     ferent symbols with the same name can exist.  mdb  uses  the
     backquote (`) character as a symbol name scoping operator to
     allow the programmer to obtain the value of the desired sym-
     bol  in this situation. The programmer can specify the scope
     used to resolve a symbol name  as  either:  object`name,  or
     file`name,   or  object`file`name.   The  object  identifier
     refers to the name of a load  object.  The  file  identifier
     refers to the basename of a source file that has a symbol of
     type STT_FILE in the specified object's  symbol  table.  The
     object  identifier's  interpretation  depends  on the target
     type.


Illumos             Last change: Nov 30, 2005                  11


User Commands                                              MDB(1)


     The mdb kernel target expects object to specify the basename
     of a loaded kernel module. For example, the symbol name

       specfs`_init


     evaluates to the value of the _init  symbol  in  the  specfs
     kernel module.


     The mdb process target expects object to specify the name of
     the  executable  or  of a loaded shared library. It can take
     any of the following forms:

         1.   An  exact  match  (that  is,  a   full   pathname):
              /usr/lib/libc.so.1

         2.   An exact basename match: libc.so.1

         3.   An initial basename match up  to  a  ``.''  suffix:
              libc.so or libc

         4.   The literal string a.out is accepted  as  an  alias
              for the executable.


     The process target  also  accepts  any  of  the  four  forms
     described  above preceded by an optional link-map id (lmid).
     The lmid prefix is specified by an initial "LM" followed  by
     the  link-map  id  in  hexadecimal followed by an additional
     backquote. For example, the symbol name

       LM0`libc.so.1`_init


     evaluates to the value of the _init symbol in the  libc.so.1
     library  that  is  loaded  on  link-map  0 (LM_ID_BASE). The
     link-map specifier can be necessary to resolve symbol naming
     conflicts  in  the  event that the same library is loaded on
     more than one link map. For more information on  link  maps,
     refer  to  the  Linker  and  Libraries Guide and dlopen(3C).
     Link-map identifiers are displayed when symbols are  printed
     according   to  the  setting  of  the  showlmid  option,  as
     described under OPTIONS.


     In the case of a naming conflict between symbols and hexade-
     cimal  integer values, mdb attempts to evaluate an ambiguous


Illumos             Last change: Nov 30, 2005                  12


User Commands                                              MDB(1)


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

  dcmd and Walker Name Resolution
     As described earlier, each mdb dmod provides a set of  dcmds
     and walkers.  dcmds and walkers are tracked in two distinct,
     global namespaces. mdb also keeps track of a dcmd and walker
     namespace  associated  with  each  dmod.   Identically named
     dcmds or walkers within a given dmod are not allowed: a dmod
     with  this  type of naming conflict fails to load. Name con-
     flicts between dcmds or walkers  from  different  dmods  are
     allowed  in the global namespace. In the case of a conflict,
     the first dcmd or walker with that  particular  name  to  be
     loaded  is  given precedence in the global namespace. Alter-
     nate definitions are kept in  a  list  in  load  order.  The
     backquote character (`) can be used in a dcmd or walker name
     as a scoping operator to  select  an  alternate  definition.
     For  example,  if dmods m1 and m2 each provide a dcmd d, and
     m1 is loaded prior to m2, then:

     ::d
               Executes m1's definition of d.


     ::m1`d
               Executes m1's definition of d.


     ::m2`d
               Executes m2's definition of d.


     If module m1 were now unloaded, the next dcmd on the  global
     definition  list (m2`d) would be promoted to global visibil-
     ity. The current definition of  a  dcmd  or  walker  can  be
     determined using the ::which dcmd, described below. The glo-
     bal definition list can be displayed using  the  ::which  -v
     option.

  dcmd Pipelines
     dcmds can be composed into a pipeline using the |  operator.
     The purpose of a pipeline is to pass a list of values, typi-
     cally virtual addresses, from one dcmd or walker to another.
     Pipeline stages might be used to map a pointer from one type
     of data structure to  a  pointer  to  a  corresponding  data
     structure,  to  sort  a  list of addresses, or to select the


Illumos             Last change: Nov 30, 2005                  13


User Commands                                              MDB(1)


     addresses of structures with certain properties.


     mdb executes each dcmd in the pipeline in order from left to
     right. The leftmost dcmd is executed using the current value
     of dot, or using the value specified by an explicit  expres-
     sion  at  the  start  of  the  command. When a | operator is
     encountered, mdb creates a pipe (a  shared  buffer)  between
     the  output  of the dcmd to its left and the mdb parser, and
     an empty list of values. As the dcmd executes, its  standard
     output is placed in the pipe and then consumed and evaluated
     by the parser, as if mdb were reading this data  from  stan-
     dard  input. Each line must consist of an arithmetic expres-
     sion terminated by a NEWLINE or semicolon (;). The value  of
     the  expression is appended to the list of values associated
     with the pipe. If a syntax error is detected,  the  pipeline
     is aborted.


     When the dcmd to the left of a  |  operator  completes,  the
     list  of  values  associated  with  the pipe is then used to
     invoke the dcmd to the right of the  |  operator.  For  each
     value  in  the list, dot is set to this value and the right-
     hand dcmd is executed. Only the rightmost dcmd in the  pipe-
     line  has its output printed to standard output. If any dcmd
     in the pipeline produces output  to  standard  error,  these
     messages  are printed directly to standard error and are not
     processed as part of the pipeline.

  Signal Handling
     The debugger ignores the PIPE and QUIT signals. The INT sig-
     nal  aborts  the  command  that  is currently executing. The
     debugger intercepts and provides special  handling  for  the
     ILL,  TRAP, EMT, FPE, BUS, and SEGV signals. If any of these
     signals are generated  asynchronously  (that  is,  delivered
     from another process using kill(2)), mdb restores the signal
     to its default disposition and dump core. However, if any of
     these  signals  are  generated synchronously by the debugger
     process itself and a dcmd from an externally loaded dmod  is
     currently  executing,  and standard input is a terminal, mdb
     provides a menu of choices allowing the user to force a core
     dump, quit without producing a core dump, stop for attach by
     a debugger, or attempt to resume. The resume  option  aborts
     all  active  commands  and  unload  the  dmod whose dcmd was
     active at the time the fault occurred. It can then be subse-
     quently  re-loaded  by  the user. The resume option provides
     limited protection against buggy dcmds. Refer  to  WARNINGS,
     Use  of  the Error Recovery Mechanism, below for information
     about the risks associated with the resume option.

  Command Re-entry


Illumos             Last change: Nov 30, 2005                  14


User Commands                                              MDB(1)


     The text  of  the  last  HISTSIZE   (default  128)  commands
     entered  from a terminal device are saved in memory. The in-
     line editing facility, described next, provides key mappings
     for searching and fetching elements from the history list.

  In-line Editing
     If standard input is a terminal device,  mdb  provides  some
     simple  emacs-style facilities for editing the command line.
     The search, previous, and next commands in edit mode provide
     access  to the history list. Only strings, not patterns, are
     matched when searching. In the table below, the notation for
     control  characters  is  caret  (^)  followed by a character
     shown in upper case. The notation for escape sequences is M-
     followed  by a character. For example, M-f (pronounced meta-
     eff) is entered by depressing ESC followed  by  'f',  or  by
     depressing  Meta followed by 'f' on keyboards that support a
     Meta key. A command line is  committed  and  executed  using
     RETURN or NEWLINE. The edit commands are:

     ^F
                   Move cursor forward (right) one character.


     M-f
                   Move cursor forward one word.


     ^B
                   Move cursor backward (left) one character.


     M-b
                   Move cursor backward one word.


     ^A
                   Move cursor to start of line.


     ^E
                   Move cursor to end of line.


     ^D
                   Delete current character, if the current  line
                   is not empty. If the current line is empty, ^D
                   denotes EOF and the debugger exits.


     M-^H
                   (Meta-backspace) Delete previous word.


Illumos             Last change: Nov 30, 2005                  15


User Commands                                              MDB(1)


     ^K
                   Delete from the cursor to the end of the line.


     ^L
                   Clear the screen and reprint the current line.


     ^T
                   Transpose current character with next  charac-
                   ter.


     ^N
                   Fetch the next command from the history.  Each
                   time  ^N  is entered, the next command forward
                   in time is retrieved.


     ^P
                   Fetch the previous command from  the  history.
                   Each  time  ^P  is  entered,  the next command
                   backward in time is retrieved.


     ^R[string]
                   Search backward in the history for a  previous
                   command  line  containing  string.  The string
                   should be terminated by a RETURN  or  NEWLINE.
                   If  string  is  omitted,  the previous history
                   element containing the most recent  string  is
                   retrieved.


     The editing mode also interprets the following  user-defined
     sequences as editing commands. User defined sequences can be
     read or modified using the stty(1) command.

     erase
                User defined erase character (usually ^H or  ^?).
                Delete previous character.


     intr
                User defined interrupt  character  (usually  ^C).
                Abort the current command and print a new prompt.


     kill
                User defined kill character  (usually  ^U).  Kill
                the entire current command line.


Illumos             Last change: Nov 30, 2005                  16


User Commands                                              MDB(1)


     quit
                User defined quit character  (usually  ^\).  Quit
                the debugger.


     suspend
                User  defined  suspend  character  (usually  ^Z).
                Suspend the debugger.


     werase
                User defined word erase character  (usually  ^W).
                Erase the preceding word.


     On keyboards that support  an  extended  keypad  with  arrow
     keys, mdb interprets these keystrokes as editing commands:

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


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


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


     right-arrow
                    Move cursor forward one  character  (same  as
                    ^F).


  Output Pager
     mdb provides a built-in output pager. The  output  pager  is
     enabled if the debugger's standard output is a terminal dev-
     ice. Each time a command is executed, mdb pauses  after  one
     screenful of output is produced and displays a pager prompt:

        >> More [<space>, <cr>, q, n, c, a] ?


     The following key sequences are recognized by the pager:


Illumos             Last change: Nov 30, 2005                  17


User Commands                                              MDB(1)


     SPACE
                              Display the next screenful of  out-
                              put.


     a, A
                              Abort the current top-level command
                              and return to the prompt.


     c, C
                              Continue displaying output  without
                              pausing at each screenful until the
                              current top-level command  is  com-
                              plete.


     n, N, NEWLINE, RETURN
                              Display the next line of output.


     q, Q, ^C, ^\
                              Quit (abort) the current dcmd only.


  Formatting dcmds
     The /, \, ?, and = metacharacters are  used  to  denote  the
     special output formatting dcmds. Each of these dcmds accepts
     an argument list consisting of one or  more  format  charac-
     ters,  repeat  counts, or quoted strings. A format character
     is one of the ASCII characters shown  in  the  table  below.
     Format  characters are used to read and format data from the
     target. A repeat count is a positive integer  preceding  the
     format  character  that  is  always  interpreted  in base 10
     (decimal). A repeat  count  can  also  be  specified  as  an
     expression  enclosed in square brackets preceded by a dollar
     sign ($[ ]). A string argument must be enclosed  in  double-
     quotes  ("  "). No blanks are necessary between format argu-
     ments.


     The formatting dcmds are:

     /
           Display data from the target's virtual  address  space
           starting at the virtual address specified by dot.


     \
           Display data from the target's physical address  space
           starting at the physical address specified by dot.


Illumos             Last change: Nov 30, 2005                  18


User Commands                                              MDB(1)


     ?
           Display data from the  target's  primary  object  file
           starting  at the object file location corresponding to
           the virtual address specified by dot.


     =
           Display the value of dot itself in each of the  speci-
           fied  data formats. The = dcmd is therefore useful for
           converting between bases and performing arithmetic.


     In addition to dot, mdb keeps track of another global  value
     called  the increment. The increment represents the distance
     between dot and the address following all the data  read  by
     the  last formatting dcmd. For example, if a formatting dcmd
     is executed with dot equal to address A, and displays  a  4-
     byte  integer,  then after this dcmd completes, dot is still
     A, but the increment is set to 4. The + character (described
     under  Arithmetic Expansion above) would now evaluate to the
     value A + 4, and could be used to reset dot to  the  address
     of the next data object for a subsequent dcmd.


     Most format characters increase the value of  the  increment
     by the number of bytes corresponding to the size of the data
     format, shown in the table. The table of  format  characters
     can  be  displayed from within mdb using the ::formats dcmd.
     The format characters are:


     +   increment dot  by  the  count  (variable
         size)
     -   decrement dot  by  the  count  (variable
         size)
     B   hexadecimal int (1 byte)
     C   character using C character notation  (1
         byte)
     D   decimal signed int (4 bytes)
     E   decimal unsigned long long (8 bytes)
     F   double (8 bytes)
     G   octal unsigned long long (8 bytes)
     H   swap bytes and shorts (4 bytes)
     I   address  and  disassembled   instruction
         (variable size)
     J   hexadecimal long long (8 bytes)
     K   hexadecimal uintptr_t (4 or 8 bytes)
     N   newline
     O   octal unsigned int (4 bytes)
     P   symbol (4 or 8 bytes)


Illumos             Last change: Nov 30, 2005                  19


User Commands                                              MDB(1)


     Q   octal signed int (4 bytes)
     R   binary int (8 bytes)
     S   string using C string notation (variable
         size)
     T   horizontal tab
     U   decimal unsigned int (4 bytes)
     V   decimal unsigned int (1 byte)
     W   default radix unsigned int (4 bytes)
     X   hexadecimal int (4 bytes)
     Y   decoded time32_t (4 bytes)
     Z   hexadecimal long long (8 bytes)
     ^   decrement  dot  by  increment  *   count
         (variable size)
     a   dot as symbol+offset
     b   octal unsigned int (1 byte)
     c   character (1 byte)
     d   decimal signed short (2 bytes)
     e   decimal signed long long (8 bytes)
     f   float (4 bytes)
     g   octal signed long long (8 bytes)
     h   swap bytes (2 bytes)
     i   disassembled instruction (variable size)
     n   newline
     o   octal unsigned short (2 bytes)
     p   symbol (4 or 8 bytes)
     q   octal signed short (2 bytes)
     r   whitespace
     s   raw string (variable size)
     t   horizontal tab
     u   decimal unsigned short (2 bytes)
     v   decimal signed int (1 byte)
     w   default radix unsigned short (2 bytes)
     x   hexadecimal short (2 bytes)
     y   decoded time64_t (8 bytes)


     The /, \, and ? formatting dcmds can also be used  to  write
     to  the  target's  virtual  address  space, physical address
     space, or object file by specifying  one  of  the  following
     modifiers as the first format character, and then specifying
     a list of words that are either immediate values or  expres-
     sions  enclosed in square brackets preceded by a dollar sign
     ($[ ]).


     The write modifiers are:

     v
          Write the lowest byte of the value of  each  expression
          to  the  target  beginning at the location specified by
          dot.


Illumos             Last change: Nov 30, 2005                  20


User Commands                                              MDB(1)


     w
          Write the lowest two bytes of the value of each expres-
          sion  to the target beginning at the location specified
          by dot.


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


     Z
          Write the complete 8 bytes of the value of each expres-
          sion  to the target beginning at the location specified
          by dot.


     The /, \, and ? formatting dcmds can also be used to  search
     for  a  particular  integer  value  in  the target's virtual
     address space, physical  address  space,  and  object  file,
     respectively,  by  specifying one of the following modifiers
     as the first format character, and then specifying  a  value
     and  optional mask. The value and mask are each specified as
     either immediate values or expressions  enclosed  in  square
     brackets  preceded  by  a  dollar  sign.  If only a value is
     specified, mdb reads integers of the  appropriate  size  and
     stops  at  the  address  containing the matching value. If a
     value V and mask M are specified, mdb reads integers of  the
     appropriate size and stops at the address containing a value
     X where (X & M) == V. At the completion of the dcmd, dot  is
     updated to the address containing the match.  If no match is
     found, dot is left at the last address that was read.


     The search modifiers are:


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


     Notice that for both user and  kernel  targets,  an  address
     space  is  typically composed of a set of discontiguous seg-
     ments. It is not legal to read from an address that does not
     have  a corresponding segment. If a search reaches a segment
     boundary without finding a match, it aborts  when  the  read
     past the end of the segment boundary fails.


Illumos             Last change: Nov 30, 2005                  21


User Commands                                              MDB(1)


  Execution Control
     mdb provides facilities for controlling and tracing the exe-
     cution  of  a live running program. Currently, only the user
     process target provides support for execution  control.  mdb
     provides a simple model of execution control:  a target pro-
     cess can be started from within the debugger using ::run, or
     mdb can attach to an existing process using :A, ::attach, or
     the -p command-line option, as described below.  A  list  of
     traced  software  events  can be specified by the user. Each
     time a traced  event  occurs  in  the  target  process,  all
     threads  in  the  target stop, the thread that triggered the
     event is chosen as the representative  thread,  and  control
     returns to the debugger. Once the target program is set run-
     ning, control can be asynchronously returned to the debugger
     by  typing  the  user-defined interrupt character (typically
     ^C).


     A software event is a state transition in the target program
     that  is observed by the debugger. For example, the debugger
     can observe the transition of a program counter register  to
     a value of interest (a breakpoint) or the delivery of a par-
     ticular signal.


     A software event specifier is a description of  a  class  of
     software  events  that is used by the debugger to instrument
     the target program in order to  observe  these  events.  The
     ::events dcmd is used to list the software event specifiers.
     A set of standard properties is associated with  each  event
     specifier, as described under ::events, below.


     The debugger can observe a  variety  of  different  software
     events, including breakpoints, watchpoints, signals, machine
     faults, and system calls.  New  specifiers  can  be  created
     using ::bp, ::fltbp, ::sigbp, ::sysbp, or ::wp. Each specif-
     ier has an associated callback (an  mdb  command  string  to
     execute as if it had been typed at the command prompt) and a
     set of properties, as described below. Any number of specif-
     iers  for the same event can be created, each with different
     callbacks and properties. The current list of traced  events
     and the properties of the corresponding event specifiers can
     be displayed using the ::events dcmd.  The  event  specifier
     properties  are  defined  as  part of the description of the
     ::events and ::evset dcmds, below.


     The execution control built-in dcmds, described  below,  are
     always  available,  but  issues  an error message indicating
     they are not supported if applied to a target that does  not
     support  execution  control.  For more information about the


Illumos             Last change: Nov 30, 2005                  22


User Commands                                              MDB(1)


     interaction of exec, attach, release, and job  control  with
     debugger execution control, refer to NOTES, below.

  Event Callbacks
     The ::evset dcmd and event tracing dcmds allow you to  asso-
     ciate  an  event  callback  (using  the -c option) with each
     event  specifier.  The  event  callbacks  are  strings  that
     represent  mdb  commands  to  execute when the corresponding
     event occurs in the target. These commands are  executed  as
     if they had been typed at the command prompt. Before execut-
     ing each callback, the dot variable is set to the  value  of
     the  representative  thread's program counter and the "hits"
     variable is set to the number of times  this  specifier  has
     been matched, including the current match.


     If the event callbacks themselves contain one or  more  com-
     mands  to  continue  the  target  (for  example,  ::cont  or
     ::step), these commands do not immediately continue the tar-
     get  and  wait  for  it to stop again. Instead, inside of an
     event callback, the continue  dcmds  note  that  a  continue
     operation  is  now  pending,  and  then  return immediately.
     Therefore, if multiple dcmds are included in an event  call-
     back,  the  step or continue dcmd should be the last command
     specified. Following the execution of all  event  callbacks,
     the  target  immediately  resumes  execution if all matching
     event callbacks requested a continue.  If  conflicting  con-
     tinue  operations  are  requested,  the  operation  with the
     highest precedence determines what type of continue  occurs.
     The  order  of  precedence  from highest to lowest is: step,
     step-over (next), step-out, continue.

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


     The mdb kernel target exports the  virtual  address  of  the
     corresponding  internal  thread  structure as the identifier
     for a given thread. The Solaris Modular Debugger Guide  pro-
     vides  more  information on debugging support for threads in
     the Solaris kernel. The mdb process target  provides  proper
     support  for  examination  of  multi-threaded user processes


Illumos             Last change: Nov 30, 2005                  23


User Commands                                              MDB(1)


     that use the native lwp_* interfaces,  /usr/lib/libthread.so
     or  /usr/lib/lwp/libthread.so.  When  debugging  a live user
     process, mdb detects if a single threaded process dlopens or
     closes  libthread  and automatically adjusts its view of the
     threading model on-the-fly. The process target thread  iden-
     tifiers  corresponds  to  either  the  lwpid_t, thread_t, or
     pthread_t of the representative, depending on the  threading
     model used by the application.


     If mdb is debugging a user process  target  and  the  target
     makes  use  of  compiler-supported thread-local storage, mdb
     automatically evaluates symbol names  referring  to  thread-
     local storage to the address of the storage corresponding to
     the current representative thread. The ::tls  built-in  dcmd
     can  be  used to display the value of the symbol for threads
     other than the representative thread.

  Built-in dcmds
     mdb provides  a  set  of  built-in  dcmds  that  are  always
     defined.  Some of these dcmds are only applicable to certain
     targets: if a dcmd is not applicable to the current  target,
     it  fails  and  prints  a message indicating "command is not
     supported by current target". In many cases, mdb provides  a
     mnemonic  equivalent  (::identifier)  for  the legacy adb(1)
     dcmd  names.  For  example,  ::quit  is  provided   as   the
     equivalent  of  $q.  Programmers  who  are  experienced with
     adb(1) or who appreciate brevity or arcana can prefer the  $
     or  : forms of the built-ins. Programmers who are new to mdb
     might prefer the more verbose ::  form.  The  built-ins  are
     shown  in alphabetical order. If a $ or : form has a ::iden-
     tifier equivalent, it is shown underneath  the  ::identifier
     form. The built-in dcmds are:

     > variable-name
     >/modifier/variable-name

         Assign the value of dot to the specified named variable.
         Some variables are read-only and can not be modified. If
         the > is followed by a modifier character surrounded  by
         /  /,  then the value is modified as part of the assign-
         ment. The modifier characters are:

         c
              unsigned char quantity (1-byte)


         s
              unsigned short quantity (2-byte)


Illumos             Last change: Nov 30, 2005                  24


User Commands                                              MDB(1)


         i
              unsigned int quantity (4-byte)


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

         Notice that these  operators  do  not  perform  a  cast.
         Instead,  they  fetch  the specified number of low-order
         bytes (on  little-endian  architectures)  or  high-order
         bytes (big-endian architectures). Modifiers are provided
         for backwards compatibility;  the  mdb  */modifier/  and
         %/modifier/ syntax should be used instead.


     $< macro-name

         Read and execute commands from the specified macro file.
         The  filename  can  be  given as an absolute or relative
         path. If the filename is a simple name (that is,  if  it
         does  not  contain  a  '/'),  mdb searches for it in the
         macro file  include  path.  If  another  macro  file  is
         currently  being  processed,  this  file  is  closed and
         replaced with the new file.


     $<< macro-name

         Read and execute commands from the specified macro  file
         (as  with  $<),  but do not close the current open macro
         file.


     $?

         Print the process-ID and current signal of the target if
         it  is  a  user process or core file, and then print the
         general register set of the representative thread.


     [ address ] $C [ count ]

         Print a C stack backtrace, including stack frame pointer
         information.  If  the  dcmd  is  preceded by an explicit
         address, a backtrace beginning at  this  virtual  memory
         address   is  displayed.  Otherwise  the  stack  of  the
         representative thread is displayed. If an optional count
         value  is given as an argument, no more than count argu-
         ments are displayed for each stack frame in the output.


Illumos             Last change: Nov 30, 2005                  25


User Commands                                              MDB(1)


     [ base ] $d

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


     $e

         Print a list of all known external (global)  symbols  of
         type  object  or  function, the value of the symbol, and
         the first 4 (32-bit mdb) or 8 (64-bit mdb) bytes  stored
         at  this location in the target's virtual address space.
         The  ::nm  dcmd  provides  more  flexible  options   for
         displaying symbol tables.


     $P prompt-string

         Set the  prompt  to  the  specified  prompt-string.  The
         default prompt is '> '. The prompt can also be set using
         ::set -P or the -P command-line option.


     distance $s

         Get or set the symbol matching distance for  address-to-
         symbol-name  conversions.  The  symbol matching distance
         modes are  discussed  along  with  the  -s  command-line
         option  under  OPTIONS. The symbol matching distance can
         also be modified using the ::set -s option. If  no  dis-
         tance is specified, the current setting is displayed.


     $v

         Print a list of the named variables that  have  non-zero
         values. The ::vars dcmd provides other options for list-
         ing variables.


     width $w

         Set the output page width to the specified value.  Typi-
         cally,  this command is not necessary as mdb queries the
         terminal for its width and handles resize events.


     $W


Illumos             Last change: Nov 30, 2005                  26


User Commands                                              MDB(1)


         Re-open the target for writing, as if mdb had been  exe-
         cuted with the -w option on the command line. Write mode
         can also be enabled with the ::set -w option.


     [ pid ] ::attach  [ core | pid ]
     [ pid ] :A [  core | pid ]

         If the user process target  is  active,  attach  to  and
         debug  the  specified  process-ID or core file. The core
         file pathname should be specified as a string  argument.
         The  process-ID can be specified as the string argument,
         or as the value of the expression  preceding  the  dcmd.
         Recall  that the default base is hexadecimal, so decimal
         PIDs obtained using pgrep(1) or ps(1) should be preceded
         with "0t" when specified as expressions.


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

         Set a breakpoint at the specified  locations.  The  ::bp
         dcmd  sets a breakpoint at each address or symbol speci-
         fied, including an  optional  address  specified  by  an
         explicit  expression preceding the dcmd, and each string
         or immediate value following the dcmd. The arguments can
         either  be  symbol  names or immediate values denoting a
         particular virtual address of interest. If a symbol name
         is  specified,  it can refer to a symbol that cannot yet
         be evaluated in the target process. That is, it can con-
         sist  of  an  object  name  and  function name in a load
         object that has not yet been opened. In this  case,  the
         breakpoint  is  deferred and is not active in the target
         until an object matching the given name is  loaded.  The
         breakpoint is automatically enabled when the load object
         is opened. Breakpoints on symbols defined  in  a  shared
         library should always be set using a symbol name and not
         using an address expression, as the address can refer to
         the  corresponding  Procedure  Linkage Table (PLT) entry
         instead of the actual symbol definition. Breakpoints set
         on  PLT entries can be overwritten by the run-time link-
         editor when the PLT entry is  subsequently  resolved  to
         the  actual  symbol  definition. The -d, -D, -e, -s, -t,
         -T, -c, and -n options have the same meaning as they  do
         for the ::evset dcmd, as described below. If the :b form
         of the dcmd is used, a breakpoint is  only  set  at  the
         virtual  address  specified  by the expression preceding
         the dcmd. The arguments following the :b dcmd  are  con-
         catenated  together to form the callback string. If this
         string contains meta-characters, it must be quoted.


Illumos             Last change: Nov 30, 2005                  27


User Commands                                              MDB(1)


     ::cat filename ...

         Concatenate and display  files.  Each  filename  can  be
         specified  as  a relative or absolute pathname. The file
         contents are printed to standard  output,  but  are  not
         passed  to the output pager. This dcmd is intended to be
         used with the | operator; the programmer can initiate  a
         pipeline using a list of addresses stored in an external
         file.


     ::cont [ SIG ]
     :c [ SIG ]

         Suspend the debugger, continue the target  program,  and
         wait  for  it  to terminate or stop following a software
         event of interest. If  the  target  is  already  running
         because  the  debugger was attached to a running program
         with the -o nostop  option  enabled,  this  dcmd  simply
         waits for the target to terminate or stop after an event
         of interest. If an optional signal name or  number  (see
         signal.h(3HEAD)) is specified as an argument, the signal
         is immediately delivered to the target as part of resum-
         ing  its execution. If the SIGINT signal is traced, con-
         trol can be asynchronously returned to the  debugger  by
         typing  the  user-defined  interrupt  character (usually
         ^C).  This SIGINT signal is automatically cleared and is
         not  observed  by the target the next time it is contin-
         ued. If no target program is currently  running,  ::cont
         starts a new program running as if by ::run.


     address ::context
     address $p

         Context switch  to  the  specified  process.  A  context
         switch  operation  is  only  valid when using the kernel
         target. The  process  context  is  specified  using  the
         address  of  its  proc structure in the kernel's virtual
         address space. The special context address "0"  is  used
         to denote the context of the kernel itself. mdb can only
         perform a context switch when examining a crash dump  if
         the  dump  contains  the  physical  memory  pages of the
         specified  user  process  (as  opposed  to  just  kernel
         pages). The kernel crash dump facility can be configured
         to dump all pages or the pages of the current user  pro-
         cess using dumpadm(1M). The ::status dcmd can be used to
         display the contents of the current crash dump.

         When the user requests a context switch from the  kernel
         target,  mdb  constructs  a  new target representing the
         specified user process. Once the switch occurs, the  new


Illumos             Last change: Nov 30, 2005                  28


User Commands                                              MDB(1)


         target  interposes  its  dcmds at the global level: thus
         the / dcmd now formats and displays data from  the  vir-
         tual  address  space of the user process, the ::mappings
         dcmd displays the mappings in the address space  of  the
         user  process,  and  so  on.  The  kernel  target can be
         restored by executing 0::context.


     ::dcmds

         List the available dcmds and print a  brief  description
         for each one.


     [ address ] ::delete [ id | all ]
     [ address ] :d [ id | all ]

         Delete the event specifiers with the  given  id  number.
         The  id  number  argument  is  interpreted in decimal by
         default. If an optional address is  specified  preceding
         the  dcmd, all event specifiers that are associated with
         the given virtual address are deleted (for example,  all
         breakpoints  or  watchpoints affecting that address). If
         the special argument "all" is given, all  event  specif-
         iers are deleted, except those that are marked sticky (T
         flag). The ::events dcmd displays the  current  list  of
         event specifiers.


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

         Disassemble starting at or around the address  specified
         by  the  final argument, or the current value of dot. If
         the address matches the start of a known  function,  the
         entire  function  is disassembled. Otherwise, a "window"
         of instructions before and after the  specified  address
         is  printed  in  order  to  provide context. By default,
         instructions are read from the target's virtual  address
         space.  If  the  -f  option is present, instructions are
         read from the  target's  object  file  instead.  The  -f
         option  is  enabled  by  default  if the debugger is not
         currently attached to a  live  process,  core  file,  or
         crash   dump.  The  -w  option  can  be  used  to  force
         "window"-mode, even if the address is  the  start  of  a
         known  function.  The size of the window defaults to ten
         instructions; the number of instructions can  be  speci-
         fied explicitly using the -n option.


     ::disasms

         List the available disassembler modes. When a target  is


Illumos             Last change: Nov 30, 2005                  29


User Commands                                              MDB(1)


         initialized,  mdb  attempts  to  select  the appropriate
         disassembler mode. The user can change the mode  to  any
         of the modes listed using the ::dismode dcmd.


     ::dismode [ mode ]
     $V [ mode ]

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


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

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


     [ address ] ::dump [ -eqrstu ] [ -f|-p ]
     #sp;#sp;[ -g bytes ] [ -w paragraphs ]

         Print a hexadecimal and ASCII memory dump of the 16-byte
         aligned  region  of memory containing the address speci-
         fied by dot. If a repeat count is specified for  ::dump,
         this  is interpreted as a number of bytes to dump rather
         than a number of iterations. The ::dump dcmd also recog-
         nizes the following options:

         -e
                          Adjusts for endian-ness. The -e  option
                          assumes 4-byte words. The -g option can
                          be used  to  change  the  default  word
                          size.


         -f
                          Reads data from the object  file  loca-
                          tion corresponding to the given virtual
                          address instead of  from  the  target's
                          virtual address space. The -f option is
                          enabled by default if the  debugger  is
                          not  currently  attached to a live pro-
                          cess, core file, or crash dump.


Illumos             Last change: Nov 30, 2005                  30


User Commands                                              MDB(1)


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


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


         -q
                          Does not print an ASCII decoding of the
                          data.


         -r
                          Numbers lines  relative  to  the  start
                          address  instead  of  with the explicit
                          address  of  each  line.  This   option
                          implies the -u option.


         -s
                          Elides repeated lines.


         -t
                          Only reads from and displays  the  con-
                          tents   of   the  specified  addresses,
                          instead of reading and printing  entire
                          lines.


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


         -w paragraphs
                          Displays paragraphs  at  16-byte  para-
                          graphs  per line. The default number of
                          paragraphs is one.  The  maximum  value
                          accepted for -w is 16.


     ::echo [ string | value ...]


Illumos             Last change: Nov 30, 2005                  31


User Commands                                              MDB(1)


         Print the arguments separated by blanks  and  terminated
         by a NEWLINE to standard output. Expressions enclosed in
         $[ ] is  evaluated to a value and printed in the default
         base.


     ::eval command

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


     ::events [ -av ]
     $b [ -av ]

         Display the list  of  software  event  specifiers.  Each
         event  specifier is assigned a unique ID number that can
         be used to delete or modify it  at  a  later  time.  The
         debugger  can  also have its own internal events enabled
         for tracing.  These events are only be displayed if  the
         -a  option  is  present.  If the -v option is present, a
         more verbose  display,  including  the  reason  for  any
         specifier  inactivity,  are  shown.  Here is some sample
         output:

           > ::events
              ID S TA HT LM Description                      Action
           ----- - -- -- -- -------------------------------- ------
           [ 1 ] - T   1  0 stop on SIGINT                   -
           [ 2 ] - T   0  0 stop on SIGQUIT                  -
           [ 3 ] - T   0  0 stop on SIGILL                   -
            ...
           [ 11] - T   0  0 stop on SIGXCPU                  -
           [ 12] - T   0  0 stop on SIGXFSZ                  -
           [ 13] -     2  0 stop at libc`printf              ::echo printf
           >


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

         ID
                        The event specifier identifier. The iden-
                        tifier is shown in square brackets [ ] if
                        the specifier is enabled, in  parentheses
                        (  )  if the specifier is disabled, or in
                        angle brackets < > if the target  program
                        is  currently  stopped  on  an event that
                        matches the given specifier.


Illumos             Last change: Nov 30, 2005                  32


User Commands                                              MDB(1)


         S
                        The event specifier state. The  state  is
                        one of the following symbols:

                        -
                             The event specifier is idle. When no
                             target   program   is  running,  all
                             specifiers are idle. When the target
                             program  is running, a specifier can
                             be idle if it  cannot  be  evaluated
                             (for  example, a deferred breakpoint
                             in a shared object that is  not  yet
                             loaded).


                        +
                             The event specifier is active.  When
                             the  target  is continued, events of
                             this  type  is   detected   by   the
                             debugger.


                        *
                             The event specifier is  armed.  This
                             state   means  that  the  target  is
                             currently running with  instrumenta-
                             tion  for  this  type of event. This
                             state  is  only   visible   if   the
                             debugger  is  attached  to a running
                             program with the -o nostop option.


                        !
                             The event specifier  was  not  armed
                             due  to  an  operating system error.
                             The ::events -v option can  be  used
                             to  display  more  information about
                             the   reason   the   instrumentation
                             failed.


         TA
                        The  Temporary,  Sticky,  and   Automatic
                        event  specifier  properties. One or more
                        of the following symbols can be shown:

                        t
                             The event  specifier  is  temporary,
                             and  is  deleted  the  next time the
                             target stops, regardless of  whether
                             it is matched.


Illumos             Last change: Nov 30, 2005                  33


User Commands                                              MDB(1)


                        T
                             The event specifier is  sticky,  and
                             is not be deleted by ::delete all or
                             :z. The specifier can be deleted  by
                             explicitly  specifying its id number
                             to ::delete.


                        d
                             The event specifier is automatically
                             disabled when the hit count is equal
                             to the hit limit.


                        D
                             The event specifier is automatically
                             deleted  when the hit count is equal
                             to the hit limit.


                        s
                             The target automatically stops  when
                             the  hit  count  is equal to the hit
                             limit.


         HT
                        The  current  hit  count.   This   column
                        displays   the   number   of   times  the
                        corresponding software event has occurred
                        in  the target since the creation of this
                        event specifier.


         LM
                        The  current  hit  limit.   This   column
                        displays  the  limit  on the hit count at
                        which the auto-disable,  auto-delete,  or
                        auto-stop  behavior  takes  effect. These
                        behaviors can  be  configured  using  the
                        ::evset dcmd, described below.


         Description
                        A description of  the  type  of  software
                        event   that  is  matched  by  the  given
                        specifier.


         Action
                        The callback string to execute  when  the


Illumos             Last change: Nov 30, 2005                  34


User Commands                                              MDB(1)


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


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

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

         -d
               Disables the event specifier when  the  hit  count
               reaches  the  hit  limit.  If  the  -d form of the
               option is given, this behavior is  disabled.  Once
               an  event  specifier  is  disabled,  the  debugger
               removes  any  corresponding  instrumentation   and
               ignores  the  corresponding  software events until
               the specifier is subsequently re-enabled.  If  the
               -n  option  is  not present, the specifier is dis-
               abled immediately.


         -D
               Deletes the event specifier  when  the  hit  count
               reaches  the  hit  limit.  If  the  -D form of the
               option is given, this behavior is disabled. The -D
               option  takes  precedence  over the -d option. The
               hit limit can be configured using the -n option.


         -e
               Enables the event specifier. If the -e form of the
               option is given, the specifier is disabled.


         -s
               Stops  the  target  program  when  the  hit  count
               reaches  the  hit  limit.  If  the  -s form of the
               option is given, this behavior is disabled. The -s
               behavior  tells  the  debugger  to  act  as if the
               ::cont were issued following each execution of the
               specifier's  callback,  except  for the Nth execu-
               tion,  where  N  is  the  current  value  of   the
               specifier's  hit  limit.  The -s option takes pre-
               cedence over both the -D option and the -d option.


Illumos             Last change: Nov 30, 2005                  35


User Commands                                              MDB(1)


         -t
               Marks the event specifier as temporary.  Temporary
               specifiers are automatically deleted the next time
               the target stops, regardless of whether it stopped
               as the result of a software event corresponding to
               the given specifier. If the -t form of the  option
               is  given, the temporary marker is removed. The -t
               option takes precedence over the -T option.


         -T
               Marks  the  event  specifier  as  sticky.   Sticky
               specifiers  are not deleted by ::delete all or :z.
               They can be deleted by specifying the  correspond-
               ing  specifier  ID  as  an  explicit  argument  to
               ::delete. If the -T form of the option  is  given,
               the sticky property is removed. The default set of
               event specifiers are all initially marked sticky.


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


         -n
               Sets the current value of the hit limit to  count.
               If no hit limit is currently set and the -n option
               does not accompany -s or D, the hit limit  is  set
               to one.

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


     ::files
     $f

         Print a list of the known source files (symbols of  type
         STT_FILE present in the various target symbol tables).


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

         Trace the specified machine faults. The faults are iden-
         tified  using  an  optional  fault  number preceding the
         dcmd,  or  a  list  of  fault  names  or  numbers   (see
         <sys/fault.h>)  following  the dcmd. The -d, -D, -e, -s,
         -t, -T, -c, and -n options have the same meaning as they
         do for the ::evset dcmd.


Illumos             Last change: Nov 30, 2005                  36


User Commands                                              MDB(1)


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

         Print the floating-point register set of the representa-
         tive  thread.  If  a  thread  is specified, the floating
         point registers of that thread are displayed. The thread
         expression  should  be  one  of  the  thread identifiers
         described under Thread Support, above.


     ::formats

         List the available output format characters for use with
         the  /,  \,  ?,  and = formatting dcmds. The formats and
         their use is described under Formatting dcmds, above.


     ::grep command

         Evaluate the specified command string,  and  then  print
         the  old  value  of  dot if the new value of dot is non-
         zero. If the command contains whitespace or  metacharac-
         ters,  it must be quoted. The ::grep dcmd can be used in
         pipelines to filter a list of addresses.


     ::help [ dcmd-name ]

         With no arguments, the ::help dcmd prints a brief  over-
         view  of  the  help  facilities  available  in mdb. If a
         dcmd-name is specified, mdb prints a usage  summary  for
         that dcmd.


     signal :i

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


     $i

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


Illumos             Last change: Nov 30, 2005                  37


User Commands                                              MDB(1)


         the ::events dcmd.


     ::kill
     :k

         Forcibly terminate the target if it is a live user  pro-
         cess.  The  target  is also forcibly terminated when the
         debugger exits if it was created by the  debugger  using
         ::run.


     $l

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


     $L

         Print the LWPIDs of each LWP in the target, if the  tar-
         get is a user process.


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

         Walk through the elements of a linked list  data  struc-
         ture  and print the address of each element in the list.
         The address of the first element  in  the  list  can  be
         specified using an optional address. Otherwise, the list
         is assumed to start at the current  value  of  dot.  The
         type parameter must name a C struct or union type and is
         used to describe the type of the list elements  so  that
         mdb  can  read  in  objects of the appropriate size. The
         member parameter is used to name the member of type that
         contains  a pointer to the next list element. The ::list
         dcmd continues iterating until a NULL pointer is encoun-
         tered,  the  first  element is reached again (a circular
         list), or an error occurs while reading an  element.  If
         the  optional  variable-name is specified, the specified
         variable is assigned the value returned at each step  of
         the  walk when mdb invokes the next stage of a pipeline.
         The ::list dcmd can only be used with objects that  con-
         tain  symbolic  debugging  information  designed for use
         with mdb. Refer to NOTES,  Symbolic  Debugging  Informa-
         tion, below for more information.


     ::load [ -s ] module-name

         Load the specified dmod. The module name can be given as
         an absolute or relative path. If module-name is a simple


Illumos             Last change: Nov 30, 2005                  38


User Commands                                              MDB(1)


         name (that is, does not contain a '/'), mdb searches for
         it  in the module library path. Modules with conflicting
         names can not be loaded; the  existing  module  must  be
         unloaded first. If the -s option is present, mdb remains
         silent and not issue any error messages if the module is
         not found or could not be loaded.


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

         Enable or  disable  the  output  log.  mdb  provides  an
         interactive  logging  facility where both the input com-
         mands and standard output can be logged to a file  while
         still  interacting  with the user. The -e option enables
         logging to the specified file, or re-enables logging  to
         the  previous  log  file if no filename is given. The -d
         option disables logging. If the $> dcmd is used, logging
         is  enabled  if a filename argument is specified; other-
         wise, logging is disabled. If  the  specified  log  file
         already  exists,  mdb  appends any new log output to the
         file.


     ::map command

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


     [ address ] ::mappings [ name ]
     [  address ] $m [ name ]

         Print a list of each mapping  in  the  target's  virtual
         address space, including the address, size, and descrip-
         tion of each mapping. If the  dcmd  is  preceded  by  an
         address,  mdb  only  shows the mapping that contains the
         given address. If a string name argument is  given,  mdb
         only shows the mapping matching that description.


     ::next [ SIG ]
     :e [ SIG ]

         Step the target program one instruction, but  step  over
         subroutine  calls.  If an optional signal name or number
         (see signal.h(3HEAD)) is specified as an  argument,  the
         signal is immediately delivered to the target as part of


Illumos             Last change: Nov 30, 2005                  39


User Commands                                              MDB(1)


         resuming  its  execution.  If  no  target   program   is
         currently  running,  ::next starts a new program running
         as if by ::run and stop at the first instruction.


     [ address ] ::nm [ -DPdghnopuvx ] [ -t types ]
     #sp;#sp;[ -f format ] [ object ]

         Print the symbol tables associated with the current tar-
         get. If an optional address preceding the dcmd is speci-
         fied,  only  the  symbol  table  entry  for  the  symbol
         corresponding  to  address is displayed. If an object is
         specified, only the symbol table for this load object is
         displayed.  The  ::nm dcmd also recognizes the following
         options:

         -D
                                    Prints .dynsym (dynamic  sym-
                                    bol  table)  instead of .sym-
                                    tab.


         -P
                                    Prints  the  private   symbol
                                    table instead of .symtab.


         -d
                                    Prints value and size  fields
                                    in decimal.


         -g
                                    Prints only global symbols.


         -h
                                    Suppresses the header line.


         -n
                                    Sorts symbols by name.


         -o
                                    Prints value and size  fields
                                    in octal.


         -p
                                    Prints symbols as a series of
                                    ::nmadd commands. This option


Illumos             Last change: Nov 30, 2005                  40


User Commands                                              MDB(1)


                                    can be used with -P  to  pro-
                                    duce a macro file that can be
                                    subsequently  read  into  the
                                    debugger with $<.


         -u
                                    Prints  only  undefined  sym-
                                    bols.


         -v
                                    Sorts symbols by value.


         -x
                                    Prints value and size  fields
                                    in hexadecimal.


         -t type[,type ... ]
                                    Prints only  symbols  of  the
                                    specified  type(s). The valid
                                    type argument strings are:

                                    noty
                                            STT_NOTYPE


                                    objt
                                            STT_OBJECT


                                    func
                                            STT_FUNC


                                    sect
                                            STT_SECTION


                                    file
                                            STT_FILE


                                    comm
                                            STT_COMMON


                                    tls
                                            STT_TLS


Illumos             Last change: Nov 30, 2005                  41


User Commands                                              MDB(1)


                                    regi
                                            STT_SPARC_REGISTER


         -f format[,format ... ]
                                    Prints  only  the   specified
                                    symbol information. The valid
                                    format argument strings are:

                                    ndx
                                             symbol table index


                                    val
                                             symbol value


                                    size
                                             size in bytes


                                    type
                                             symbol type


                                    bind
                                             binding


                                    oth
                                             other


                                    shndx
                                             section index


                                    name
                                             symbol name


                                    ctype
                                             C  type  for  symbol
                                             (if known)


                                    obj
                                             object which defines
                                             symbol


Illumos             Last change: Nov 30, 2005                  42


User Commands                                              MDB(1)


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

         Add the specified symbol  name  to  the  private  symbol
         table. mdb provides a private, configurable symbol table
         that can be used to interpose  on  the  target's  symbol
         table,  as described under Symbol Name Resolution above.
         The ::nmadd dcmd also recognizes the following options:

         -e
               Sets the size of the symbol to end - value.


         -f
               Sets the type of the symbol to STT_FUNC.


         -o
               Sets the type of the symbol to STT_OBJECT.


         -s
               Sets the size of the symbol to size.


     ::nmdel name

         Delete the specified symbol name from the private symbol
         table.


     ::objects [ -v ]

         Print a map of the target's virtual address space, show-
         ing  only  those mappings that correspond to the primary
         mapping (usually the text section) of each of the  known
         load objects. The -v option displays the version of each
         load object. Version information is  not  available  for
         all  load objects. Load objects without version informa-
         tion is listed as having a version of "Unknown"  in  the
         output for the -v option.


     ::offsetof type member

         Print the offset of the specified member of  the  speci-
         fied type. The type should be the name of a C structure.
         The offset is printed in bytes, unless the member  is  a
         bit-field,  in  which  case the offset can be printed in
         bits. The output is always suffixed with the appropriate
         units  for  clarity. The type name can use the backquote
         (`)  scoping  operator  described  under   Symbol   Name


Illumos             Last change: Nov 30, 2005                  43


User Commands                                              MDB(1)


         Resolution,  above. The ::offsetof dcmd can only be used
         with objects that contain symbolic debugging information
         designed  for  use  with  mdb.  Refer to NOTES, Symbolic
         Debugging Information, below for more information.


     address ::print [ -aCdiLptx ] [ -c lim ]
     #sp;#sp;[ -l lim ] [ type [ member ... ] ]

         Print  the  data  structure  at  the  specified  virtual
         address  using  the  given  type  information.  The type
         parameter can name a C struct, union, enum,  fundamental
         integer type, or a pointer to any of these types. If the
         type name  contains  whitespace  (for  example,  "struct
         foo"),  it  must be enclosed in single or double quotes.
         The type name can use the backquote (`) scoping operator
         described  under  Symbol  Name Resolution, above. If the
         type is a structured type, the ::print dcmd  recursively
         prints  each  member of the struct or union. If the type
         argument  is  not  present  and  a  static   or   global
         STT_OBJECT  symbol  matches  the address, ::print infers
         the appropriate type automatically. If the type argument
         is  specified, it can be followed by an optional list of
         member expressions, in which case only those members and
         submembers  of the specified type are displayed. If type
         contains other structured types, each member string  can
         refer  to  a  sub-structure element by forming a list of
         member names separated by period ('.')  delimiters.  The
         ::print  dcmd can only be used with objects that contain
         symbolic debugging information  designed  for  use  with
         mdb.  Refer  to  NOTES,  Symbolic Debugging Information,
         below for more information. After  displaying  the  data
         structure, ::print increments dot by the size of type in
         bytes.

         If the -a option is present, the address of each  member
         is  displayed.  If  the  -p  option  is present, ::print
         interprets address as a physical memory address  instead
         of  a  virtual  memory  address.  If  the  -t  option is
         present, the type of each member is displayed. If the -d
         or -x options are present, all integers are displayed in
         decimal (-d) or hexadecimal (-x). By default, a  heuris-
         tic  is  used  to  determine  if  the  value  should  be
         displayed in decimal or hexadecimal. The number of char-
         acters  in  a character array that is read and displayed
         as a string can be limited with the -c option. If the -C
         option  is present, no limit is enforced.  The number of
         elements in a standard array that is read and  displayed
         can  be  limited with the -l option. If the -L option is
         present, no limit is enforced and all array elements are
         shown.  The default values for -c and -l can be modified
         using ::set or the -o command-line option  as  described


Illumos             Last change: Nov 30, 2005                  44


User Commands                                              MDB(1)


         under OPTIONS.

         If the -i option is  specified,  the  address  value  is
         interpreted  as  an  immediate  value to be printed. You
         must give a type with which to interpret the  value.  If
         the type is smaller than 64 bits, the immediate value is
         interpreted as if it were the size of the type.  The  -i
         option cannot be used in conjunction with the -p option.
         If the -a option is given, the addresses shown are  byte
         offsets starting at zero.


     ::quit
     $q

         Quit the debugger.


     [ thread ] ::regs
     [ thread ] $r

         Print the general purpose register set of the  represen-
         tative  thread.  If  a  thread is specified, the general
         purpose register set of that thread  is  displayed.  The
         thread  expression  should be one of the thread identif-
         iers described under Thread Support, above.


     ::release [ -a ]
     :R [ -a ]

         Release the previously attached process or core file. If
         the  -a  option  is present, the process is released and
         left stopped and abandoned. It can subsequently be  con-
         tinued  by prun(1) (see proc(1)) or it can be resumed by
         applying mdb or another debugger. By default, a released
         process  is forcibly terminated if it was created by mdb
         using ::run, or it is released and set running if it was
         attached  to  by  mdb  using  the -p option or using the
         ::attach or :A dcmds.


     ::run [ args . . . ]
     :r [ args . . . ]

         Start a new target program running  with  the  specified
         arguments and attach to it. The arguments are not inter-
         preted by the shell. If the debugger is already  examin-
         ing  a live running program, it first detaches from this
         program as if by ::release.


Illumos             Last change: Nov 30, 2005                  45


User Commands                                              MDB(1)


     ::set [ -wF ] [ -/-o option ] [ -s distance ] [ -I path ]
     #sp;#sp;[ -L path ] [ -P prompt ]

         Get or set  miscellaneous  debugger  properties.  If  no
         options  are specified, the current set of debugger pro-
         perties is displayed. The ::set dcmd recognizes the fol-
         lowing options:

         -F
               Forcibly takes over the  next  user  process  that
               ::attach  is  applied  to, as if mdb had been exe-
               cuted with the -F option on the command line.


         -I
               Sets the default path for  locating  macro  files.
               The  path  argument can contain any of the special
               tokens described for the  -I  command-line  option
               under OPTIONS.


         -L
               Sets  the  default  path  for  locating   debugger
               modules.  The path argument can contain any of the
               special tokens described for the  -I  command-line
               option under OPTIONS.


         -o
               Enables the specified debugger option. If  the  -o
               form  is  used, the option is disabled. The option
               strings are described along with the  -o  command-
               line option under OPTIONS.


         -P
               Sets the command prompt to  the  specified  prompt
               string.


         -s
               Sets the symbol matching distance to the specified
               distance.  Refer  to  the  description  of  the -s
               command-line option under OPTIONS for more  infor-
               mation.


         -w
               Re-opens the target for writing,  as  if  mdb  had
               been  executed  with  the -w option on the command
               line.


Illumos             Last change: Nov 30, 2005                  46


User Commands                                              MDB(1)


     ::showrev [ -pv ]

         Display  revision  information  for  the  hardware   and
         software.  With  no  options  specified,  general system
         information is displayed. The -v option displays version
         information  for all load objects, whereas the -p option
         displays the  version  information  only  for  the  load
         objects  that  have been installed on the system as part
         of a patch. Version information is not available for all
         load  objects.  Load objects without version information
         is omitted from the output for  the  -p  option  and  is
         listed  as  having  a version of "Unknown" in the output
         for the -v option.


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

         Trace delivery of the specified signals. The signals are
         identified using an optional signal number preceding the
         dcmd,  or  a  list  of  signal  names  or  numbers  (see
         signal.h(3HEAD)) following the dcmd. The -d, -D, -e, -s,
         -t, -T, -c, and -n options have the same meaning as they
         do  for  the ::evset dcmd. Initially, the set of signals
         that cause the process to  dump  core  by  default  (see
         signal.h(3HEAD)) and SIGINT are traced.


     ::sizeof type

         Print the size of the specified type in bytes. The  type
         parameter  can name a C struct, union, enum, fundamental
         integer type, or a pointer to any of  these  types.  The
         type  name  can  use  the backquote (`) scoping operator
         described  under  Symbol  Name  Resolution,  above.  The
         ::sizeof dcmd can only be used with objects that contain
         symbolic debugging information  designed  for  use  with
         mdb.  Refer  to  NOTES,  Symbolic Debugging Information,
         below for more information.


     [ address ] ::stack  [ count ]
     [  address ] $c [ count ]

         Print a C stack backtrace. If the dcmd is preceded by an
         explicit  address, a backtrace beginning at this virtual
         memory address is displayed. Otherwise the stack of  the
         representative thread is displayed. If an optional count
         value is given as an argument, no more than count  argu-
         ments are displayed for each stack frame in the output.


Illumos             Last change: Nov 30, 2005                  47


User Commands                                              MDB(1)


     ::status

         Print a summary of information related  to  the  current
         target.


     ::step [ over | out ] [ SIG ]
     :s [ SIG ]
     :u [ SIG ]

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


     [ syscall ] ::sysbp [ -/-dDestT ] [ -io ] [ -c cmd ]
     #sp;#sp;[ -n count ] syscall...

         Trace entry to or exit from the specified system  calls.
         The system calls are identified using an optional system
         call number preceding the dcmd, or a list of system call
         names  or  numbers  (see  <sys/syscall.h>) following the
         dcmd.  If the -i option is specified (the default),  the
         event  specifiers  trigger  on entry into the kernel for
         each system call. If the -o  option  is  specified,  the
         event  specifiers  trigger  on exit out from the kernel.
         The -d, -D, -e, -s, -t, -T, -c, and -n options have  the
         same meaning as they do for the ::evset dcmd.


     thread ::tls symbol

         Print the address  of  the  storage  for  the  specified
         thread-local  storage (TLS) symbol in the context of the
         specified thread. The thread expression should be one of
         the  thread  identifiers described under Thread Support,
         above. The symbol name can use any of the scoping opera-
         tors described under Symbol Name Resolution, above.


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


Illumos             Last change: Nov 30, 2005                  48


User Commands                                              MDB(1)


         Set attributes for named variables. If one or more vari-
         able  names  are  specified, they are defined and set to
         the value of dot. If  the  -t  option  is  present,  the
         user-defined  tag  associated with each variable is set.
         If the -t option is present, the tag is cleared.  If  no
         variable  names are specified, the list of variables and
         their values is printed.


     ::unload module-name

         Unload the specified dmod. The list of active dmods  can
         be  printed using the ::dmods dcmd. Built-in modules can
         not be unloaded. Modules that are busy (that is, provide
         dcmds that are currently executing) can not be unloaded.


     ::unset variable-name . . .

         Unset (remove) the specified variable(s) from  the  list
         of  defined  variables.   Some variables exported by mdb
         are marked as persistent, and can not be  unset  by  the
         user.


     ::vars [ -npt]

         Print a listing of named variables. If the -n option  is
         present,  the  output  is  restricted  to variables that
         currently have non-zero values.  If  the  -p  option  is
         present,  the  variables  are printed in a form suitable
         for re-processing by the debugger  using  the  $<  dcmd.
         This  option  can  be  used to record the variables to a
         macro file and then restore these values later.  If  the
         -t  option  is  present,  only  the tagged variables are
         printed.  Variables can be tagged using the -t option of
         the ::typeset dcmd.


     ::version

         Print the debugger version number.


     address ::vtop [-a as]

         Print the physical address  mapping  for  the  specified
         virtual  address,  if  possible. The ::vtop dcmd is only
         available when examining a kernel target, or  when  exa-
         mining  a user process inside a kernel crash dump (after
         a ::context dcmd has been issued).


Illumos             Last change: Nov 30, 2005                  49


User Commands                                              MDB(1)


         When examining a kernel target from the kernel  context,
         the -a option can be used to specify the address (as) of
         an alternate address space structure that should be used
         for the virtual to physical translation. By default, the
         kernel's address space is  used  for  translation.  This
         option  is available for active address spaces even when
         the dump content only contains kernel pages.


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

         Walk through the elements of a data structure using  the
         specified  walker.  The  available walkers can be listed
         using the ::walkers dcmd. Some walkers operate on a glo-
         bal  data  structure  and  do  not  require  a  starting
         address. For example, walk the list of  proc  structures
         in  the kernel. Other walkers operate on a specific data
         structure whose address must  be  specified  explicitly.
         For  example,  given a pointer to an address space, walk
         the list  of  segments.  When  used  interactively,  the
         ::walk  dcmd  prints  the address of each element of the
         data structure in the default base. The dcmd can also be
         used  to provide a list of addresses for a pipeline. The
         walker name can use the backquote (`)  scoping  operator
         described  under dcmd and Walker Name Resolution, above.
         If the optional variable-name is specified,  the  speci-
         fied  variable  is  assigned  the value returned at each
         step of the walk when mdb invokes the next stage of  the
         pipeline.


     ::walkers

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


     ::whence [ -v ] name . . .
     ::which [ -v ] name ...

         Print the dmod that  exports  the  specified  dcmds  and
         walkers. These dcmds can be used to determine which dmod
         is currently providing  the  global  definition  of  the
         given  dcmd  or walker. Refer to the section on dcmd and
         Walker Name Resolution above  for  more  information  on
         global name resolution. The -v option causes the dcmd to
         print the alternate definitions of each dcmd and  walker
         in order of precedence.


     addr [ ,len ]::wp  [ -/-dDestT ] [ -rwx ] [ -c cmd ]
     #sp;#sp; [ -n count ]


Illumos             Last change: Nov 30, 2005                  50


User Commands                                              MDB(1)


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

         Set a watchpoint at the specified address. The length in
         bytes  of the watched region can be set by specifying an
         optional repeat count preceding the dcmd. If  no  length
         is  explicitly  set,  the  default is one byte. The ::wp
         dcmd allows the watchpoint to be configured  to  trigger
         on  any  combination  of  read  (-r  option),  write (-w
         option), or execute (-x option) access. The -d, -D,  -e,
         -s,  -t, -T, -c, and -n options have the same meaning as
         they do for the ::evset dcmd. The :a dcmd  sets  a  read
         access  watchpoint at the specified address. The :p dcmd
         sets an  execute  access  watchpoint  at  the  specified
         address.  The  :w dcmd sets a write access watchpoint at
         the specified address. The arguments following  the  :a,
         :p,  and  :w dcmds are concatenated together to form the
         callback  string.  If   this   string   contains   meta-
         characters, it must be quoted.


     ::xdata

         List the external data buffers exported by  the  current
         target.  External  data  buffers  represent  information
         associated with the target  that  can  not  be  accessed
         through  standard target facilities (that is, an address
         space, symbol table, or register set). These buffers can
         be consumed by dcmds; for more information, refer to the
         Solaris Modular Debugger Guide.


     :z

         Delete all event specifiers  from  the  list  of  traced
         software  events.  Event  specifiers can also be deleted
         using ::delete.


OPTIONS
     The following options are supported:

     -A
                    Disables automatic loading of mdb modules. By
                    default,   mdb   attempts  to  load  debugger
                    modules corresponding to  the  active  shared
                    libraries  in a user process or core file, or
                    to the loaded  kernel  modules  in  the  live
                    operating system or an operating system crash
                    dump.


Illumos             Last change: Nov 30, 2005                  51


User Commands                                              MDB(1)


     -f
                    Forces raw file debugging mode.  By  default,
                    mdb  attempts to infer whether the object and
                    core file operands refer to a user executable
                    and  core dump or to a pair of operating sys-
                    tem crash dump files. If the file type cannot
                    be inferred, the debugger defaults to examin-
                    ing the files as plain binary data.   The  -f
                    option  forces mdb to interpret the arguments
                    as a set of raw files to examine.


     -F
                    Forcibly takes over the specified  user  pro-
                    cess,  if  necessary. By default, mdb refuses
                    to attach to a user process that  is  already
                    under  the control of another debugging tool,
                    such as truss(1). With  the  -F  option,  mdb
                    attaches  to these processes anyway. This can
                    produce unexpected interactions  between  mdb
                    and the other tools attempting to control the
                    process.


     -I path
                    Sets default path for locating  macro  files.
                    Macro  files  are  read  using  the $< or $<<
                    dcmds. The path is a  sequence  of  directory
                    names  delimited by colon (:) characters. The
                    -I include path  and  -L  library  path  (see
                    below)  can also contain any of the following
                    tokens:

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


                    %o
                          Expands to the old value  of  the  path
                          being  modified.  This  is  useful  for
                          appending or prepending directories  to
                          an existing path.


                    %p
                          Expands to the current platform  string
                          (either uname -i or the platform string
                          stored in  the  process  core  file  or
                          crash dump).


Illumos             Last change: Nov 30, 2005                  52


User Commands                                              MDB(1)


                    %r
                          Expands to the  pathname  of  the  root
                          directory.  An alternate root directory
                          can be specified using the  -R  option.
                          If  no  -R  option is present, the root
                          directory is derived  dynamically  from
                          the  path to the mdb executable itself.
                          For example, if /bin/mdb  is  executed,
                          the    root    directory   is   /.   If
                          /net/hostname/bin/mdb  were   executed,
                          the  root directory would be derived as
                          /net/hostname.


                    %t
                          Expands to the name of the current tar-
                          get.  This  is  either  be  the literal
                          string 'proc' (a user process  or  user
                          process  core  file),  'kvm'  (a kernel
                          crash dump or the live  operating  sys-
                          tem), or 'raw' (a raw file).

                    The default include path for 32-bit mdb is:

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


                    The default include path for 64-bit mdb is:

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


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


     -K
                    Load kmdb, stop the  live  running  operating
                    system   kernel,  and  proceed  to  the  kmdb


Illumos             Last change: Nov 30, 2005                  53


User Commands                                              MDB(1)


                    debugger prompt. This option should  only  be
                    used on the system console, as the subsequent
                    kmdb prompt appears on the system console.


     -L path
                    Sets  default  path  for  locating   debugger
                    modules.  Modules are loaded automatically on
                    startup or using the ::load dcmd. The path is
                    a  sequence  of  directory names delimited by
                    colon (:) characters. The -L library path can
                    also  contain  any of the tokens shown for -I
                    above.


     -m
                    Disables demand-loading of kernel module sym-
                    bols.  By  default, mdb processes the list of
                    loaded kernel  modules  and  performs  demand
                    loading  of  per-module symbol tables. If the
                    -m option is specified, mdb does not  attempt
                    to  process the kernel module list or provide
                    per-module symbol tables. As  a  result,  mdb
                    modules   corresponding   to   active  kernel
                    modules are not loaded on startup.


     -M
                    Preloads  all  kernel  module   symbols.   By
                    default, mdb performs demand-loading for ker-
                    nel module symbols: the complete symbol table
                    for  a module is read when an address is that
                    module's text or data section is  referenced.
                    With  the  -M  option, mdb loads the complete
                    symbol table of  all  kernel  modules  during
                    startup.


     -o option
                    Enables the specified debugger option. If the
                    -o  form of the option is used, the specified
                    option is disabled. Unless noted below,  each
                    option  is off by default. mdb recognizes the
                    following option arguments:

                    adb
                                             Enables     stricter
                                             adb(1)   compatibil-
                                             ity. The  prompt  is
                                             set   to  the  empty
                                             string and many  mdb
                                             features,   such  as


Illumos             Last change: Nov 30, 2005                  54


User Commands                                              MDB(1)


                                             the output pager, is
                                             disabled.


                    array_mem_limit=limit
                                             Sets   the   default
                                             limit  on the number
                                             of   array   members
                                             that         ::print
                                             displays.  If  limit
                                             is the special token
                                             none,   all    array
                                             members          are
                                             displayed         by
                                             default.


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


                    follow_exec_mode=mode
                                             Sets  the   debugger
                                             behavior for follow-
                                             ing an exec(2)  sys-
                                             tem  call.  The mode
                                             should be one of the
                                             following named con-
                                             stants:

                                             ask
                                                       If  stdout
                                                       is  a ter-
                                                       minal dev-
                                                       ice,   the
                                                       debugger
                                                       stops
                                                       after  the
                                                       exec(2)
                                                       system
                                                       call   has


Illumos             Last change: Nov 30, 2005                  55


User Commands                                              MDB(1)


                                                       returned
                                                       and   then
                                                       prompts
                                                       the   user
                                                       to  decide
                                                       whether to
                                                       follow the
                                                       exec    or
                                                       stop.   If
                                                       stdout  is
                                                       not a ter-
                                                       minal dev-
                                                       ice,   the
                                                       ask   mode
                                                       defaults
                                                       to stop.


                                             follow
                                                       The
                                                       debugger
                                                       follows
                                                       the   exec
                                                       by
                                                       automati-
                                                       cally con-
                                                       tinuing
                                                       the target
                                                       process
                                                       and reset-
                                                       ting   all
                                                       of     its
                                                       mappings
                                                       and symbol
                                                       tables
                                                       based   on
                                                       the    new
                                                       execut-
                                                       able.  The
                                                       follow
                                                       behavior
                                                       is    dis-
                                                       cussed  in
                                                       more
                                                       detail
                                                       under
                                                       NOTES,
                                                       Interac-
                                                       tion  with
                                                       Exec,
                                                       below.


Illumos             Last change: Nov 30, 2005                  56


User Commands                                              MDB(1)


                                             stop
                                                       The
                                                       debugger
                                                       stops fol-
                                                       lowing
                                                       return
                                                       from   the
                                                       exec  sys-
                                                       tem  call.
                                                       The   stop
                                                       behavior
                                                       is    dis-
                                                       cussed  in
                                                       more
                                                       detail
                                                       under
                                                       NOTES,
                                                       Interac-
                                                       tion  with
                                                       Exec,
                                                       below.


                    follow_fork_mode=mode
                                             Sets  the   debugger
                                             behavior for follow-
                                             ing    a    fork(2),
                                             fork1(2),         or
                                             vfork(2)      system
                                             call.    The    mode
                                             should be one of the
                                             following named con-
                                             stants:

                                             ask
                                                       If  stdout
                                                       is  a ter-
                                                       minal dev-
                                                       ice,   the
                                                       debugger
                                                       stops
                                                       after  the
                                                       fork(2)
                                                       system
                                                       call   has
                                                       returned
                                                       and   then
                                                       prompts
                                                       the   user
                                                       to  decide
                                                       whether to


Illumos             Last change: Nov 30, 2005                  57


User Commands                                              MDB(1)


                                                       follow the
                                                       parent  or
                                                       child.  If
                                                       stdout  is
                                                       not a ter-
                                                       minal dev-
                                                       ice,   the
                                                       ask   mode
                                                       defaults
                                                       to parent.


                                             parent
                                                       The
                                                       debugger
                                                       follows
                                                       the parent
                                                       process,
                                                       and
                                                       detaches
                                                       from   the
                                                       child pro-
                                                       cess   and
                                                       sets    it
                                                       running.


                                             child
                                                       The
                                                       debugger
                                                       follows
                                                       the  child
                                                       process,
                                                       and
                                                       detaches
                                                       from   the
                                                       parent
                                                       process
                                                       and   sets
                                                       it    run-
                                                       ning.


                    ignoreeof
                                             The  debugger   does
                                             not exit when an EOF
                                             sequence   (^D)   is
                                             entered  at the ter-
                                             minal.  The   ::quit
                                             dcmd must be used to
                                             quit.


Illumos             Last change: Nov 30, 2005                  58


User Commands                                              MDB(1)


                    nostop
                                             Does not stop a user
                                             process when attach-
                                             ing to it  when  the
                                             -p  option is speci-
                                             fied  or  when   the
                                             ::attach or :A dcmds
                                             are   applied.   The
                                             nostop  behavior  is
                                             described  in   more
                                             detail  under NOTES,
                                             Process  Attach  and
                                             Release, below.


                    pager
                                             Enables  the  output
                                             pager (default).


                    repeatlast
                                             If  a   NEWLINE   is
                                             entered  as the com-
                                             plete command at the
                                             terminal,        mdb
                                             repeats the previous
                                             command   with   the
                                             current   value   of
                                             dot.  This option is
                                             implied by -o adb.


                    showlmid
                                             mdb provides support
                                             for   symbol  naming
                                             and   identification
                                             in user applications
                                             that  make  use   of
                                             link maps other than
                                             LM_ID_BASE       and
                                             LM_ID_LDSO,       as
                                             described in  Symbol
                                             Name     Resolution,
                                             above.  Symbols   on
                                             link maps other than
                                             LM_ID_BASE        or
                                             LM_ID_LDSO  is shown
                                             as
                                             LMlmid`library`symbol,
                                             where  lmid  is  the
                                             link-map  ID  in the
                                             default output radix


Illumos             Last change: Nov 30, 2005                  59


User Commands                                              MDB(1)


                                             (16).  The  user can
                                             optionally configure
                                             mdb   to   show  the
                                             link-map ID scope of
                                             all    symbols   and
                                             objects,   including
                                             those     associated
                                             with LM_ID_BASE  and
                                             LM_ID_LDSO,  by ena-
                                             bling  the  showlmid
                                             option.     Built-in
                                             dcmds that deal with
                                             object   file  names
                                             displays    link-map
                                             IDs according to the
                                             value  of   showlmid
                                             above,     including
                                             ::nm,    ::mappings,
                                             $m, and ::objects.


     -p pid
                    Attaches to and stops the specified  process-
                    id.  mdb uses the /proc/pid/object/a.out file
                    as the executable file pathname.


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


     -R root
                    Sets root directory for  pathname  expansion.
                    By  default,  the  root  directory is derived
                    from  the  pathname  of  the  mdb  executable
                    itself.  The root directory is substituted in
                    place of the %r token during pathname  expan-
                    sion.


     -s distance
                    Sets  the  symbol   matching   distance   for
                    address-to-symbol-name   conversions  to  the
                    specified distance. By default, mdb sets  the
                    distance  to  zero,  which  enables  a smart-
                    matching mode. Each ELF  symbol  table  entry
                    includes  a  value V and size S, representing
                    the size of the function or  data  object  in
                    bytes.  In smart mode, mdb matches an address
                    A with the given symbol if A is in the  range


Illumos             Last change: Nov 30, 2005                  60


User Commands                                              MDB(1)


                    [  V,  V  +  S ). If any non-zero distance is
                    specified, the same algorithm is used, but  S
                    in  the expression above is always the speci-
                    fied absolute distance and the symbol size is
                    ignored.


     -S
                    Suppresses processing of the user's  ~/.mdbrc
                    file. By default, mdb reads and processes the
                    macro file .mdbrc if one is  present  in  the
                    user's  home  directory, as defined by $HOME.
                    If the -S option is present, this file is not
                    read.


     -u
                    Forces user debugging mode. By  default,  mdb
                    attempts to infer whether the object and core
                    file operands refer to a user executable  and
                    core  dump,  or to a pair of operating system
                    crash dump files. The -u option forces mdb to
                    assume  these  files are not operating system
                    crash dump files.


     -U
                    Unload kmdb  if  it  is  loaded.  You  should
                    unload  kmdb when it is not in use to release
                    the memory used by the kernel  debugger  back
                    to the free memory available to the operating
                    system.


     -V version
                    Sets disassembler version.  By  default,  mdb
                    attempts  to  infer the appropriate disassem-
                    bler  version  for  the  debug  target.   The
                    disassembler  can be set explicitly using the
                    -V  option.  The  ::disasms  dcmd  lists  the
                    available disassembler versions.


     -w
                    Opens the specified object and core files for
                    writing.


     -W
                    Permit access to memory  addresses  that  are
                    mapped  to  I/O devices. By default, mdb does
                    not allow such access because many devices do


Illumos             Last change: Nov 30, 2005                  61


User Commands                                              MDB(1)


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


     -y
                    Sends   explicit   terminal    initialization
                    sequences  for tty mode. Some terminals, such
                    as cmdtool(1), require  explicit  initializa-
                    tion  sequences  to  switch  into a tty mode.
                    Without this initialization sequence,  termi-
                    nal features such as standout mode can not be
                    available to mdb.


OPERANDS
     The following operands are supported:

     object
               Specifies an ELF format object  file  to  examine.
               mdb  provides  the ability to examine and edit ELF
               format executables (ET_EXEC), ELF dynamic  library
               files   (ET_DYN),  ELF  relocatable  object  files
               (ET_REL), and operating system unix.X symbol table
               files.


     core
               Specifies an ELF process core file  (ET_CORE),  or
               an  operating  system crash dump vmcore.X file. If
               an ELF core file operand  is  provided  without  a
               corresponding  object  file, mdb attempts to infer
               the name of the executable file that produced  the
               core  using  several  different algorithms.  If no
               executable is found, mdb still executes, but  some
               symbol information can be unavailable.


     suffix
               Specifies the numerical suffix representing a pair
               of operating system crash dump files. For example,
               if the suffix is '3', mdb infers  that  it  should
               examine  the  files  'unix.3'  and 'vmcore.3'. The
               string of digits are not interpreted as  a  suffix
               if  an  actual file of the same name is present in
               the current directory.


USAGE
     mdb processes all input  files  (including  scripts,  object
     files, core files, and raw data files) in a large file aware


Illumos             Last change: Nov 30, 2005                  62


User Commands                                              MDB(1)


     fashion. See largefile(5) for  more  information  about  the
     processing  of  large files, which are files greater than or
     equal to 2 Gbytes (2^31 bytes).

EXIT STATUS
     The following exit values are returned:

     0
          Debugger completed execution successfully.


     1
          A fatal error occurred.


     2
          Invalid command line options were specified.


ENVIRONMENT VARIABLES
     HISTSIZE
                 This variable is used to determine  the  maximum
                 length  of  the  command  history  list. If this
                 variable is not present, the default  length  is
                 128.


     HOME
                 This variable is used to determine the  pathname
                 of  the  user's  home  directory, where a .mdbrc
                 file  can  reside.  If  this  variable  is   not
                 present, no .mdbrc processing occurs.


     SHELL
                 This variable is used to determine the  pathname
                 of  the  shell  used  to  process  shell escapes
                 requested using the !  meta-character.  If  this
                 variable is not present, /bin/sh is used.


FILES
     $HOME/.mdbrc

         User  mdb  initialization  file.  The  .mdbrc  file,  if
         present,  is  processed  after the debug target has been
         initialized, but before module auto-loading is performed
         or any commands have been read from standard input.


     /dev/kmem


Illumos             Last change: Nov 30, 2005                  63


User Commands                                              MDB(1)


         Kernel virtual memory image device. This device  special
         file  is  used  as the core file when examining the live
         operating system.


     /dev/ksyms

         Kernel symbol table device. This device special file  is
         used  as the object file when examining the live operat-
         ing system.


     /proc/pid/*

         Process information files that are read  when  examining
         and controlling user processes.


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

         Default directories for macro files that are  read  with
         the  $<  and $<< dcmds. platform-name is the name of the
         platform, derived either from information in a core file
         or  crash  dump,  or  from  the current machine as if by
         uname -i (see uname(1)).


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

         Default directories for debugger modules that are loaded
         using  the ::load dcmd. platform-name is the name of the
         platform, derived either from information in a core file
         or  crash  dump,  or  from  the current machine as if by
         uname -i (see uname(1)).


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


     _______________________________________
    |   ATTRIBUTE TYPE   |  ATTRIBUTE VALUE|
    |____________________|_________________|
    | Interface Stability|  Evolving       |
    |____________________|_________________|


Illumos             Last change: Nov 30, 2005                  64


User Commands                                              MDB(1)


SEE ALSO
     adb(1),  cmdtool(1),  gcore(1),  proc(1),  pgrep(1),  ps(1),
     stty(1),  truss(1)uname(1)coreadm(1M)dumpadm(1M), lar-
     gefile(5),  savecore(1M),  exec(2),  fork(2),  _lwp_self(2),
     pipe(2),  vfork(2),  dlopen(3C),  elf(3ELF),  libc_db(3LIB),
     libkvm(3LIB)libthread(3LIB)signal(3C),  signal.h(3HEAD),
     thr_self(3C)core(4)proc(4)attributes(5)largefile(5),
     threads(5)ksyms(7D)mem(7D)


     Linker and Libraries Guide


     Solaris Modular Debugger Guide

WARNINGS
  Use of the Error Recovery Mechanism
     The debugger and its  dmods  execute  in  the  same  address
     space,  and  thus it is quite possible that a buggy dmod can
     cause mdb to dump  core  or  otherwise  misbehave.  The  mdb
     resume  capability,  described  above under Signal Handling,
     provides a limited recovery mechanism for these  situations.
     However,  it  is  not  possible for mdb to know definitively
     whether the dmod in question  has  corrupted  only  its  own
     state,  or  the debugger's global state.  Therefore a resume
     operation cannot be guaranteed to be safe, or to  prevent  a
     subsequent  crash  of  the  debugger.  The  safest course of
     action following a resume is to  save  any  important  debug
     information, and then quit and restart the debugger.

  Use of the Debugger to Modify the Live Operating System
     The use of the debugger to modify (that is,  write  to)  the
     address  space of live running operating system is extremely
     dangerous, and can result in a system panic in the event the
     user damages a kernel data structure.

NOTES
  Limitations on Examining Process Core Files
     mdb does not provide  support  for  examining  process  core
     files  that were generated by a release of Solaris preceding
     Solaris 2.6.  When  debugging  core  files  generated  by  a
     release  of Solaris 9 or an earlier release, symbol informa-
     tion might not be available.  Since  the  text  section  and
     read-only  data is not present in those core files, the sym-
     bol information might not match the data present in the pro-
     cess  at  the  time  it  dumped core. In releases later than
     Solaris 9, text sections and read-only data are included  in
     core  files  by default. Users can configure their processes
     to  exclude  that  information   from   core   files   using
     coreadm(1M).  Thus,  the  information  presented  by mdb for
     those core files can not match the data that was present  at
     the  time  the  process dumped core. Core files from Solaris


Illumos             Last change: Nov 30, 2005                  65


User Commands                                              MDB(1)


     x86 systems can not be examined on  Solaris  SPARC  systems,
     and vice-versa.

  Limitations on Examining Crash Dump Files
     Crash dumps from Solaris 7 and earlier releases can only  be
     examined  with  the aid of the libkvm from the corresponding
     operating system release. If a crash dump from one operating
     system  release is examined using the dmods from a different
     operating system release, changes in the kernel  implementa-
     tion  can  prevent  some dcmds or walkers from working prop-
     erly. mdb issues a warning message if it detects this condi-
     tion.  Crash dumps from Solaris x86 systems can not be exam-
     ined on Solaris SPARC systems, and vice-versa.

  Relationship Between 32-bit and 64-bit Debugger
     mdb provides support for debugging both  32-bit  and  64-bit
     programs. Once it has examined the target and determined its
     data model, mdb automatically  re-executes  the  mdb  binary
     that  has  the  same data model as the target, if necessary.
     This  approach  simplifies  the  task  of  writing  debugger
     modules,  because  the  modules that are loaded use the same
     data model as the primary target. Only the  64-bit  debugger
     can  be  used  to  debug  64-bit target programs. The 64-bit
     debugger can only be used on a system that  is  running  the
     64-bit operating environment.


     The debugger can also need to re-execute itself when  debug-
     ging  a 32-bit process that execs a 64-bit process, or vice-
     versa. The handling of this situation is discussed  in  more
     detail under Interaction with Exec, below.

  Interaction with Exec
     When a controlled process performs a successful exec(2), the
     behavior  of  the  debugger  is  controlled  by the ::set -o
     follow_exec_mode option, as described above. If the debugger
     and victim process have the same data model, then the "stop"
     and "follow" modes determine whether mdb automatically  con-
     tinues  the target or returns to the debugger prompt follow-
     ing the exec. If the debugger and victim process have a dif-
     ferent  data model, then the "follow" behavior causes mdb to
     automatically re-exec the mdb binary  with  the  appropriate
     data model and to re-attach to the process, still stopped on
     return from the exec. Not all debugger  state  is  preserved
     across this re-exec.


     If a 32-bit victim process  execs  a  64-bit  program,  then
     "stop" returns to the command prompt, but the debugger is no
     longer able to examine the process because it is  now  using
     the  64-bit  data  model.  To  resume debugging, execute the
     ::release -a dcmd, quit mdb, and then execute mdb -p pid  to


Illumos             Last change: Nov 30, 2005                  66


User Commands                                              MDB(1)


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


     If a 64-bit victim process  execs  a  32-bit  program,  then
     "stop"  returns to the command prompt, but the debugger only
     provides limited capabilities for examining the new process.
     All built-in dcmds work as advertised, but loadable dcmds do
     not since they do  not  perform  data  model  conversion  of
     structures.  The  user  should  release  and  re-attach  the
     debugger to the process  as  described  above  in  order  to
     restore full debugging capabilities.

  Interaction with Job Control
     If the debugger is attached to a process that is stopped  by
     job  control  (that  is,  it stopped in response to SIGTSTP,
     SIGTTIN, or SIGTTOU), the process can not be able to be  set
     running  again  when  it is continued by a continue dcmd. If
     the victim process is a member of the same session (that is,
     it  shares  the  same  controlling  terminal  as  mdb),  mdb
     attempts to bring the associated process group to the  fore-
     ground and to continue the process with SIGCONT to resume it
     from job control stop. When mdb is detached from such a pro-
     cess, it restores the process group to the background before
     exiting. If the victim process is not a member of  the  same
     session,  mdb  cannot  safely bring the process group to the
     foreground, so it continues the process with respect to  the
     debugger,  but  the  process remains stopped by job control.
     mdb prints a warning in this case, and the user  must  issue
     an  "fg"  command  from  the  appropriate  shell in order to
     resume the process.

  Process Attach and Release
     When mdb attaches to  a  running  process,  the  process  is
     stopped  and remains stopped until one of the continue dcmds
     is applied, or the debugger quits. If the -o  nostop  option
     is enabled prior to attaching the debugger to a process with
     -p, or prior to issuing  an  ::attach  or  :A  command,  mdb
     attaches to the process but does not stop it. While the pro-
     cess is still running, it can be inspected as usual  (albeit
     with  inconsistent results) and breakpoints or other tracing
     flags might be enabled.  If the :c or ::cont dcmds are  exe-
     cuted  while  the process is running, the debugger waits for
     the process to stop. If no traced software events occur, the
     user  can send an interrupt (^C) after :c or ::cont to force
     the process to stop and return control to the debugger.


     mdb releases the current running process (if any)  when  the
     :R,  ::release, :r, ::run, $q, or ::quit dcmds are executed,
     or when the debugger terminates as the result of an  EOF  or
     signal.  If  the  process  was  originally  created  by  the
     debugger using :r or ::run, it is forcibly terminated as  if


Illumos             Last change: Nov 30, 2005                  67


User Commands                                              MDB(1)


     by  SIGKILL  when it is released. If the process was already
     running prior to attaching mdb to  it,  it  is  set  running
     again  when  it  is  released. A process can be released and
     left stopped and abandoned using the ::release -a option.

  Symbolic Debugging Information
     The ::list, ::offsetof, ::print, and ::sizeof dcmds  require
     that  one  or  more load objects contain compressed symbolic
     debugging information suitable for use with mdb. This infor-
     mation  is currently only available for certain Solaris ker-
     nel modules.

  Developer Information
     The Solaris Modular Debugger Guide provides a more  detailed
     description  of  mdb  features,  as  well as information for
     debugger module developers.


     The header file <sys/mdb_modapi.h> contains  prototypes  for
     the functions in the MDB Module API, and the SUNWmdbdm pack-
     age provides source code for an example module in the direc-
     tory /usr/demo/mdb.


Illumos             Last change: Nov 30, 2005                  68