unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-5.10)
Page:
Section:
Apropos / Subsearch:
optional field

mdb(1)                           User Commands                          mdb(1)



NAME
       mdb - modular debugger

SYNOPSIS
       mdb  [-fkmuwyAFMS]  [+-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,  operating  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 Mod-
       ular 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  program  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 system, where bugs may
       not be reproducible and program state is massive and  distributed,  for
       programs  that  are  highly optimized, have had their debug information
       removed, or are themselves low-level debugging tools, or  for  customer
       situations where the developer can only access post-mortem information.

       mdb  provides a completely customizable environment for debugging these
       programs and scenarios, including a dynamic module facility  that  pro-
       grammers  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 cur-
       rently provides support for the following types of targets:  user  pro-
       cesses,  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 binary files. Each target  exports  a  standard  set  of
       properties,  including  one  or more address spaces, one or more symbol
       tables, a set of load objects, and a set of threads that can  be  exam-
       ined using the debugger commands described below.

       A  debugger  command, or dcmd (pronounced dee-command) in mdb terminol-
       ogy, is a routine in the debugger that can access any of the properties
       of  the  current  target.  mdb parses commands from standard input, and
       then executes the corresponding dcmds. Each dcmd can also accept a list
       of  string  or  numerical arguments, as shown in the syntax description
       below. 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 implementation from dcmds and from
       mdb itself. You can use walkers interactively, or use them as a  primi-
       tive 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  dynamically
       loaded  library  containing a set of dcmds and walkers. During initial-
       ization, mdb will attempt 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  mod-
       ules.

       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
       kernel that may be used with either tool.

   Syntax
       The debugger processes commands from standard input. If standard  input
       is a terminal, mdb provides terminal editing capabilities. mdb can also
       process commands from macro files and from  dcmd  pipelines,  described
       below.  The language syntax is designed around the concept of computing
       the value of an expression (typically a memory address in the  target),
       and  then applying a dcmd to that address. The current address location
       is referred to as 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  characters  sepa-
       rated by one or more non-quoted metacharacters. Some of the metacharac-
       ters 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 metacharacters:


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



       dcmds named by metacharacters or prefixed by a single $ or :  are  pro-
       vided  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 arguments to the invoked
       dcmd, except as specified under Quoting and Arithmetic Expansion below.
       Each  dcmd returns an exit status that indicates it was either success-
       ful, failed, or was invoked with invalid arguments.

       A pipeline is a sequence of one or more simple commands separated by |.
       Unlike  the  shell, dcmds in mdb pipelines are not executed as separate
       processes. After the pipeline has been parsed, each dcmd is invoked  in
       order from left to right. Each dcmd's output is processed and stored as
       described under dcmd Pipelines below. Once the left-hand dcmd  is  com-
       plete,  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 Expansion 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 will be executed count times before the
           next dcmd in the  pipeline  is  executed.  The  repeat  count  only
           applies to the first dcmd in the pipeline.



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

           If  the  initial expression is omitted, dot is not modified but the
           first dcmd in the pipeline will be repeated according to the  value
           of the expression.



       expression [! word ...] [ ; ]

           A command can consist only of an arithmetic expression. The expres-
           sion 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 modified 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 followed by  the  string
           formed by concatenating the words after the ! character.



   Comments
       A  word beginning with // causes that word and all the subsequent char-
       acters 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  com-
       pute  a  numerical  argument  for  a dcmd. An arithmetic expression can
       appear in an argument list enclosed in square brackets  preceded  by  a
       dollar sign ($[ expression ]), and will be replaced by the value of the
       expression.

       Expressions may contain any of the following special words:

       integer                 The specified integer value. Integer values may
                               be  prefixed  with  0i or 0I to indicate binary
                               values, 0o or 0O to indicate octal  values,  0t
                               or  0T to indicate decimal values, and 0x or 0X
                               to indicate hexadecimal values (the default).



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



       'cccccccc'              The integer value computed by  converting  each
                               character  to  a byte equal to its ASCII value.
                               Up to eight characters may be  specified  in  a
                               character  constant. Characters are packed into
                               the integer in  reverse  order  (right-to-left)
                               beginning at the least significant byte.



       <&lt;identifier             The value of the variable named by identifier.



       identifier              The value of the symbol named by identifier.



       (expression)            The value of expression.



       .                       The value of dot.



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



       +                       The value of dot  incremented  by  the  current
                               increment.



       ^                       The  value  of  dot  decremented by the current
                               increment.



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

       Unary operators are right associative and have higher  precedence  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 corre-
                               sponding to virtual address expression  in  the
                               target's virtual address space.



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



       *expression             The value of a pointer-sized quantity  at  vir-
                               tual 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  precedence  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.



       <&lt;<&lt;       Bitwise shift left.



       >&gt;>&gt;       Bitwise shift right.



       ==       Logical equality.



       !=       Logical inequality.



       &&amp;        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 significance) by enclosing them
       in  a  pair of single (' ') or double (" ") quote marks. A single quote
       cannot appear within single quotes. Inside double  quotes,  mdb  recog-
       nizes the C programming language character escape sequences.

   Shell Escapes
       The ! character can be used to create a pipeline between an mdb command
       and the user's shell. If the $SHELL environment variable  is  set,  mdb
       will fork and exec this program for shell escapes; otherwise /bin/sh is
       used. The shell is invoked with the -c  option  followed  by  a  string
       formed  by concatenating the words after the ! character. The ! charac-
       ter takes precedence over all other  metacharacters,  except  semicolon
       (;) and NEWLINE. Once a shell escape is detected, the remaining charac-
       ters up to the next semicolon or NEWLINE are passed as is to the shell.
       The  output  of  shell commands may not be piped to mdb dcmds. Commands
       executed by a shell escape have their output sent directly to the  ter-
       minal, 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, under-
       scores, or periods. A variable can be assigned a value using the >&gt; dcmd
       or ::typeset dcmd, and its attributes  can  be  manipulated  using  the
       ::typeset  dcmd.  Each  variable's  value  is  represented  as a 64-bit
       unsigned integer. A variable may have one  or  more  of  the  following
       attributes:  read-only  (cannot  be  modified  by the user), persistent
       (cannot be unset by the user), and tagged (user-defined indicator).

       The following variables are defined as persistent:

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



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



       b               The virtual address of the base of the data section.



       d               The size of the data section in bytes.



       e               The virtual address of the entry point.



       m               The  initial  bytes (magic number) of the target's pri-
                       mary 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 representative
                       thread. The value of  the  identifier  depends  on  the
                       threading  model used by the current target. See Thread
                       Support, below.




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

   Symbol Name Resolution
       As  explained  in  the  Syntax  description  above, a symbol identifier
       present in an expression context evaluates to the value of this symbol.
       The  value typically denotes the virtual address of the storage associ-
       ated with the symbol in the target's virtual address  space.  A  target
       may  support  multiple  symbol  tables including, but not limited to, a
       primary executable symbol table, a primary dynamic symbol table, a run-
       time  link-editor  symbol table, and standard and dynamic symbol tables
       for each of a number of load objects (such as  shared  libraries  in  a
       user process, or kernel modules in the Solaris kernel). The target typ-
       ically 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;  auto-
       matic symbols do not appear in the symbol 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 defini-
       tions are then used  whenever  mdb  converts  a  symbolic  name  to  an
       address, or an address to the nearest symbol.

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

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

       specfs`_init

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

       The mdb process target expects object to specify the name of  the  exe-
       cutable or of a loaded shared library. It may take any of the following
       forms:

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


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


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


       4.  The literal string a.out is accepted  as  an  alias  for  the  exe-
           cutable.


       The  process  target  will  also accept 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

       will evaluate 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 may
       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 will be displayed when symbols are printed accord-
       ing to the setting of the showlmid option, as described under OPTIONS.

       In the case of a naming conflict between symbols and hexadecimal  inte-
       ger values, mdb will attempt to evaluate an ambiguous token as a symbol
       first, before evaluating it as an integer value. For example, the token
       f  may  either refer to the decimal integer value 15 specified in hexa-
       decimal (the default base), or to a global variable named f in the tar-
       get'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  walk-
       ers.  dcmds and walkers are tracked in two distinct, global namespaces.
       mdb also keeps track of a dcmd and  walker  namespace  associated  with
       each  dmod.  Identically named dcmds or walkers within a given dmod are
       not allowed: a dmod with this type of  naming  conflict  will  fail  to
       load.  Name conflicts between dcmds or walkers from different dmods are
       allowed in the global namespace.  In the case of a conflict, the  first
       dcmd  or  walker with that particular name to be loaded is given prece-
       dence in the global namespace. Alternate definitions are kept in a list
       in  load  order.  The  backquote character (`) may be used in a dcmd or
       walker name as a scoping operator to select  an  alternate  definition.
       For example, if dmods m1 and m2 each provide a dcmd d, and m1 is loaded
       prior to m2, then:

       ::d             Executes m1's definition of d.



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



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




       If module m1 were now unloaded, the next dcmd on the global  definition
       list (m2`d) would be promoted to global visibility. The current defini-
       tion of a dcmd or walker can be  determined  using  the  ::which  dcmd,
       described  below. The global 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, typically virtual addresses,
       from one dcmd or walker to another. Pipeline stages might  be  used  to
       map  a pointer from one type of data structure to a pointer to a corre-
       sponding data structure, to sort a list of addresses, or to select  the
       addresses of structures with certain properties.

       mdb executes each dcmd in the pipeline in order from left to right. The
       leftmost dcmd is executed using the current value of dot, or using  the
       value  specified by an explicit expression 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 standard input. Each line must  consist
       of  an  arithmetic expression terminated by a NEWLINE or semicolon (;).
       The value of the expression is appended to the list of  values  associ-
       ated  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
       pipeline has its output printed to standard output. If any dcmd in  the
       pipeline  produces output to standard error, these messages are printed
       directly to standard error and are not processed as part of  the  pipe-
       line.

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

   Command Re-entry
       The  text  of  the last HISTSIZE  (default 128) commands entered from a
       terminal device are saved in  memory.  The  in-line  editing  facility,
       described  next,  provides key mappings for searching and fetching ele-
       ments 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  charac-
       ter  shown  in upper case. The notation for escape sequences is M- fol-
       lowed by a character. For example, M-f (pronounced meta-eff) is entered
       by  depressing  <&lt;ESC>&gt; followed by 'f', or by depressing <&lt;Meta>&gt; followed
       by 'f' on keyboards that support a Meta key. A command line is  commit-
       ted and executed using RETURN or NEWLINE. The edit commands are:

       ^F              Move cursor forward (right) one character.



       M-f             Move cursor forward one word.



       ^B              Move cursor backward (left) one character.



       M-b             Move cursor backward one word.



       ^A              Move cursor to start of line.



       ^E              Move cursor to end of line.



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



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



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



       ^L              Clear the screen and reprint the current line.



       ^T              Transpose current character with next character.



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



       ^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  termi-
                       nated 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.



       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 will
       interpret 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 device. Each time  a  com-
       mand  is executed, mdb will pause after one screenful of output is pro-
       duced and will display a pager prompt:

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

       The following key sequences are recognized by the pager:

       SPACE                   Display the next screenful of output.



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



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



       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 consist-
       ing of one or more format characters, 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 tar-
       get. A repeat count is a positive integer preceding the format  charac-
       ter that is always interpreted in base 10 (decimal). A repeat count may
       also be specified as an expression enclosed in square brackets preceded
       by  a dollar sign ($[ ]). A string argument must be enclosed in double-
       quotes (" "). No blanks are necessary between format arguments.

       The formatting dcmds are:

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



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



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



       =        Display the value of dot itself in each of the specified  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  num-
       ber 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:


       tab();  lw(0.687500i)  lw(4.812500i).   +T{  increment dot by the count
       (variable size) T} -T{ decrement dot by the count  (variable  size)  T}
       Bhexadecimal  int  (1 byte) CT{ character using C character notation (1
       byte) T} Ddecimal signed int (4 bytes) ET{ decimal unsigned  long  long
       (8  bytes)  T}  Fdouble  (8  bytes) Goctal unsigned long long (8 bytes)
       Hswap bytes and shorts (4 bytes) IT{ address and disassembled  instruc-
       tion  (variable size) T} Jhexadecimal long long (8 bytes) KT{ hexadeci-
       mal uintptr_t (4 or 8 bytes) T} Nnewline Ooctal unsigned int (4  bytes)
       Psymbol  (4  or  8  bytes)  Qoctal  signed int (4 bytes) Rbinary int (8
       bytes) ST{ string using C string notation (variable size) T}  Thorizon-
       tal  tab Udecimal unsigned int (4 bytes) Vdecimal unsigned int (1 byte)
       WT{ default radix unsigned int (4 bytes) T} Xhexadecimal int (4  bytes)
       Ydecoded time32_t (4 bytes) Zhexadecimal long long (8 bytes) ^T{ decre-
       ment dot by increment * count (variable size) T} adot as  symbol+offset
       boctal  unsigned int (1 byte) ccharacter (1 byte) ddecimal signed short
       (2 bytes) edecimal signed long long (8 bytes) ffloat (4  bytes)  goctal
       signed  long  long  (8  bytes)  hswap  bytes (2 bytes) iT{ disassembled
       instruction (variable size) T} nnewline ooctal unsigned short (2 bytes)
       psymbol  (4  or 8 bytes) qoctal signed short (2 bytes) rwhitespace sraw
       string (variable size)  thorizontal  tab  udecimal  unsigned  short  (2
       bytes) vdecimal signed int (1 byte) wT{ default radix unsigned short (2
       bytes) T} xhexadecimal short (2 bytes) ydecoded time64_t (8 bytes)


       The /, \, and ? formatting dcmds can also be used to write to the  tar-
       get's  virtual address space, physical address space, or object file by
       specifying one of the following modifiers as the first  format  charac-
       ter, and then specifying a list of words that are either immediate val-
       ues or expressions 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.



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



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



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



       The  /, \, and ? formatting dcmds can also be used to search for a par-
       ticular 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 pre-
       ceded  by  a dollar sign. If only a value is specified, mdb reads inte-
       gers of the appropriate size and stops at the  address  containing  the
       matching  value. If a value V and mask M are specified, mdb reads inte-
       gers of the appropriate size and stops  at  the  address  containing  a
       value  X  where  (X  &&amp;  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:


       tab();  lw(0.687500i)  lw(4.812500i).   lT{  Search  for  the specified
       2-byte value.  T} LT{ Search for the specified 4-byte  value.   T}  MT{
       Search for the specified 8-byte value.  T}


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

   Execution Control
       mdb  provides facilities for controlling and tracing the execution 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 process 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  soft-
       ware  events  can  be  specified  by the user. Each time a traced event
       occurs in the target process, all  threads  in  the  target  stop,  the
       thread that triggered the event is chosen as the representative thread,
       and control returns to the debugger. Once the  target  program  is  set
       running, control can be asynchronously returned to the debugger by typ-
       ing 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 may observe the
       transition of a program counter register to  a  value  of  interest  (a
       breakpoint) or the delivery of a particular 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 specifier 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
       specifiers for the same event may be created, each with different call-
       backs and properties. The current list of traced events and the proper-
       ties  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 will issue an error message indicating they are not sup-
       ported  if applied to a target that does not support execution control.
       For more information about the interaction of  exec,  attach,  release,
       and job control with debugger execution control, refer to NOTES, below.

   Event Callbacks
       The  ::evset  dcmd  and  event  tracing dcmds allow you to associate 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  exe-
       cuted as if they had been typed at the command prompt. Before executing
       each callback, the dot variable is set to the value of the  representa-
       tive  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 commands to con-
       tinue the target (for example, ::cont or ::step), these commands do not
       immediately continue the target and wait for it to stop again. Instead,
       inside of an event callback, the continue dcmds note  that  a  continue
       operation  is  now  pending, and then return immediately. Therefore, if
       multiple dcmds are included in an event callback, the step or  continue
       dcmd  should be the last command specified.  Following the execution of
       all event callbacks, the target will immediately  resume  execution  if
       all  matching event callbacks requested a continue. If conflicting con-
       tinue operations are requested, the operation with the  highest  prece-
       dence  determines what type of continue will occur. The order of prece-
       dence from highest to lowest is: step, step-over (next), step-out, con-
       tinue.

   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  avail-
       able.   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 >&gt; 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 provides more information  on  debugging
       support  for threads in the Solaris kernel. The mdb process target pro-
       vides proper support for examination of multi-threaded  user  processes
       that   use   the  native  lwp_*  interfaces,  /usr/lib/libthread.so  or
       /usr/lib/lwp/libthread.so. When debugging a live user process, mdb will
       detect  if  a  single  threaded process dlopens or closes libthread and
       will automatically adjust its view of the threading  model  on-the-fly.
       The  process  target  thread  identifiers will correspond 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 will automatically  evalu-
       ate  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 will  fail  and  print  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 may prefer the $ or : forms of the built-ins. Programmers who
       are new to mdb may prefer the more verbose :: form. The  built-ins  are
       shown in alphabetical order. If a $ or : form has a ::identifier equiv-
       alent, it is shown underneath the ::identifier form. The built-in dcmds
       are:

       >&gt; variable-name
       >&gt;/modifier/variable-name

           Assign the value of dot to the specified named variable. Some vari-
           ables are read-only and may not be modified. If the >&gt;  is  followed
           by  a modifier character surrounded by / /, then the value is modi-
           fied as part of the assignment. The modifier characters are:

           c        unsigned char quantity (1-byte)





           s        unsigned short quantity (2-byte)



           i        unsigned int quantity (4-byte)



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



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


       $<&lt; macro-name

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



       $<&lt;<&lt; macro-name

           Read and execute commands from the specified macro  file  (as  with
           $<&lt;), 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 informa-
           tion. If the dcmd is preceded by an explicit address,  a  backtrace
           beginning  at  this  virtual memory address is displayed. Otherwise
           the stack of the representative thread is displayed. If an optional
           count  value  is given as an argument, no more than count arguments
           are displayed for each stack frame in the output.



       [ base ] $d

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



       $e

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



       $P prompt-string

           Set  the  prompt to the specified prompt-string. The default prompt
           is '>&gt; '. The prompt can also be set using ::set -P or the  -P  com-
           mand-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 may 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 listing variables.



       width $w

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



       $W

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



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

           If the user process target is active, attach to and debug the spec-
           ified  process-ID  or  core  file. The core file pathname should be
           specified as a string argument. The process-ID may be specified  as
           the  string  argument,  or as the value of the expression preceding
           the dcmd. Recall that the default base is hexadecimal,  so  decimal
           PIDs  obtained using pgrep(1) or ps(1) should be preceded with "0t"
           when specified as 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  specified,  including an
           optional address specified by an explicit expression preceding  the
           dcmd,  and  each  string or immediate value following the dcmd. The
           arguments may either be symbol names or immediate values denoting a
           particular  virtual address of interest. If a symbol name is speci-
           fied, it may refer to a symbol that cannot yet be evaluated in  the
           target process. That is, it may consist of an object name and func-
           tion name in a load object that has not yet been opened.   In  this
           case,  the  breakpoint is deferred and it will not be active in the
           target until an object matching  the  given  name  is  loaded.  The
           breakpoint  will  be  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 expres-
           sion, as the address may refer to the corresponding Procedure Link-
           age  Table  (PLT)  entry  instead  of the actual symbol definition.
           Breakpoints set on PLT entries may 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 pre-
           ceding the dcmd. The arguments following the :b dcmd  are  concate-
           nated together to form the callback string. If this string contains
           meta-characters, it must be quoted.




       ::cat filename ...

           Concatenate and display files. Each filename  may  specified  as  a
           relative or absolute pathname. The file contents will be printed to
           standard output, but will not be passed to the output  pager.  This
           dcmd is intended to be used with the | operator; the 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 inter-
           est. 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 SIGINT  signal
           is  traced,  control may be asynchronously returned to the debugger
           by typing the user-defined interrupt character (usually  ^C).  This
           SIGINT  signal  will  be  automatically  cleared  and  will  not be
           observed by the target the next time it is continued. If no  target
           program  is currently running, ::cont will start a new program run-
           ning 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 config-
           ured to dump all pages or the pages of  the  current  user  process
           using  dumpadm(1M).  The  ::status  dcmd can be used to display the
           contents of the current crash dump.

           When the user requests a context switch from the kernel target, mdb
           constructs  a  new  target representing the specified user process.
           Once the switch occurs, the new target interposes its dcmds at  the
           global level: thus the / dcmd will now format and display data from
           the virtual address space of the user process, the ::mappings  dcmd
           will display the mappings in the address space of the user process,
           and so on. The kernel target can be restored by  executing  0::con-
           text.




       ::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 specifiers 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  speci-
           fied  address  is  printed in order to provide context. By default,
           instructions are read from the target's virtual address  space.  If
           the  -f  option is present, instructions are read from the target's
           object file instead. The -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 specified explicitly using the -n option.



       ::disasms

           List  the  available  disassembler modes. When a target is initial-
           ized, mdb will attempt to select the appropriate disassembler mode.
           The  user  can change the mode to any of the modes listed using the
           ::dismode dcmd.



       ::dismode [ mode ]
       $V [ mode ]

           Get or set the disassembler mode.  If  no  argument  is  specified,
           print  the  current disassembler mode. If a mode argument is speci-
           fied, 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 particu-
           lar dmod by specifying its name as an additional argument.



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

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


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





           -f              Reads data from the  object  file  location  corre-
                           sponding  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 process, core file, or
                           crash dump.



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



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



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



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



           -s              Elides repeated lines.



           -t              Only  reads  from  and displays the contents of the
                           specified addresses, instead of reading and  print-
                           ing entire lines.



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



           -w paragraphs   Displays paragraphs at 16-byte paragraphs per line.
                           The  default number of paragraphs is one. The maxi-
                           mum value accepted for -w is 16.



       ::echo [ string | value ...]

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



       ::eval command

           Evaluate and execute the specified string as a command. If the com-
           mand  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 may also  have  its  own  internal
           events  enabled for tracing. These events will only be displayed if
           the -a option is present. If the -v option is present, a more  ver-
           bose  display,  including  the reason for any specifier inactivity,
           will be 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 identifier will
                           be shown in square brackets [ ] if the specifier is
                           enabled,  in  parentheses  (  ) if the specifier is
                           disabled, or in angle brackets <&lt; >&gt;  if  the  target
                           program  is  currently  stopped  on  an  event that
                           matches the given specifier.





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

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




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



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



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




           TA              The Temporary, Sticky, and Automatic  event  speci-
                           fier  properties. One or more of the following sym-
                           bols may be shown:

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




                           T        The event specifier is sticky, and will be
                                    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 will be automatically
                                    disabled when the hit count  is  equal  to
                                    the hit limit.



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



                           s        The  target  will  automatically stop 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  will  take
                           effect. These behaviors can be configured using the
                           ::evset dcmd, described below.



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



           Action          The callback string to execute when the correspond-
                           ing  software  event  occurs. This callback is exe-
                           cuted 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 will remove any corresponding instrumentation
                    and will ignore the corresponding  software  events  until
                    the specifier is subsequently re-enabled. If the -n option
                    is not present, the specifier is disabled immediately.



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



           -e       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  execu-
                    tion  of the specifier's callback, except for the Nth exe-
                    cution, where N is the current value  of  the  specifier's
                    hit limit. The -s option takes precedence over both the -D
                    option and the -d option.



           -t       Marks the event specifier as temporary.  Temporary  speci-
                    fiers  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
                    will  not  be  deleted  by ::delete all or :z. They can be
                    deleted by specifying the corresponding specifier ID as an
                    explicit  argument  to  ::delete.  If  the  +T form of the
                    option is given,  the  sticky  property  is  removed.  The
                    default  set  of event specifiers are all initially marked
                    sticky.



           -c       Executes the specified cmd string  each  time  the  corre-
                    sponding  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 will be 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 identified using
           an optional fault number preceding the dcmd, or  a  list  of  fault
           names  or  numbers  (see <&lt;sys/fault.h>&gt;) following the dcmd. The -d,
           -D, -e, -s, -t, -T, -c, and -n options have  the  same  meaning  as
           they do for the ::evset dcmd.



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

           Print the floating-point register set of the representative thread.
           If a thread is specified, the  floating  point  registers  of  that
           thread  are  displayed.  The thread expression should be one of the
           thread identifiers described under 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 metacharacters, it must be quoted.  The  ::grep  dcmd
           can be used in pipelines to filter a list of addresses.



       ::help [ dcmd-name ]

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



       signal :i

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



       $i

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



       ::kill
       :k

           Forcibly  terminate  the  target  if it is a live user process. The
           target will also be 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 target is a user
           process.



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

           Walk through the elements of a linked list data structure and print
           the address of each element in the list. The address of  the  first
           element  in  the  list  can be specified using an optional address.
           Otherwise, the list is assumed to start at  the  current  value  of
           dot.  The  type parameter must name a C struct or union type and is
           used to describe the type of the list elements so that 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  will  continue  iterating until a NULL
           pointer is encountered, the first element is reached again (a  cir-
           cular  list),  or  an error occurs while reading an element. If the
           optional variable-name is specified, the specified variable will be
           assigned  the  value  returned  at  each  step of the walk when mdb
           invokes the next stage of a pipeline. The ::list dcmd may  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.



       ::load [ -s ] module-name

           Load  the  specified dmod. The module name may be given as an abso-
           lute or relative path. If module-name is a simple  name  (that  is,
           does  not  contain  a  '/'),  mdb  will search for it in the module
           library path. Modules with conflicting names may not be loaded; the
           existing  module  must  be  unloaded  first.  If  the  -s option is
           present, mdb will remain silent and not issue any error messages if
           the module is not found or could not be loaded.



       ::log [ -d | [ -e ] filename ]
       $>&gt; [ filename ]

           Enable  or disable the output log. mdb provides an interactive log-
           ging facility where both the input commands 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 $>&gt; dcmd is used, logging is enabled  if  a
           filename  argument is specified; otherwise, logging is disabled. If
           the specified log file already exists, mdb appends any new log out-
           put to the file.




       ::map command

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



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

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




       ::next [ SIG ]
       :e [ SIG ]

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




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

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


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





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



           -d                      Prints value and size fields in decimal.



           -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 com-
                                   mands. This option can be used with  -P  to
                                   produce  a  macro  file  that can be subse-
                                   quently read into the debugger with $<&lt;.



           -u                      Prints only undefined symbols.



           -v                      Sorts symbols by value.



           -x                      Prints value and size fields  in  hexadeci-
                                   mal.



           -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



                                   regi     STT_SPARC_REGISTER



           -f format[,format ... ] Prints  only  the specified symbol informa-
                                   tion. 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



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

           Add the specified symbol name to the private symbol table. mdb pro-
           vides 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 follow-
           ing 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, showing 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
           information will be 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 specified 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
           may be printed in bits. The output  is  always  suffixed  with  the
           appropriate  units for clarity. The type name may use the backquote
           (`) scoping operator described under Symbol Name Resolution, above.
           The ::offsetof dcmd may only be used with objects that contain sym-
           bolic debugging information designed for use  with  mdb.  Refer  to
           NOTES, Symbolic Debugging Information, below for more information.



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

           Print the data structure at the specified virtual address using the
           given type information. The type parameter may  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 may use the backquote (`)  scoping  operator  described  under
           Symbol  Name  Resolution,  above. If the type is a structured type,
           the ::print dcmd will recursively print 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  will  infer
           the  appropriate type automatically. If the type argument is speci-
           fied, it may 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  may  refer  to a sub-structure element by forming a
           list of member names separated  by  period  ('.')  delimiters.  The
           ::print  dcmd  may  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 dis-
           played. 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 heuristic  is  used
           to  determine  if the value should be displayed in decimal or hexa-
           decimal. The number of characters in a character array that will be
           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 will be read and displayed can be
           limited with the -l option. If the -L option is present,  no  limit
           is  enforced  and  all array elements are shown. The default values
           for -c and -l can be modified using ::set or  the  -o  command-line
           option as described under OPTIONS.

           If  the -i option is specified, the address value is interpreted as
           an immediate value to be printed. You must give a type  with  which
           to  interpret  the  value. If the type is smaller than 64 bits, the
           immediate value is 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 representative
           thread. If a thread is specified, the general purpose register  set
           of that thread is displayed. The thread expression should be one of
           the thread identifiers described under 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  continued  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 interpreted by  the  shell.  If
           the  debugger  is already examining a live running program, it will
           first detach from this program as if by ::release.




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

           Get or set miscellaneous debugger properties.  If  no  options  are
           specified, the current set of debugger properties is displayed. The
           ::set dcmd recognizes the following options:

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





           -I       Sets the default path for locating macro files.  The  path
                    argument  may  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  may  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 dis-
                    tance. Refer to the description  of  the  -s  command-line
                    option under OPTIONS for more information.



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




       ::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 will be omitted from the output
           for  the  -p  option  and  will  be  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 mean-
           ing as they do for the ::evset dcmd. Initially, the set of  signals
           that   cause  the  process  to  dump  core  by  default  (see  sig-
           nal.h(3HEAD)) and SIGINT are traced.




       ::sizeof type

           Print the size of the specified type in bytes. The  type  parameter
           may  name  a  C struct, union, enum, fundamental integer type, or a
           pointer to any of these types. The type name may use the  backquote
           (`) scoping operator described under Symbol Name Resolution, above.
           The ::sizeof dcmd may only be used with objects that  contain  sym-
           bolic  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 dis-
           played. If an optional count value is given as an argument, no more
           than count arguments are displayed for each stack frame in the out-
           put.




       ::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
           will  step  over  subroutine calls. The ::step over argument is the
           same as the ::next dcmd. If the optional "out" argument  is  speci-
           fied,  the  target  program  will continue until the representative
           thread returns from the current function. If no target  program  is
           currently  running,  ::step out will start a new program running as
           if by ::run and stop at the first instruction. The :s dcmd  is  the
           same as ::step. The :u dcmd is the same as ::step out.





       [ syscall ] ::sysbp [ +/-dDestT ] [ -io ] [ -c cmd ]
         [ -n count ] syscall...

           Trace  entry to or exit from the specified system calls. The system
           calls are identified using an optional system call number preceding
           the  dcmd,  or  a  list  of  system  call  names  or  numbers  (see
           <&lt;sys/syscall.h>&gt;) following the dcmd. If the -i option is  specified
           (the  default), the event specifiers trigger on entry into the ker-
           nel 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 may  use  any  of  the
           scoping operators described under Symbol Name Resolution, above.



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

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



       ::unload module-name

           Unload the specified dmod. The list of active dmods may be  printed
           using  the ::dmods dcmd. Built-in modules may not be unloaded. Mod-
           ules that are busy (that is, provide dcmds that are currently  exe-
           cuting) may 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 may not be unset by the user.



       ::vars [ -npt]

           Print  a  listing  of named variables. If the -n option is present,
           the output is restricted to variables that currently  have non-zero
           values. If the -p option is present, the variables are printed in a
           form suitable for re-processing by the debugger using the $<&lt;  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 exam-
           ining a kernel target, or when examining a user  process  inside  a
           kernel crash dump (after a ::context dcmd has been issued).

           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 global data structure  and  do  not
           require  a  starting  address.  For  example, walk the list of proc
           structures in the kernel. Other walkers operate on a specific  data
           structure  whose address must be specified explicitly. For example,
           given a pointer to an address space, walk  the  list  of  segments.
           When  used interactively, the ::walk dcmd will print the address of
           each element of the data structure in the default  base.  The  dcmd
           can also be used to provide a list of addresses for a pipeline. The
           walker name may use the backquote (`)  scoping  operator  described
           under dcmd and Walker Name Resolution, above. If the optional vari-
           able-name is specified, the specified variable will be assigned the
           value  returned  at each step of the walk when mdb invokes the next
           stage of the 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  informa-
           tion  on  global name resolution. The -v option will cause the dcmd
           to print the alternate definitions of each dcmd and walker in order
           of precedence.




       addr [ ,len ]::wp  [ +/-dDestT ] [ -rwx ] [ -c cmd ]
          [ -n count ]
       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 may 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 con-
           figured  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  may  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 oper-
                       ating system or an operating system crash dump.



       -f              Forces   raw  file  debugging  mode.  By  default,  mdb
                       attempts to infer whether the object and core file  op-
                       erands refer to a user executable and core dump or to a
                       pair of operating system crash dump files. If the  file
                       type  cannot  be inferred, the debugger will default to
                       examining 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 process, if nec-
                       essary.  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  may  pro-
                       duce  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  $<&lt;  or  $<&lt;<&lt; dcmds. The path is a
                       sequence of directory  names  delimited  by  colon  (:)
                       characters.  The  -I  include  path and -L library path
                       (see below) may  also  contain  any  of  the  following
                       tokens:

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




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



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



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



                       %t       Expands  to  the  name  of the current target.
                                This will either be the literal string  'proc'
                                (a  user  process  or user process core file),
                                'kvm' (a kernel crash dump or the live operat-
                                ing system), or 'raw' (a raw file).



                       The default include path for 32-bit mdb is:


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

                       The default include path for 64-bit mdb is:


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


       -k              Forces  kernel debugging mode. By default, mdb attempts
                       to infer whether the  object  and  core  file  operands
                       refer  to a user executable and core dump, or to a pair
                       of operating system crash dump  files.  The  -k  option
                       forces  mdb  to assume these files are operating system
                       crash dump files. If no object or core operand is spec-
                       ified,  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.



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



       -m              Disables demand-loading of kernel  module  symbols.  By
                       default,  mdb  processes the list of loaded kernel mod-
                       ules and performs demand loading of  per-module  symbol
                       tables.  If  the  -m  option is specified, mdb will not
                       attempt to process the kernel module  list  or  provide
                       per-module symbol tables. As a result, mdb modules cor-
                       responding to active kernel modules will not be  loaded
                       on startup.



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



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

                       adb

                           Enables  stricter  adb(1) compatibility. The prompt
                           will be set to the empty string and many  mdb  fea-
                           tures, such as the output pager, will be disabled.




                       array_mem_limit=limit

                           Sets  the default limit on the number of array mem-
                           bers that ::print will display.  If  limit  is  the
                           special  token none, all array members will be dis-
                           played by default.



                       array_str_limit=limit

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



                       follow_exec_mode=mode

                           Sets the debugger behavior for following an exec(2)
                           system  call. The mode should be one of the follow-
                           ing named constants:

                           ask      If stdout is a terminal device, the debug-
                                    ger  stops  after  the exec(2) system call
                                    has returned and then prompts the user  to
                                    decide whether to follow the exec or stop.
                                    If stdout is not a  terminal  device,  the
                                    ask mode defaults to stop.




                           follow   The debugger follows the exec by automati-
                                    cally continuing the  target  process  and
                                    resetting  all  of its mappings and symbol
                                    tables based on the new  executable.   The
                                    follow   behavior  is  discussed  in  more
                                    detail under NOTES, Interaction with Exec,
                                    below.



                           stop     The  debugger  stops following return from
                                    the exec system call. The stop behavior is
                                    discussed  in  more  detail  under  NOTES,
                                    Interaction with Exec, below.




                       follow_fork_mode=mode

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

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




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



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




                       ignoreeof

                           The  debugger  will  not  exit when an EOF sequence
                           (^D) is entered at the terminal.  The  ::quit  dcmd
                           must be used to quit.



                       nostop

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



                       pager

                           Enables the output pager (default).



                       repeatlast

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



                       showlmid

                           mdb provides support for symbol naming and  identi-
                           fication 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
                           will  be shown as LMlmid`library`symbol, where lmid
                           is the link-map ID  in  the  default  output  radix
                           (16). The user may optionally configure mdb to show
                           the link-map ID scope of all symbols  and  objects,
                           including  those  associated  with  LM_ID_BASE  and
                           LM_ID_LDSO, by enabling the showlmid option. Built-
                           in dcmds that deal with object file names will dis-
                           play  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
                       will  use  the  /proc/pid/object/a.out file as the exe-
                       cutable file pathname.



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



       -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  substi-
                       tuted  in  place of the %r token during pathname expan-
                       sion.



       -s distance     Sets the symbol matching distance  for  address-to-sym-
                       bol-name  conversions  to  the  specified  distance. By
                       default, mdb sets the distance to zero, which enables a
                       smart-matching   mode.  Each  ELF  symbol  table  entry
                       includes a value V and size S, representing the size of
                       the  function  or  data object in bytes. In smart mode,
                       mdb matches an address A with the given symbol if A  is
                       in  the range [ V, V + S ). If any non-zero distance is
                       specified, the same algorithm is used,  but  S  in  the
                       expression  above is always the specified absolute dis-
                       tance and the symbol size is ignored.



       -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 will not be 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.



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



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



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



OPERANDS
       The following operands are supported:

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



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



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



USAGE
       mdb  processes  all  input files (including scripts, object files, core
       files, and raw data files) in a large file aware  fashion.  See  large-
       file(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 may reside.
                       If this variable is not present, no  .mdbrc  processing
                       will occur.



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



FILES
       $HOME/.mdbrc

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



       /dev/kmem

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



       /dev/ksyms

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



       /proc/pid/*

           Process information files that are read when examining and control-
           ling user processes.



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

           Default directories for macro files that are read with the  $<&lt;  and
           $<&lt;<&lt;  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 attributes:


       tab()    allbox;    cw(2.750000i)|     cw(2.750000i)     lw(2.750000i)|
       lw(2.750000i).    ATTRIBUTE   TYPEATTRIBUTE  VALUE  AvailabilitySUNWmdb
       Interface StabilityEvolving


SEE ALSO
       adb(1),  cmdtool(1),  gcore(1),  proc(1),  pgrep(1),  ps(1),   stty(1),
       truss(1),    uname(1),    coreadm(1M),    dumpadm(1M),    largefile(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 situa-
       tions. However, it is not possible for mdb to know definitively whether
       the dmod in question has corrupted only its own state,  or  the  debug-
       ger's  global  state. Therefore a resume operation cannot be guaranteed
       to be safe, or to prevent a  subsequent  crash  of  the  debugger.  The
       safest  course  of  action  following a resume is to save any important
       debug information, and then quit and restart the debugger.

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

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 information may not be available. Since  the  text  section  and
       read-only  data is not present in those core files, the symbol informa-
       tion may not match the data present in  the  process  at  the  time  it
       dumped  core. In releases later than Solaris 9, text sections and read-
       only data are included in core files by default.  Users  can  configure
       their processes to exclude that information from core files using core-
       adm(1M). Thus, the information presented by mdb for  those  core  files
       may  not match the data that was present at the time the process dumped
       core. Core files from  Solaris x86  systems  may  not  be  examined  on
       Solaris SPARC systems, and vice-versa.

   Limitations on Examining Crash Dump Files
       Crash  dumps  from  Solaris 7 and earlier releases may only be examined
       with the aid of the libkvm  from  the  corresponding  operating  system
       release.  If a crash dump from one operating system release is examined
       using the dmods from a different operating system release,  changes  in
       the  kernel implementation may prevent some dcmds or walkers from work-
       ing properly. mdb will issue a warning message if it detects this  con-
       dition.  Crash  dumps  from  Solaris x86 systems may not be examined on
       Solaris SPARC systems, and vice-versa.

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

       The debugger may also need to re-execute itself when debugging a 32-bit
       process that execs a 64-bit process, or  vice-versa.  The  handling  of
       this situation is discussed in more detail under 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 continues the target or returns to  the  debugger  prompt
       following the exec. If the debugger and victim process have a different
       data model, then the "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 re-attach the 64-bit debugger to the process.

       If  a  64-bit  victim  process execs a 32-bit program, then "stop" will
       return to the command prompt, but the debugger will only  provide  lim-
       ited  capabilities  for  examining  the new process. All built-in dcmds
       will work as advertised, but loadable dcmds will 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 may 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 foreground and to continue
       the  process  with SIGCONT to resume it from job control stop. When mdb
       is detached from such a process, it restores the process group  to  the
       background before exiting. If the victim process is not a member of the
       same session, mdb cannot safely bring the process group  to  the  fore-
       ground,  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
       process  is  still  running,  it may be inspected as usual (albeit with
       inconsistent results) and breakpoints or other  tracing  flags  may  be
       enabled.  If  the  :c or ::cont dcmds are executed while the process is
       running, the debugger waits for the process to stop. If no traced soft-
       ware  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 will be
       forcibly terminated as if by  SIGKILL  when  it  is  released.  If  the
       process  was  already  running prior to attaching mdb to it, it will be
       set running again when it is released. A process may  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 information is currently only available
       for certain Solaris kernel 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  <&lt;sys/mdb_modapi.h>&gt; contains prototypes for the func-
       tions in the MDB Module API, and the SUNWmdbdm package provides  source
       code for an example module in the directory /usr/demo/mdb.



SunOS 5.10                        26 Apr 2004                           mdb(1)