Unix/Linux Go Back    


OpenSolaris 2009.06 - man page for mdb (opensolaris section 1)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


mdb(1)					  User Commands 				   mdb(1)

NAME
       mdb - modular debugger

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

DESCRIPTION
   Introduction
       The  mdb  utility is an extensible utility for low-level debugging and editing of the live
       operating system, 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 Modular Debugger Guide.

       Debugging is the process of analyzing the execution and state of  a  software  program  in
       order to remove defects. Traditional debugging tools provide facilities for execution con-
       trol 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 might not be reproducible and program
       state is massive and distributed, for programs that are highly optimized, have  had  their
       debug  information  removed,  or are themselves low-level debugging tools, or for customer
       situations where the developer can only access post-mortem information.

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

   Definitions
       The  target is the program being inspected by the debugger. mdb currently provides support
       for the following types of targets: user processes, user  process  core	files,	the  live
       operating  system  (via	/dev/kmem  and	/dev/ksyms),  operating  system crash dumps, user
       process images recorded inside an operating system crash dump, ELF object files,  and  raw
       binary  files.  Each  target  exports  a standard set of properties, including one or more
       address spaces, one or more symbol tables, a set of load objects, and  a  set  of  threads
       that can be examined using the debugger commands described below.

       A  debugger  command, or dcmd (pronounced dee-command) in mdb terminology, is a routine in
       the debugger that can access any of the properties of the current target. mdb parses  com-
       mands  from  standard input, and then executes the 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  imple-
       mentation  from	dcmds and from mdb itself. You can use walkers interactively, or use them
       as a primitive to build other dcmds or walkers. As with	dcmds,	you  can  extend  mdb  by
       implementing your own walkers as part of a debugger module.

       A  debugger module, or dmod (pronounced dee-mod), is a dynamically loaded library contain-
       ing a set of dcmds and walkers. During initialization, mdb attempts to load  dmods  corre-
       sponding  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 devel-
       oping your own debugger modules.

       A macro file is a text file containing a set of commands to execute. Macro files are typi-
       cally  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 can be used with either tool.

   Syntax
       The debugger processes commands from standard input. If standard input is a terminal,  mdb
       provides terminal editing capabilities. mdb can also process commands from macro files and
       from dcmd pipelines, described below. The language 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 separated by one or more
       non-quoted metacharacters. Some of the metacharacters only function as delimiters in  cer-
       tain  contexts, as described below. An identifier is a sequence of letters, digits, under-
       scores, 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  provided  as  built-in
       operators,  and implement complete compatibility with the command set of the legacy adb(1)
       utility. Once a dcmd has been parsed, the /, \, ?, =, >, $, and : characters are no longer
       recognized as metacharacters until the termination of the argument list.

       A  simple-command  is a dcmd followed by a sequence of zero or more blank-separated words.
       The words are passed as 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 successful, failed, or was invoked with invalid arguments.

       A pipeline is a sequence of one or more simple commands separated by |. Unlike the  shell,
       dcmds in mdb pipelines are not executed as separate processes. After the pipeline has been
       parsed, each dcmd is invoked in order from left to right. Each dcmd's output is	processed
       and  stored  as described under dcmd Pipelines below. Once the left-hand dcmd is complete,
       its processed output is used as input for the next dcmd in the pipeline. If any dcmd  does
       not return a successful exit status, the pipeline is aborted.

       An  expression is a sequence of words that is evaluated to compute a 64-bit unsigned inte-
       ger 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, indicat-
	   ing 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 fol-
	   lowed 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 evalu-
	   ated to determine the new value of dot, and the second is  evaluated  to  determine	a
	   repeat  count  for  the  first dcmd in the pipeline. This dcmd is executed count times
	   before the next dcmd in the pipeline is executed. The repeat count only applies to the
	   first dcmd in the pipeline.

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

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

       expression [! word ...] [ ; ]

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

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

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

       , 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 characters up to a NEW-
       LINE to be ignored.

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

       Expressions can contain any of the following special words:

       integer		     The specified integer value. Integer values can be prefixed with  0i
			     or  0I to indicate binary values, 0o or 0O to indicate octal values,
			     0t or 0T to indicate decimal values, and 0x or 0X to indicate  hexa-
			     decimal 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 can be specified in
			     a character constant. Characters are  packed  into  the  integer  in
			     reverse  order  (right-to-left)  beginning  at the least significant
			     byte.

       <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.

       &		     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 corresponding to virtual address expression in
			      the target's virtual address space.

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

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

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

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

       Binary operators are left associative and have lower 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.

       <<    Bitwise shift left.

       >>    Bitwise shift right.

       ==    Logical equality.

       !=    Logical inequality.

       &     Bitwise AND.

       ^     Bitwise exclusive OR.

       |     Bitwise inclusive OR.

   Quoting
       Each  metacharacter  described above (see Syntax) terminates a word unless quoted. Charac-
       ters 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 recognizes  the
       C programming language character escape sequences.

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

   Variables
       A  variable  is a variable name, a corresponding integer value, and a set of attributes. A
       variable name is a sequence of letters, digits, underscores, or periods. A variable can be
       assigned a value using the > dcmd or ::typeset dcmd, and its attributes can be manipulated
       using the ::typeset dcmd. Each variable's value is represented as a 64-bit unsigned  inte-
       ger.  A	variable  can  have one or more of the following attributes: read-only (cannot be
       modified by the user), persistent (cannot be unset by the user), and tagged  (user-defined
       indicator).

       The following variables are defined as persistent:

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

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

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

       d	 The size of the data section in bytes.

       e	 The virtual address of the entry point.

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

       t	 The size of the text section in bytes.

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

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

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

   Symbol Name Resolution
       As explained in the Syntax description above, a symbol identifier present in an expression
       context evaluates to the value of this symbol. The value  typically  denotes  the  virtual
       address of the storage associated with the symbol in the target's virtual address space. A
       target can support multiple symbol tables including, but not limited to,  a  primary  exe-
       cutable symbol table, a primary dynamic symbol table, a run-time link-editor symbol table,
       and standard and dynamic symbol tables for each of a  number  of  load  objects	(such  as
       shared  libraries  in a user process, or kernel modules in the Solaris kernel). The target
       typically searches the primary executable's symbol tables first, and then one or  more  of
       the  other symbol tables. Notice that ELF symbol tables only contain entries for external,
       global, and static symbols; automatic symbols do not appear in the 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 cre-
       ate  symbol  definitions  for  program functions or data that were either missing from the
       original program or stripped out. These definitions are then used whenever mdb converts	a
       symbolic name to an address, or an address to the nearest symbol.

       As  targets contain multiple symbol tables, and each symbol table can include symbols from
       multiple object files, different symbols with the same name can exist. mdb uses the  back-
       quote  (`)  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 executable or of a loaded
       shared library. It can take any of the following forms:

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

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

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

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

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

	 LM0`libc.so.1`_init

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

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

       ::d	 Executes m1's definition of d.

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

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

       If module m1 were now unloaded, the next dcmd on the global definition list  (m2`d)  would
       be promoted to global visibility. The current definition of a dcmd or walker can be deter-
       mined 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 corresponding data structure, to sort a list of addresses, or to  select  the
       addresses of structures with certain properties.

       mdb  executes  each dcmd in the pipeline in order from left to right. The leftmost dcmd is
       executed using the current value of dot, or using  the  value  specified  by  an  explicit
       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 stan-
       dard  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  associated
       with the pipe. If a syntax error is detected, the pipeline is aborted.

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

   Signal Handling
       The debugger ignores the PIPE and QUIT signals. The INT 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  asyn-
       chronously  (that is, delivered from another process using kill(2)), mdb restores the sig-
       nal to its default disposition and dump core. However, if any of these signals are  gener-
       ated  synchronously  by	the  debugger process itself and a dcmd from an externally loaded
       dmod is currently executing, and standard input is a terminal,  mdb  provides  a  menu  of
       choices	allowing  the user to force a core dump, quit without producing a core dump, stop
       for attach by a debugger, or attempt to resume. The resume option aborts all  active  com-
       mands  and  unload  the	dmod whose dcmd was active at the time the fault occurred. It can
       then be subsequently re-loaded by the user. The resume option provides limited  protection
       against	buggy  dcmds.  Refer  to WARNINGS, Use of the Error Recovery Mechanism, below for
       information about the risks associated with the resume option.

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

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

       ^F	     Move cursor forward (right) one character.

       M-f	     Move cursor forward one word.

       ^B	     Move cursor backward (left) one character.

       M-b	     Move cursor backward one word.

       ^A	     Move cursor to start of line.

       ^E	     Move cursor to end of line.

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

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

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

       ^L	     Clear the screen and reprint the current line.

       ^T	     Transpose current character with next character.

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

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

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

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

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

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

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

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

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

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

       On  keyboards  that  support an extended keypad with arrow keys, mdb interprets these key-
       strokes 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  stan-
       dard  output  is  a terminal device. Each time a command is executed, mdb pauses after one
       screenful of output is produced and displays a pager prompt:

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

       The following key sequences are recognized by the pager:

       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 command 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 consisting 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 target.	A
       repeat  count  is  a positive integer preceding the format character that is always inter-
       preted in base 10 (decimal). A repeat  count  can  also	be  specified  as  an  expression
       enclosed  in  square  brackets preceded by a dollar sign ($[ ]). A string argument must be
       enclosed in double-quotes (" "). No blanks are necessary between format 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 loca-
	     tion 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 number of  bytes  corre-
       sponding  to  the size of the data format, shown in the table. The table of format charac-
       ters can be displayed from within mdb using the ::formats dcmd. The format characters are:

       +	 increment dot by the count (variable size)
       -	 decrement dot by the count (variable size)
       B	 hexadecimal int (1 byte)
       C	 character using C character notation (1 byte)
       D	 decimal signed int (4 bytes)
       E	 decimal unsigned long long (8 bytes)
       F	 double (8 bytes)
       G	 octal unsigned long long (8 bytes)
       H	 swap bytes and shorts (4 bytes)
       I	 address and disassembled  instruction	(variable
		 size)
       J	 hexadecimal long long (8 bytes)
       K	 hexadecimal uintptr_t (4 or 8 bytes)
       N	 newline
       O	 octal unsigned int (4 bytes)
       P	 symbol (4 or 8 bytes)
       Q	 octal signed int (4 bytes)
       R	 binary int (8 bytes)
       S	 string using C string notation (variable size)
       T	 horizontal tab
       U	 decimal unsigned int (4 bytes)
       V	 decimal unsigned int (1 byte)
       W	 default radix unsigned int (4 bytes)
       X	 hexadecimal int (4 bytes)
       Y	 decoded time32_t (4 bytes)
       Z	 hexadecimal long long (8 bytes)
       ^	 decrement  dot  by  increment	* count (variable
		 size)

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

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

       The search modifiers are:

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

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

   Execution Control
       mdb  provides  facilities for controlling and tracing the execution of a live running pro-
       gram. 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 software events can be
       specified by the user. Each time a traced event occurs in the target process, all  threads
       in  the	target	stop, the thread that triggered the event is chosen as the representative
       thread, and control returns to the debugger. Once the target program is set running,  con-
       trol  can  be asynchronously returned to the debugger by typing the user-defined interrupt
       character (typically ^C).

       A software event is a state transition in the target  program  that  is	observed  by  the
       debugger. For example, the debugger can observe the transition of a program counter regis-
       ter 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 can be cre-
       ated, each with different callbacks and properties. The current list of traced events  and
       the  properties	of the corresponding event specifiers can be displayed using the ::events
       dcmd. The event specifier properties are  defined  as  part  of	the  description  of  the
       ::events and ::evset dcmds, below.

       The execution control built-in dcmds, described below, are always available, but issues an
       error message indicating they are not supported if applied to a target that does not  sup-
       port  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  executed as if they had been typed at the command prompt. Before executing each call-
       back, the dot variable is set to the value of the representative thread's program  counter
       and  the  "hits"  variable  is set to the number of times this specifier has been matched,
       including the current match.

       If the event callbacks themselves contain one or more commands to continue 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 com-
       mand  specified.  Following  the  execution of all event callbacks, the target immediately
       resumes execution if all matching event callbacks requested  a  continue.  If  conflicting
       continue  operations  are  requested, the operation with the highest precedence determines
       what type of continue occurs. The order of precedence from highest  to  lowest  is:  step,
       step-over (next), step-out, continue.

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

       The mdb kernel target exports the virtual address of  the  corresponding  internal  thread
       structure  as  the  identifier for a given thread. The Solaris Modular Debugger Guide pro-
       vides more information on debugging support for threads in the  Solaris	kernel.  The  mdb
       process	target	provides  proper support for examination of multi-threaded user processes
       that use the native lwp_* interfaces, /usr/lib/libthread.so or  /usr/lib/lwp/libthread.so.
       When  debugging	a  live user process, mdb detects if a single threaded process dlopens or
       closes libthread and automatically adjusts its view of the threading model on-the-fly. The
       process	target	thread	identifiers  corresponds  to  either  the  lwpid_t,  thread_t, or
       pthread_t of the representative, depending on the threading model used by the application.

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

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

       > variable-name
       >/modifier/variable-name

	   Assign the value of dot to the specified named variable. Some variables are	read-only
	   and	can not be modified. If the > is followed by a modifier character surrounded by /
	   /, then the value is modified as part of the 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). Modifiers are provided for  backwards  compatibility;  the  mdb
	   */modifier/ and %/modifier/ syntax should be used instead.

       $< macro-name

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

       $<< macro-name

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

       $?

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

       [ address ] $C [ count ]

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

       [ base ] $d

	   Get	or  set  the default output radix. If the dcmd is preceded by an explicit expres-
	   sion, 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 flex-
	   ible options for displaying symbol tables.

       $P prompt-string

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

       distance $s

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

       $v

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

       width $w

	   Set	the output page width to the specified value. Typically, this command is not nec-
	   essary 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 specified process-ID or
	   core file. The core file pathname should  be  specified  as	a  string  argument.  The
	   process-ID  can be specified as the string argument, or as the value of the expression
	   preceding the dcmd. Recall that the default	base  is  hexadecimal,	so  decimal  PIDs
	   obtained  using  pgrep(1)  or  ps(1)  should  be  preceded with "0t" when specified as
	   expressions.

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

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

       ::cat filename ...

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

       ::cont [ SIG ]
       :c [ SIG ]

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

       address ::context
       address $p

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

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

       ::dcmds

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

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

	   Delete the event specifiers with the given id number. The id number argument is inter-
	   preted  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 speci-
	   fiers.

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

	   Disassemble starting at or around the address specified by the final argument, or  the
	   current value of dot. If the address matches the start of a known function, the entire
	   function is disassembled. Otherwise, a "window" of instructions before and  after  the
	   specified address is printed in order to provide context. By default, instructions are
	   read from the target's virtual address space. If the -f option  is  present,  instruc-
	   tions  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 initialized, mdb attempts to
	   select the appropriate disassembler mode. The user can change the mode to any  of  the
	   modes listed using the ::dismode dcmd.

       ::dismode [ mode ]
       $V [ mode ]

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

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

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

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

	   Print a hexadecimal and ASCII memory dump of the 16-byte aligned region of memory con-
	   taining  the address specified by dot. If a repeat count is specified for ::dump, this
	   is interpreted as a number of bytes to dump rather than a number  of  iterations.  The
	   ::dump dcmd also 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 corresponding to  the  given
			    virtual  address  instead of from the target's virtual address space.
			    The -f option is enabled by default if the debugger is not	currently
			    attached to a live process, core file, or crash dump.

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

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

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

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

	   -s		    Elides repeated lines.

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

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

	   -w paragraphs    Displays paragraphs at 16-byte paragraphs per line. The default  num-
			    ber of paragraphs is one. The maximum value accepted for -w is 16.

       ::echo [ string | value ...]

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

       ::eval command

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

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

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

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

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

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

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

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

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

			  *    The  event specifier is armed. This state means that the target is
			       currently running with instrumentation for  this  type  of  event.
			       This  state  is only visible if the debugger is attached to a run-
			       ning 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 informa-
			       tion about the reason the instrumentation failed.

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

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

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

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

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

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

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

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

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

	   Action	  The  callback  string  to execute when the corresponding software event
			  occurs. This callback is executed as if it had been typed at	the  com-
			  mand 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 rec-
	   ognizes the following options:

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

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

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

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

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

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

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

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

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

       ::files
       $f

	   Print  a list of the known source files (symbols of type STT_FILE present in the vari-
	   ous 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 <sys/fault.h>)
	   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.

       [ 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 prints 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 is deleted from the list of traced events. By default, the set
	   of ignored signals is initialized to the complement of the set of signals that cause a
	   process to dump core by default (see signal.h(3HEAD)), except  for  SIGINT,	which  is
	   traced by default.

       $i

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

       ::kill
       :k

	   Forcibly  terminate	the  target  if  it  is  a  live user process. The target is also
	   forcibly terminated when the debugger exits if it was created by  the  debugger  using
	   ::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  speci-
	   fied 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 appro-
	   priate size. The member parameter is used to name the member of type that  contains	a
	   pointer  to	the  next  list element. The ::list dcmd continues iterating until a NULL
	   pointer is encountered, the first element is reached again (a circular  list),  or  an
	   error occurs while reading an element. If the optional variable-name is specified, the
	   specified variable is assigned the value returned at each step of the  walk	when  mdb
	   invokes  the  next  stage of a pipeline. The ::list dcmd can only be used with objects
	   that 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 can be given as an absolute or relative path.
	   If module-name is a simple name (that is, does not contain a '/'), mdb searches for it
	   in  the  module  library  path.  Modules with conflicting names can not be loaded; the
	   existing module must be unloaded first. If the  -s  option  is  present,  mdb  remains
	   silent  and	not  issue  any error messages if the module is not found or could not be
	   loaded.

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

	   Enable or disable the output log. mdb provides an interactive logging  facility  where
	   both the input commands and standard output can be logged to a file while still inter-
	   acting 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 dis-
	   ables logging. If the $> 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 output to the file.

       ::map command

	   Map the value of dot to a corresponding value using the command specified as a  string
	   argument,  and  then print the new value of dot. If the command contains whitespace or
	   metacharacters, it must be quoted. The ::map dcmd can be used in pipelines  to  trans-
	   form 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	only shows the mapping that contains the given address. If a string name argument
	   is given, mdb only shows the mapping matching that description.

       ::next [ SIG ]
       :e [ SIG ]

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

       [ address ] ::nm [ -DPdghnopuvx ] [ -t types ]
       #sp;#sp;[ -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 corre-
	   sponding 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 commands. This option
				      can be used with -P to produce a macro  file  that  can  be
				      subsequently read into the debugger with $<.

	   -u			      Prints only undefined symbols.

	   -v			      Sorts symbols by value.

	   -x			      Prints value and size fields in hexadecimal.

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

				      noty    STT_NOTYPE

				      objt    STT_OBJECT

				      func    STT_FUNC

				      sect    STT_SECTION

				      file    STT_FILE

				      comm    STT_COMMON

				      tls     STT_TLS

				      regi    STT_SPARC_REGISTER

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

				      ndx      symbol table index

				      val      symbol value

				      size     size in bytes

				      type     symbol type

				      bind     binding

				      oth      other

				      shndx    section index

				      name     symbol name

				      ctype    C type for symbol (if known)

				      obj      object which defines symbol

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

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

	   -e	 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 is
	   listed as having a version of "Unknown" in the output for the -v option.

       ::offsetof type member

	   Print the offset of the specified member of the 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 can be printed in bits. The output is always  suffixed
	   with  the appropriate units for clarity. The type name can use the backquote (`) scop-
	   ing operator described under Symbol Name Resolution, above. The  ::offsetof	dcmd  can
	   only be used with objects that contain symbolic debugging information designed for use
	   with mdb. Refer to NOTES, Symbolic Debugging Information, below for more information.

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

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

	   If the -a option is present, the address of each member is displayed. If the -p option
	   is present, ::print interprets address as a physical memory address instead of a  vir-
	   tual  memory  address.  If  the  -t option is present, the type of each member is dis-
	   played. 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 hexadecimal. The number of characters in a character
	   array that is read and displayed as a string can be limited with the -c option. If the
	   -C option is present, no limit is enforced. The number of elements in a standard array
	   that  is  read  and	displayed  can be limited with the -l option. If the -L option is
	   present, no limit is enforced and all array elements are shown. The default values for
	   -c and -l can be modified using ::set or the -o command-line option as described under
	   OPTIONS.

	   If the -i option is specified, the address value is interpreted as an immediate  value
	   to  be printed. You must give a type with which to interpret the value. If the type is
	   smaller than 64 bits, the immediate value is 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 first detaches from this program as if by ::release.

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

	   Get or set miscellaneous debugger properties. If no options are specified, the current
	   set	of  debugger  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 can contain
		 any of the special  tokens  described	for  the  -I  command-line  option  under
		 OPTIONS.

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

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

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

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

	   -w	 Re-opens the target for writing, as if mdb had been executed 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 infor-
	   mation is omitted from the output for the -p option and is listed as having a  version
	   of "Unknown" in the output for the -v option.

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

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

       ::sizeof type

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

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

	   Print a C stack backtrace. If the dcmd is preceded by an explicit address, a backtrace
	   beginning at this virtual memory address is displayed. Otherwise the stack of the rep-
	   resentative 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.

       ::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 spec-
	   ified, ::step steps over subroutine calls. The ::step over argument is the same as the
	   ::next dcmd. If the optional "out" argument is specified, the target program continues
	   until the representative thread returns from the current function. If no  target  pro-
	   gram  is currently running, ::step out starts a new program running as if by ::run and
	   stop at the first instruction. The :s dcmd is the same as ::step. The :u dcmd  is  the
	   same as ::step out.

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

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

       thread ::tls symbol

	   Print  the  address of the storage for the specified thread-local storage (TLS) symbol
	   in the context of the specified thread. The thread expression should  be  one  of  the
	   thread  identifiers described under Thread Support, above. The symbol name can use any
	   of the scoping 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 can be printed using  the  ::dmods
	   dcmd.  Built-in  modules  can not be unloaded. Modules that are busy (that is, provide
	   dcmds that are currently executing) can not be unloaded.

       ::unset variable-name . . .

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

       ::vars [ -npt]

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

       ::version

	   Print the debugger version number.

       address ::vtop [-a as]

	   Print the physical address mapping for the specified virtual address, if possible. The
	   ::vtop dcmd is only available when examining a kernel target, or when 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 avail-
	   able 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 prints  the
	   address  of	each element of the data structure in the default base. The dcmd can also
	   be used to provide a list of addresses for a pipeline. The walker  name  can  use  the
	   backquote (`) scoping operator described under dcmd and Walker Name Resolution, above.
	   If the optional variable-name is specified, the specified  variable	is  assigned  the
	   value  returned  at each step of the walk when mdb invokes the next stage of the pipe-
	   line.

       ::walkers

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

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

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

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

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

       ::xdata

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

       :z

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

OPTIONS
       The following options are supported:

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

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

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

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

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

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

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

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

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

		      The default include path for 32-bit mdb is:

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

		      The default include path for 64-bit mdb is:

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

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

       -K	      Load kmdb, stop the live running operating system kernel,  and  proceed  to
		      the  kmdb  debugger  prompt.  This option should only be used on the system
		      console, as the subsequent kmdb prompt appears on the system console.

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

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

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

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

		      adb		       Enables stricter adb(1) compatibility. The  prompt
					       is  set to the empty string and many mdb features,
					       such as the output pager, is disabled.

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

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

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

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

					       follow	 The  debugger	follows the exec by auto-
							 matically continuing the target  process
							 and  resetting  all  of its mappings and
							 symbol tables	based  on  the	new  exe-
							 cutable.  The	follow	behavior  is dis-
							 cussed  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  con-
					       stants:

					       ask	 If  stdout  is  a  terminal  device, the
							 debugger 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 ter-
							 minal 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  does  not exit when an EOF sequence
					       (^D) is entered at the terminal. The  ::quit  dcmd
					       must be used to quit.

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

		      pager		       Enables the output pager (default).

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

		      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. Sym-
					       bols  on  link  maps  other  than  LM_ID_BASE   or
					       LM_ID_LDSO   is	shown  as  LMlmid`library`symbol,
					       where lmid is the link-map ID in the default  out-
					       put  radix(16). The user can optionally configure
					       mdb to show the link-map ID scope of  all  symbols
					       and   objects,  including  those  associated  with
					       LM_ID_BASE  and	LM_ID_LDSO,   by   enabling   the
					       showlmid  option.  Built-in  dcmds  that deal with
					       object file names displays link-map IDs	according
					       to  the	value  of showlmid above, including ::nm,
					       ::mappings, $m, and ::objects.

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

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

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

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

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

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

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

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

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

       -W	      Permit  access  to  memory  addresses  that  are	mapped to I/O devices. By
		      default, mdb does not allow such access because many devices do not provide
		      hardware protection against invalid software manipulations. Use this option
		      only when debugging device drivers and with caution.

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

OPERANDS
       The following operands are supported:

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

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

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

USAGE
       mdb  processes  all input files (including scripts, object files, core files, and raw data
       files) in a large file aware fashion. See largefile(5) for more information about the pro-
       cessing of large files, which are files greater than or equal to 2 Gbytes (2^31 bytes).

EXIT STATUS
       The following exit values are returned:

       0    Debugger completed execution successfully.

       1    A fatal error occurred.

       2    Invalid command line options were specified.

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

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

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

FILES
       $HOME/.mdbrc

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

       /dev/kmem

	   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 controlling user processes.

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

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

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

	   Default directories for debugger modules that are loaded using the ::load dcmd.  plat-
	   form-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:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Availability		     |SUNWmdb			   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Evolving			   |
       +-----------------------------+-----------------------------+

SEE ALSO
       adb(1), cmdtool(1), gcore(1), proc(1), pgrep(1), ps(1), stty(1), truss(1), uname(1), core-
       adm(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  possi-
       ble  that  a  buggy dmod can cause mdb to dump core or otherwise misbehave. The mdb resume
       capability, described above under Signal Handling, provides a limited  recovery	mechanism
       for these situations. However, it is not possible for mdb to know definitively whether the
       dmod in question has corrupted only its own state, or the debugger's global state.  There-
       fore  a resume operation cannot be guaranteed to be safe, or to prevent a subsequent crash
       of the debugger. The safest course of action following a resume is to save  any	important
       debug information, and then quit and restart the debugger.

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

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

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

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

       The debugger can also need to re-execute itself when 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 "fol-
       low" 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" returns to the command
       prompt, but the debugger only provides limited capabilities for examining the new process.
       All built-in dcmds work as advertised, but loadable dcmds do not since they do not perform
       data model conversion of structures. The user should release and re-attach the debugger to
       the process as described above in order to restore full debugging capabilities.

   Interaction with Job Control
       If  the	debugger  is  attached	to  a process that is stopped by job control (that is, it
       stopped in response to SIGTSTP, SIGTTIN, or SIGTTOU), the process can not be  able  to  be
       set running again when it is continued by a continue dcmd. If the victim process is a mem-
       ber 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  foreground, so it continues the process with respect to the debugger, but the process
       remains stopped by job control. mdb prints a warning in this case, and the user must issue
       an "fg" command from the appropriate shell in order to resume the process.

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

       mdb  releases  the current running process (if any) when the :R, ::release, :r, ::run, $q,
       or ::quit dcmds are executed, or when the debugger terminates as the result of an  EOF  or
       signal.	If  the  process  was originally created by the debugger using :r or ::run, it is
       forcibly terminated as if by SIGKILL when it is released. If the process was already  run-
       ning  prior to attaching mdb to it, it is set running again when it is released. A process
       can be released and left stopped and abandoned using the ::release -a option.

   Symbolic Debugging Information
       The ::list, ::offsetof, ::print, and ::sizeof dcmds require that one or more load  objects
       contain compressed symbolic debugging information suitable for use with mdb. This informa-
       tion 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 <sys/mdb_modapi.h> contains prototypes for the functions in the MDB Module
       API, and the SUNWmdbdm package provides source code for an example module in the directory
       /usr/demo/mdb.

SunOS 5.11				   30 Nov 2005					   mdb(1)
Unix & Linux Commands & Man Pages : ©2000 - 2017 Unix and Linux Forums


All times are GMT -4. The time now is 11:15 AM.