Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
mdb(1)				 User Commands				mdb(1)

NAME
       mdb - modular debugger

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

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

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

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

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

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

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

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

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

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

   Syntax
       The  debugger processes commands	from standard input. If	standard input
       is a terminal, mdb provides terminal editing capabilities. mdb can also
       process	commands  from	macro files and	from dcmd pipelines, described
       below. The language syntax is designed around the concept of  computing
       the  value of an	expression (typically a	memory address in the target),
       and then	applying a dcmd	to that	address. The current address  location
       is referred to as dot, and its value is referenced using	``.''.

       A metacharacter is one of the following characters:

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

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

       A dcmd is denoted by one	of the following words or metacharacters:

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

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

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

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

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

   Commands
       A command is one	of the following:

       pipeline	[! word	...] [ ; ]

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

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

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

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

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

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

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

       expression [! word ...] [ ; ]

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

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

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

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

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

       ! word ... [ ; ]

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

   Comments
       A word beginning	with //	causes that word and all the subsequent	 char-
       acters up to a NEWLINE to be ignored.

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

       Expressions may contain any of the following special words:

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

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

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

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

       ^		       The value of dot	decremented by the current in-
			       crement.

       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  ad-
			       dress space.

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

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

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

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

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

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

       *	Integer	multiplication.

       %	Integer	division.

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

       +	Integer	addition.

       -	Integer	subtraction.

       <<	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 un-
       less quoted. Characters can be quoted (forcing mdb  to  interpret  each
       character as itself without any special significance) by	enclosing them
       in a pair of single (' ') or double (" ") quote marks. A	 single	 quote
       cannot  appear  within  single quotes. Inside double quotes, mdb	recog-
       nizes the C programming language	character escape sequences.

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

   Variables
       A variable is a variable	name, a	corresponding integer value, and a set
       of attributes. A	variable name is a sequence of letters,	digits,	under-
       scores, or periods. A variable can be assigned a	value using the	> dcmd
       or  ::typeset  dcmd,  and  its  attributes can be manipulated using the
       ::typeset dcmd. Each variable's value is	represented as	a  64-bit  un-
       signed  integer.	 A  variable may have one or more of the following at-
       tributes: read-only (cannot be modified by the user), persistent	 (can-
       not 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  pri-
		       mary  object  file,  or zero if no object file has been
		       read yet.

       t	       The size	of the text section in bytes.

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

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

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

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

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

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

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

       specfs`_init

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

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

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

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

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

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

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

       LM0`libc.so.1`_init

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

       In  the case of a naming	conflict between symbols and hexadecimal inte-
       ger values, mdb will attempt to evaluate	an ambiguous token as a	symbol
       first, before evaluating	it as an integer value.	For example, the token
       f may either refer to the decimal integer value 15 specified  in	 hexa-
       decimal (the default base), or to a global variable named f in the tar-
       get's symbol table. If a	symbol with an ambiguous name is present,  the
       integer value can be specified by using an explicit 0x or 0X prefix.

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

       ::d	       Executes	m1's definition	of d.

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

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

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

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

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

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

   Signal Handling
       The debugger ignores the	PIPE and QUIT signals. The INT	signal	aborts
       the  command  that  is currently	executing. The debugger	intercepts and
       provides	special	handling for the ILL, TRAP, EMT, FPE,  BUS,  and  SEGV
       signals.	If any of these	signals	are generated asynchronously (that is,
       delivered from another process using kill(2)),  mdb  will  restore  the
       signal  to  its	default	 disposition and dump core. However, if	any of
       these signals are generated synchronously by the	debugger  process  it-
       self  and a dcmd	from an	externally loaded dmod is currently executing,
       and standard input is a terminal, mdb will provide a  menu  of  choices
       allowing	 the  user to force a core dump, quit without producing	a core
       dump, stop for attach by	a debugger, or attempt to resume.  The	resume
       option  will  abort  all	active commands	and unload the dmod whose dcmd
       was active at the time the fault	occurred. It can then be  subsequently
       re-loaded  by  the  user. The resume option provides limited protection
       against buggy dcmds. Refer to WARNINGS, Use of the Error	Recovery Mech-
       anism, 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, de-
       scribed 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 charac-
       ter shown in upper case.	The notation for escape	sequences is  M-  fol-
       lowed by	a character. For example, M-f (pronounced meta-eff) is entered
       by depressing <ESC> followed by 'f', or by depressing  <Meta>  followed
       by  'f' on keyboards that support a Meta	key. A command line is commit-
       ted and executed	using RETURN or	NEWLINE. The edit commands are:

       ^F	       Move cursor forward (right) one character.

       M-f	       Move cursor forward one word.

       ^B	       Move cursor backward (left) one character.

       M-b	       Move cursor backward one	word.

       ^A	       Move cursor to start of line.

       ^E	       Move cursor to end of line.

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

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

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

       ^L	       Clear the screen	and reprint the	current	line.

       ^T	       Transpose current character with	next character.

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

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

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

       The editing mode	also interprets	the following  user-defined  sequences
       as editing commands. User defined sequences can be read or modified us-
       ing 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  en-
		       tire current command line.

       quit	       User  defined quit character (usually ^\). Quit the de-
		       bugger.

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

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

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

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

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

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

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

   Output Pager
       mdb provides a built-in output pager. The output	pager  is  enabled  if
       the  debugger's	standard output	is a terminal device. Each time	a com-
       mand is executed, mdb will pause	after one screenful of output is  pro-
       duced and will display a	pager prompt:

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

       The following key sequences are recognized by the pager:

       SPACE		       Display the next	screenful of output.

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

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

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

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

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

       The formatting dcmds are:

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

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

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

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

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

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

       +	 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  tar-
       get's  virtual address space, physical address space, or	object file by
       specifying one of the following modifiers as the	first  format  charac-
       ter, and	then specifying	a list of words	that are either	immediate val-
       ues or expressions enclosed in square brackets  preceded	 by  a	dollar
       sign ($[	]).

       The write modifiers are:

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

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

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

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

       The  /, \, and ?	formatting dcmds can also be used to search for	a par-
       ticular integer value in	the target's virtual address  space,  physical
       address	space, and object file,	respectively, by specifying one	of the
       following modifiers as the first	format character, and then  specifying
       a value and optional mask. The value and	mask are each specified	as ei-
       ther immediate values or	expressions enclosed in	square	brackets  pre-
       ceded  by  a dollar sign. If only a value is specified, mdb reads inte-
       gers of the appropriate size and	stops at the  address  containing  the
       matching	 value.	If a value V and mask M	are specified, mdb reads inte-
       gers of the appropriate size and	stops  at  the	address	 containing  a
       value  X	 where (X & M) == V. At	the completion of the dcmd, dot	is up-
       dated 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 typi-
       cally composed of a set of discontiguous	segments. It is	not  legal  to
       read  from  an address that does	not have a corresponding segment. If a
       search reaches a	segment	boundary without  finding  a  match,  it  will
       abort when the read past	the end	of the segment boundary	fails.

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

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

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

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

       The  execution  control	built-in  dcmds,  described  below, are	always
       available, but will issue an error message indicating they are not sup-
       ported  if applied to a target that does	not support execution control.
       For more	information about the interaction of  exec,  attach,  release,
       and job control with debugger execution control,	refer to NOTES,	below.

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

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

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

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

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

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

       > variable-name
       >/modifier/variable-name

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

	   c	    unsigned char quantity (1-byte)

	   s	    unsigned short quantity (2-byte)

	   i	    unsigned int quantity (4-byte)

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

	   Notice  that	 these	operators do not perform a cast. Instead, they
	   fetch the specified number of low-order bytes (on little-endian ar-
	   chitectures)	 or high-order bytes (big-endian architectures). Modi-
	   fiers 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 file-
	   name	may be given as	an absolute or relative	path. If the  filename
	   is  a simple	name (that is, if it does not contain a	'/'), mdb will
	   search for it in the	macro file include path. If another macro file
	   is currently	being processed, this file is closed and replaced with
	   the new file.

       $<< 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 informa-
	   tion. If the	dcmd is	preceded by an explicit	address,  a  backtrace
	   beginning  at  this	virtual	memory address is displayed. Otherwise
	   the stack of	the representative thread is displayed.	If an optional
	   count  value	 is given as an	argument, no more than count arguments
	   are displayed for each stack	frame in the output.

       [ base ]	$d

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

       $e

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

       $P prompt-string

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

       distance	$s

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

       $v

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

       width $w

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

       $W

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

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

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

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

	   Set a breakpoint at the specified locations.	The ::bp dcmd  sets  a
	   breakpoint  at  each	 address or symbol specified, including	an op-
	   tional address specified by an explicit  expression	preceding  the
	   dcmd,  and  each  string or immediate value following the dcmd. The
	   arguments may either	be symbol names	or immediate values denoting a
	   particular  virtual address of interest. If a symbol	name is	speci-
	   fied, it may	refer to a symbol that cannot yet be evaluated in  the
	   target process. That	is, it may consist of an object	name and func-
	   tion	name in	a load object that has not yet been opened.   In  this
	   case,  the  breakpoint is deferred and it will not be active	in the
	   target until	an object matching  the	 given	name  is  loaded.  The
	   breakpoint  will  be	 automatically enabled when the	load object is
	   opened. Breakpoints on symbols defined in a shared  library	should
	   always  be set using	a symbol name and not using an address expres-
	   sion, as the	address	may refer to the corresponding Procedure Link-
	   age	Table  (PLT)  entry  instead  of the actual symbol definition.
	   Breakpoints set on PLT entries may be overwritten by	 the  run-time
	   link-editor	when the PLT entry is subsequently resolved to the ac-
	   tual	symbol definition. The -d, -D, -e, -s, -t, -T, -c, and -n  op-
	   tions have the same meaning as they do for the ::evset dcmd,	as de-
	   scribed below. If the :b form of the	dcmd is	used, a	breakpoint  is
	   only	set at the virtual address specified by	the expression preced-
	   ing 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	 may  specified	 as  a
	   relative or absolute	pathname. The file contents will be printed to
	   standard output, but	will not be passed to the output  pager.  This
	   dcmd	is intended to be used with the	| operator; the	programmer can
	   initiate a pipeline using a list of addresses stored	in an external
	   file.

       ::cont [	SIG ]
       :c [ SIG	]

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

       address ::context
       address $p

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

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

       ::dcmds

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

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

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

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

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

       ::disasms

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

       ::dismode [ mode	]
       $V [ mode ]

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

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

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

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

	   Print a hexadecimal and ASCII memory	dump of	 the  16-byte  aligned
	   region  of memory containing	the address specified by dot. If a re-
	   peat	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	corre-
			   sponding  to	 the  given virtual address instead of
			   from	the target's virtual address space. The	-f op-
			   tion	 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 op-
			   tion	implies	the -u option.

	   -s		   Elides repeated lines.

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

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

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

       ::echo [	string | value ...]

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

       ::eval command

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

	   Action	   The callback	string to execute when the correspond-
			   ing	software  event	 occurs. This callback is exe-
			   cuted as if	it  had	 been  typed  at  the  command
			   prompt.

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

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

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

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

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

	   -s	    Stops  the	target	program	when the hit count reaches the
		    hit	limit. If the +s form of the option is given, this be-
		    havior  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	speci-
		    fiers  are	automatically deleted the next time the	target
		    stops, regardless of whether it stopped as the result of a
		    software  event  corresponding  to the given specifier. If
		    the	+t form	of the option is given,	the  temporary	marker
		    is removed.	The -t option takes precedence over the	-T op-
		    tion.

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

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

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

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

       ::files
       $f

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

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

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

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

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

       ::formats

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

       ::grep command

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

       ::help [	dcmd-name ]

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

       signal :i

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

       $i

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

       ::kill
       :k

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

       $l

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

       $L

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

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

	   Walk	through	the elements of	a linked list data structure and print
	   the	address	 of each element in the	list. The address of the first
	   element in the list can be specified	 using	an  optional  address.
	   Otherwise,  the  list  is  assumed to start at the current value of
	   dot.	The type parameter must	name a C struct	or union type  and  is
	   used	to describe the	type of	the list elements so that mdb can read
	   in objects of the appropriate size. The member parameter is used to
	   name	 the  member  of type that contains a pointer to the next list
	   element. The	::list dcmd  will  continue  iterating	until  a  NULL
	   pointer  is encountered, the	first element is reached again (a cir-
	   cular list),	or an error occurs while reading an  element.  If  the
	   optional variable-name is specified,	the specified variable will be
	   assigned the	value returned at each step of the walk	when  mdb  in-
	   vokes  the  next  stage  of a pipeline. The ::list dcmd may only be
	   used	with objects that contain symbolic debugging  information  de-
	   signed  for use with	mdb. Refer to NOTES, Symbolic Debugging	Infor-
	   mation, below for more information.

       ::load [	-s ] module-name

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

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

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

       ::map command

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

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

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

       ::next [	SIG ]
       :e [ SIG	]

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

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

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

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

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

	   -d			   Prints value	and size fields	in decimal.

	   -g			   Prints only global symbols.

	   -h			   Suppresses the header line.

	   -n			   Sorts symbols by name.

	   -o			   Prints value	and size fields	in octal.

	   -p			   Prints symbols as a series of ::nmadd  com-
				   mands.  This	 option	can be used with -P to
				   produce a macro file	 that  can  be	subse-
				   quently read	into the debugger with $<.

	   -u			   Prints only undefined symbols.

	   -v			   Sorts symbols by value.

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

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

				   noty	    STT_NOTYPE

				   objt	    STT_OBJECT

				   func	    STT_FUNC

				   sect	    STT_SECTION

				   file	    STT_FILE

				   comm	    STT_COMMON

				   tls	    STT_TLS

				   regi	    STT_SPARC_REGISTER

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

				   ndx	    symbol table index

				   val	    symbol value

				   size	    size in bytes

				   type	    symbol type

				   bind	    binding

				   oth	    other

				   shndx    section index

				   name	    symbol name

				   ctype    C type for symbol (if known)

				   obj	    object which defines symbol

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

	   Add the specified symbol name to the	private	symbol table. mdb pro-
	   vides  a private, configurable symbol table that can	be used	to in-
	   terpose on the target's symbol table,  as  described	 under	Symbol
	   Name	Resolution above. The ::nmadd dcmd also	recognizes the follow-
	   ing options:

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

	   -f	    Sets the type of the symbol	to STT_FUNC.

	   -o	    Sets the type of the symbol	to STT_OBJECT.

	   -s	    Sets the size of the symbol	to size.

       ::nmdel name

	   Delete the specified	symbol name from the private symbol table.

       ::objects [ -v ]

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

       ::offsetof type member

	   Print the offset of the specified member of the specified type. The
	   type	 should	be the name of a C structure. The offset is printed in
	   bytes, unless the member is a bit-field, in which case  the	offset
	   may	be printed in bits. The	output is always suffixed with the ap-
	   propriate units for clarity.	The type name may  use	the  backquote
	   (`) scoping operator	described under	Symbol Name Resolution,	above.
	   The ::offsetof dcmd may only	be used	with objects that contain sym-
	   bolic  debugging  information  designed  for	use with mdb. Refer to
	   NOTES, Symbolic Debugging Information, below	for more information.

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

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

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

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

       ::quit
       $q

	   Quit	the debugger.

       [ thread	] ::regs
       [ thread	] $r

	   Print the  general  purpose	register  set  of  the	representative
	   thread.  If a thread	is specified, the general purpose register set
	   of that thread is displayed.	The thread expression should be	one of
	   the thread identifiers described under Thread Support, above.

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

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

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

	   Start a new target program running with the specified arguments and
	   attach  to  it.  The	arguments are not interpreted by the shell. If
	   the debugger	is already examining a live running program,  it  will
	   first detach	from this program as if	by ::release.

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

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

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

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

	   -L	    Sets  the  default path for	locating debugger modules. The
		    path argument may contain any of the  special  tokens  de-
		    scribed 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  de-
		    scribed  along  with  the -o command-line option under OP-
		    TIONS.

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

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

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

       ::showrev [ -pv ]

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

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

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

       ::sizeof	type

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

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

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

       ::status

	   Print a summary of information related to the current target.

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

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

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

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

       thread ::tls symbol

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

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

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

       ::unload	module-name

	   Unload  the specified dmod. The list	of active dmods	may be printed
	   using the ::dmods dcmd. Built-in modules may	not be unloaded.  Mod-
	   ules	 that are busy (that is, provide dcmds that are	currently exe-
	   cuting) may not be unloaded.

       ::unset variable-name . . .

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

       ::vars [	-npt]

	   Print a listing of named variables. If the -n  option  is  present,
	   the output is restricted to variables that currently	 have non-zero
	   values. If the -p option is present,	the variables are printed in a
	   form	 suitable for re-processing by the debugger using the $< 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 ad-
	   dress, if possible. The ::vtop dcmd is only available when  examin-
	   ing a kernel	target,	or when	examining a user process inside	a ker-
	   nel crash dump (after a ::context dcmd has been issued).

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

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

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

       ::walkers

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

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

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

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

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

       ::xdata

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

       :z

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

OPTIONS
       The following options are supported:

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

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

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

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

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

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

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

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

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

		       The default include path	for 32-bit mdb is:

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

		       The default include path	for 64-bit mdb is:

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

       -k	       Forces  kernel debugging	mode. By default, mdb attempts
		       to infer	whether	the object and core file operands  re-
		       fer 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 ob-
		       ject file of /dev/ksyms and a core file	of  /dev/kmem.
		       Read  access  to	 /dev/kmem is restricted to group sys.
		       Write access requires ALL privileges.

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

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

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

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

		       adb

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

		       array_mem_limit=limit

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

		       array_str_limit=limit

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

		       follow_exec_mode=mode

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

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

			   follow   The	debugger follows the exec by automati-
				    cally continuing the  target  process  and
				    resetting  all  of its mappings and	symbol
				    tables based on the	new  executable.   The
				    follow  behavior  is discussed in more de-
				    tail 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, In-
				    teraction with Exec, below.

		       follow_fork_mode=mode

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

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

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

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

		       ignoreeof

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

		       nostop

			   Does	 not  stop a user process when attaching to it
			   when	the -p option is specified or when  the	 ::at-
			   tach	 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  de-
			   scribed  in	Symbol Name Resolution,	above. Symbols
			   on link maps	other than  LM_ID_BASE	or  LM_ID_LDSO
			   will	 be shown as LMlmid`library`symbol, where lmid
			   is the link-map ID  in  the	default	 output	 radix
			   (16). The user may optionally configure mdb to show
			   the link-map	ID scope of all	symbols	 and  objects,
			   including  those  associated	 with  LM_ID_BASE  and
			   LM_ID_LDSO, by enabling the showlmid	option.	Built-
			   in dcmds that deal with object file names will dis-
			   play	 link-map  IDs	according  to  the  value   of
			   showlmid above, including ::nm, ::mappings, $m, and
			   ::objects.

       -p pid	       Attaches	to and stops  the  specified  process-id.  mdb
		       will  use  the  /proc/pid/object/a.out file as the exe-
		       cutable file pathname.

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

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

       -s distance     Sets the	symbol matching	distance  for  address-to-sym-
		       bol-name	 conversions to	the specified distance.	By de-
		       fault, mdb sets the distance to zero, which  enables  a
		       smart-matching  mode.  Each  ELF	symbol table entry in-
		       cludes 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 ex-
		       pression	 above	is  always the specified absolute dis-
		       tance and the symbol size is ignored.

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

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

       -V version      Sets  disassembler version. By default, mdb attempts to
		       infer the appropriate disassembler version for the  de-
		       bug  target. The	disassembler can be set	explicitly us-
		       ing the -V option. The ::disasms	dcmd lists the	avail-
		       able disassembler versions.

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

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

OPERANDS
       The following operands are supported:

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

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

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

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

EXIT STATUS
       The following exit values are returned:

       0	Debugger completed execution successfully.

       1	A fatal	error occurred.

       2	Invalid	command	line options were specified.

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

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

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

FILES
       $HOME/.mdbrc

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

       /dev/kmem

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

       /dev/ksyms

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

       /proc/pid/*

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

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

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

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

	   Default  directories	for debugger modules that are loaded using the
	   ::load dcmd.	platform-name is the name of the platform, derived ei-
	   ther	 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),	 coreadm(1M),	 dumpadm(1M),	 largefile(5),
       savecore(1M),  exec(2),	fork(2),  _lwp_self(2),	  pipe(2),   vfork(2),
       dlopen(3C),  elf(3ELF),	libc_db(3LIB),	libkvm(3LIB), libthread(3LIB),
       signal(3C),  signal.h(3HEAD),  thr_self(3C),  core(4),	proc(4),   at-
       tributes(5), largefile(5), threads(5), ksyms(7D), mem(7D)

       Linker and Libraries Guide

       Solaris Modular Debugger	Guide

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

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

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

   Limitations on Examining Crash Dump Files
       Crash  dumps  from  Solaris 7 and earlier releases may only be examined
       with the	aid of the libkvm from the corresponding operating system  re-
       lease.  If  a  crash dump from one operating system release is examined
       using the dmods from a different	operating system release,  changes  in
       the  kernel implementation may prevent some dcmds or walkers from work-
       ing properly. mdb will issue a warning message if it detects this  con-
       dition. Crash dumps from	Solaris	x86 systems may	not be examined	on So-
       laris 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 au-
       tomatically 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 will use the same
       data  model as the primary target. Only the 64-bit debugger may be used
       to debug	64-bit target programs.	The 64-bit debugger can	only  be  used
       on a system that	is running the 64-bit operating	environment.

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

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

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

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

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

   Process Attach and Release
       When mdb	attaches to a running process, the process is stopped and  re-
       mains stopped until one of the continue dcmds is	applied, or the	debug-
       ger quits. If the -o nostop option is enabled prior  to	attaching  the
       debugger	 to  a	process	with -p, or prior to issuing an	::attach or :A
       command,	mdb attaches to	the process but	does not stop  it.  While  the
       process is still	running, it may	be inspected as	usual (albeit with in-
       consistent results) and breakpoints or other tracing flags may  be  en-
       abled. If the :c	or ::cont dcmds	are executed while the process is run-
       ning, 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,	 ::re-
       lease,  :r, ::run, $q, or ::quit	dcmds are executed, or when the	debug-
       ger terminates as the result of an EOF or signal. If  the  process  was
       originally  created  by	the  debugger  using  :r  or ::run, it will be
       forcibly	terminated as if by  SIGKILL  when  it	is  released.  If  the
       process	was  already  running prior to attaching mdb to	it, it will be
       set running again when it is released. A	process	may  be	 released  and
       left stopped and	abandoned using	the ::release -a option.

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

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

       The  header  file  <sys/mdb_modapi.h> contains prototypes for the func-
       tions in	the MDB	Module API, and	the SUNWmdbdm package provides	source
       code for	an example module in the directory /usr/demo/mdb.

SunOS 5.10			  26 Apr 2004				mdb(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | OPERANDS | USAGE | EXIT STATUS | ENVIRONMENT VARIABLES | FILES | ATTRIBUTES | SEE ALSO | WARNINGS | NOTES

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=mdb&sektion=1&manpath=SunOS+5.10>

home | help