unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



dbx(1)								       dbx(1)



NAME

  dbx -	source level debugger

SYNOPSIS

  dbx  [-I dir]	[-c file] [-k] [-i] [-r] [-pid xxx] [objectfile	[corefile]]

OPTIONS

  The dbx debugger accepts the following options:

  -c file
      Selects a	command	file other than	.dbxinit.

  -i  Invokes dbx in interactive mode.	This option causes the debugger	to
      not treat	source lines beginning with number signs (#) as	comments.

  -I dir
      Adds dir to the list of directories that dbx searches for	source files.
      By default, dbx searches the current directory and the directory where
      object is	located. You can specify multiple directories by using multi-
      ple -I options.

  -k  Maps memory addresses.  This option is useful for	kernel debugging. For
      information on kernel debugging, see the Kernel Debugging	manual.

  -module_path path
      Specifies	the directory path where dbx should search for shared
      libraries	(or loadable kernel modules).  This option is useful if, for
      example, you are debugging a core	dump (or a kernel crash	dump) and the
      version of a shared library (or module) that was running when the	dump
      occurred has been	moved to a different location. Using this option
      automatically sets the $module_path dbx variable to the specified	path.
      If dbx cannot find a file	in the specified directory, it looks in	the
      directory	where that file	was originally,	as recorded in the dump. See
      also the DBX_MODULE_PATH environment variable. For information on	ker-
      nel debugging, see the Kernel Debugging manual.

  -module_verbose
      Causes dbx to print the path of shared libraries (or loadable kernel
      modules, if debugging a kernel) as they are being	loaded.	By default,
      dbx does not print the path. Using this option automatically sets	the
      $module_verbose dbx variable to the value	1.  See	 also the
      DBX_MODULE_VERBOSE environment variable. For information on kernel
      debugging, see the Kernel	Debugging manual.

  -r  Executes the object file immediately.  If	program	execution terminates
      with an error, dbx displays the message that describes the error.	You
      can then either invoke the debugger or let the program continue exit-
      ing.  The	dbx debugger reads from	/dev/tty when you specify the -r
      option and standard input	is not a terminal.  If the program executes
      successfully, dbx	prompts	you for	input.

  -remote
      For use in debugging kernels.  (Refer to the Kernel Debugging manual
      for information on kernel	debugging.  For	information on debugging a
      running kernel using breakpoints,	refer to kdbx(8).)

  -emacs
      Outputs file and line number information in a format compatible with
      the emacs	function gdb.

  -pid xxx
      Attaches dbx to a	currently running process specified by process id
      xxx.

OPERANDS

  objectfile
      Specifies	the object file	that you want dbx to read as input.

      For complete dbx support,	the object file	must contain extended symbol
      table information. The supported compilers each have a -g	option that
      produces the symbol table	information in the object file.	The extended
      symbol table contains the	names of all the source	files processed	by
      the compiler as well as any symbolic information in those	files (for
      example, routine names, variable names, and line numbers). This infor-
      mation allows you	to look	at all of the source code that went into
      creating an object file during your debugging session. If	your object
      file does	not contain the	extended symbol	table information, use the
      commands described in the	Debugging at the Machine Code Level section
      to debug your program.

      If you omit objectfile, dbx prompts you for the name of an object	file.
      If you press the Return key, dbx attempts	to read	a file named a.out
      from the current directory. If no	a.out file exists, dbx exits.

  corefile
      Specifies	a core dump file, created if a program failed during execu-
      tion or if the coredump(1) command was used to take a core snapshot of
      a	running	process. The dump file holds an	image of memory	at the time
      the program failed or the	snapshot was taken. If you specify a core
      file on the command line,	dbx identifies where the program failed	or
      the snapshot was taken,  and you can then	use dbx	commands to determine
      the state	of the program at that time.

      Core dump	files are all named core by default. See the Programmer's
      Guide for	information about enabling core-file naming at the system or
      application level.

DBX COMMANDS

  The debugger supplies	a number of commands that you can issue	at the dbx
  prompt.

  Multiple commands can	be specified on	the same command line by separating
  them with a semicolon	(;).

  You can repeat dbx commands by pressing carriage return. Pressing carriage
  return repeats the last command issued to dbx. (This feature can be turned
  off by setting the $repeatmode variable to 0.)

  The following	sections describe the commands supported by dbx.






  Controlling the Monitor


  Use the following commands to	control	the dbx	monitor:

  !string or !integer or !-integer
      Executes a command from the history list.	 You can specify the command
      name in the string argument.  If you specify an integer, dbx executes
      the command having that number in	the history list. If you specify -
      integer, the debugger executes the command that you issued integer com-
      mands ago.  For example, if you specify -3, the debugger issues the
      command you issued three commands	ago.  The debugger echoes the command
      on standard output before	executing it.

  help [topic]
      With no argument,	displays a list	of topics for which help information
      is available. If you name	a topic, the debugger displays help informa-
      tion on that topic.

  history
      Displays a list of the previous commands you issued. By default, the
      debugger displays	the previous 20	commands. You can change the number
      of commands dbx keeps in the history list	by using the set command to
      modify the $lines	debugger variable.

      Predefined alias for history command: h

  quit
      Exit dbx.	 Predefined alias for quit command: q

  Controlling dbx


  Use the following commands to	control	the operation of the dbx debugger.

  alias	[name[(arg1,arg2,...)]string]
      Lists all	existing aliases or defines an alias. If you omit all argu-
      ments to the alias command, dbx displays a list of the existing
      aliases.

      You can supply arguments to define a new alias. If you specify a dbx
      command for string, the debugger assigns name as an alias	for that com-
      mand.  For example, to define an alias rr	for the	command	rerun, issue
      the following command:


	   (dbx) alias rr "rerun"

      If you specify parameters	in the alias command, the debugger substi-
      tutes the	values you supply on the command line when it executes the
      command.	For example, to	define halt as an alias	that sets a stop at a
      particular line, issue the following command:


	   (dbx) alias halt(x) "stop at	x"

      Once you issue this command, dbx interprets the following	commands as
      the same:


	   (dbx) halt(12)
	   (dbx) stop at 12

      Both commands set	a breakpoint at	source line 12.

      To remove	an alias, use the unalias command, as shown:


	   (dbx) unalias halt

  delete event-number, ... or delete all or delete *
      Deletes the specified breakpoint,	trace event, or	record event from the
      status list.  The	argument all and the argument *	delete all events
      from the status list.

      Predefined alias for delete command: d

  listobj
      Displays the names of the	objects	that have been loaded by dbx. These
      objects include the main program and all of the shared libraries that
      are used in the application.

  playback input [file]
      Replays commands that were saved with the	record input command in	a
      text file. If you	omit file, the debugger	reads commands from the	tem-
      porary file it creates by	default	when you issue the record input	com-
      mand.

      Predefined alias for playback input command: pi or source.

  playback output [file]
      Replays debugger output that was saved with the record output command.
      If you omit file,	the debugger displays output stored in a temporary
      file it creates by default when you issue	the record output command.

      Predefined alias for playback output command: po

  record input [file]
      Records all commands you enter at	the dbx	prompt.	 If you	omit file,
      the debugger creates a temporary file that it deletes when you exit
      from the debugger.

      The debugger associates an event number with each	record command you
      issue.  You use the event	number to turn off recording, as described
      with the delete command.

      Predefined alias for record input	command: ri

  record output	[file]
      Records all dbx output.  If you omit file, the debugger creates a	tem-
      porary file that it deletes when you exit	from the debugger. To record
      input and	output to the same file, set the $rimode debugger variable.

      The debugger associates an event number with each	record command you
      issue.  You use the event	number to turn off recording, as described
      with the delete command.

      Predefined alias for record output command: ro

  source file
      Executes the dbx commands	from the specified file.  This command is an
      alias for	the playback input command.

  status
      Lists current breakpoints, record	events,	and trace events.

      Predefined alias for status command: j

  set [variable	= expression]
      Lists existing debugger variables	and their values or defines a value
      for the named debugger variable.

      Some debugger variables contain either a zero or nonzero value that
      controls dbx behavior.  For example, when	set to a nonzero value,	the
      $hexstrings variable causes the debugger to display all strings in hex-
      adecimal format.	When set to zero, this variable	causes the debugger
      to display strings in character format.  You can set a variable like
      $hexstrings to a nonzero value as	shown:


	   (dbx) set $hexstrings = 1

      You can disable the variable using the unset command, as shown:


	   (dbx) unset $hexstrings

      You can create a debugger	variable using a name of your own.  A
      debugger variable	name you create	must not conflict with the name	of
      any variable in the program you are debugging, and it must not begin
      with a dollar sign ($).  For information on existing debugger vari-
      ables, see PREDEFINED DBX	VARIABLES.  (Use the assign command to change
      the value	of variables in	your program. See the section Preparing	for
      Program Execution	for information	on the assign command.)

  setenv name string
      Sets the environment variable name to string by changing the value of
      an existing environment variable or creating a new one. To reset the
      environment variable, specify a null string.  The	following example
      shows how	to reset the EDITOR environment	variable:


	   (dbx) setenv	EDITOR ""

  sh [shell command]
      Calls a shell from dbx or	executes the specified shell command. The sh
      command cannot be	used in	the action list	of the when and	wheni dbx
      commands.

  tagvalue (tagname)
      Returns the value	of tagname, where tagname is a tag that	marks a	func-
      tion or type definition in your program. If the tag extends to more
      than one line or if it contains arguments, the debugger issues an	error
      message. You can use tagvalue in commands	where you specify a procedure
      or function name.

      For example, if a	tag getline is associated with a function, the fol-
      lowing command is	valid:


	   (dbx) call tagvalue(getline)	()

      This command causes execution to begin at	the location associated	with
      the getline tag.

      You create tags using the	ctags command.	See ctags(1) for information.
      The debugger uses	the file named in the $tagfile variable	when resolv-
      ing references to	tags.

  unalias name
      Removes the specified alias.

  unset	variable
      Removes the setting of a specified debugger variable.




  Examining Source Code


  The following	commands allow you to examine your source files	during a
  debugging session:

  regular expression or	?regular expression
      Searches forward or backward in the source code for the regular expres-
      sion.

  edit [file]
      Invokes an editor	on file	or the current source file if none is speci-
      fied.  By	default, dbx invokes the vi editor.  You can override the
      default setting by modifying the EDITOR environment variable.

  file [file]
      Changes the current file to file,	or, if you omit	file, displays the
      name of the current file.

      Predefined alias for file	command: e

  func [expression]

  func [procedure]
      Changes the current procedure or function	to the one you specify.	 If
      you omit expression and procedure, the debugger displays the name	of
      the current procedure or function.

      Changing the current function implicitly changes the current source
      file to the one that contains the	procedure or function; it also
      changes the current scope	used for name resolution.

      Predefined alias for func	command: f

  list [source-line-number[:integer]]

  list [source-line-number[, source-line-number]]

  list [procedure]
      Lists the	lines in the current source file.

      If you specify a source line number and an integer, dbx lists beginning
      from source-line-number and continuing for integer number	of lines.  If
      you omit integer,	the debugger displays 10 lines by default.

      If you specify two source	line numbers separated by a comma, the
      debugger begins the display at the first source line number and contin-
      ues through the second source line number.  If you omit the second
      source line number, the debugger displays	10 lines by default.

      If you specify a procedure or function name, the debugger	displays
      lines in that procedure or function. The debugger	displays 10 lines by
      default.

      If you omit all arguments, the debugger begins the display at the
      current line and displays	10 lines by default.

      The $listwindow debugger variable	controls how many lines	the debugger
      displays.	The default value for $listwindow is 10.

      Predefined aliases for list command:

      l	      The next 10 lines	of source code.

      li      The next 10 machine instructions after the current machine
	      instruction.

      u	      The previous 10 lines of source code.

      w	      The five lines before and	after the current line.

      W	      The 10 lines before and after the	current	line.

      wi      The five machine instructions before and after the current one.

  tag tagname
      Sets the current source file or source line to the location specified
      by tagname.

      You create tags using the	ctags command.	See ctags(1) for more infor-
      mation.  The debugger uses the tag file named in the $tagfile debugger
      variable to resolve references to	tags.

  use [directory ...]
      Displays or sets the list	of directories that dbx	uses when searching
      for source files.	 If you	issue the use command without arguments, the
      debugger displays	the list of directories	it searches for	source files.
      To change	the directory list, specify the	names of the directories you
      want on the list as arguments to the use command.	 The directories you
      specify replace any existing directory list. Give	absolute or relative
      pathnames; ~ is not supported.

      The use command looks first for source files in the path consisting of
      the complete source path used when the file was compiled appended	to
      the directory specified in the use command.  If the use command cannot
      find the source file with	that path, it takes the	directory specified
      by the use command and only the filename part of the compilation source
      path.

      For example, when	you built the program, the sources were	in
      /usr/src/project.	 For some reason, perhaps because of different NFS
      mounting,	when you run it, the sources are in /project. You enter:


	   (dbx) use /project

      The use command looks for	/project/../../src/project/filename.c and
      cannot find it.  If you enter the	following command, the use command
      can find the source file:


	   (dbx) use /project/filename.c

  whatis variable or whatis struct name
      Displays the type	declaration for	variable. (If variable is a dbx	key-
      word, it must be enclosed	within parentheses.)

  whereis variable
      Displays the fully qualified name	of each	occurrence of variable.	The
      order in which the debugger displays the qualified names is not mean-
      ingful.  (If variable is a dbx keyword, it must be enclosed within
      parentheses.)

  which	variable
      Displays the fully qualified name	of variable. (If variable is a dbx
      keyword, it must be enclosed within parentheses.)






  Preparing for	Program	Execution


  Before you execute your program under	dbx control, you might want to per-
  form setup tasks, such as changing the value of debugger variables,
  specifying what signals your program should recognize	or ignore, and set-
  ting breakpoints. The	following commands allow you to	perform	these tasks:

  addobj path|file
      Loads a shared library and reads in the library's	symbol table.

      If you specify an	absolute or relative path (path) for the library, dbx
      looks only in the	specified location.  If	you specify only the library
      file name	(file),	dbx first looks	for that file in the directory speci-
      fied by the $module_path variable, if set. If $module_path is not	set
      or if dbx	cannot find the	file in	the specified directory, it looks in
      the directory where that file was	originally, as recorded	in the object
      (or in the dump, if debugging a core dump).

      Use this command only for	debugging applications that load in their own
      shared libraries instead of using	the dynamic loader. For	applications
      that do not load their own shared	libraries, dbx will obtain the names
      of the shared libraries from the dynamic loader.

      Limitation: dbx will not work correctly when a shared library is added
      with the addobj command and the library is loaded	at an address that
      differs from the address at which	it was linked.

      You can also use the addobj command to load loadable modules when
      debugging	a kernel. In general, the basic	considerations described
      above for	shared libraries also apply to loadable	modules. For complete
      information on kernel debugging, see the Kernel Debugging	manual.

  assign variable = expression

  assign expression1 = expression2
      Assigns the value	of the specified expression to the specified program
      variable.	The program must be running for	the assign command to work.
      (If variable is a	dbx keyword, it	must be	enclosed within	parentheses.)

      Use the set command to set the value of debugger variables.

      Predefined alias for assign command: a

  catch	[signal]
      Lists all	signals	that dbx catches or, if	you supply an argument,
      causes dbx to catch that signal.	The signal you specify is added	to
      the list of signals dbx catches, so the debugger continues to catch any
      signals that were	already	on its list.  Some signals cannot be caught
      by any process. For a list of signals and	information on which signals
      can be caught, see signal(4) for more information.

  ignore [signal]
      Lists all	signals	that dbx ignores.  If you specify a signal, this com-
      mand adds	the signal to the list of signals the debugger ignores.	 Some
      signals cannot be	ignored	by any process.	 For a list of signals and
      information on which signals can be ignored, see signal(4) for more
      information.

  patch	variable = expression patch expression1	= expression2
      Patches executable disk files to correct bad data	or instructions. The
      text, initialized	data, or read-only data	areas can be patched. The bss
      segment cannot be	patched	because	it does	not exist in disk files.

      Examples:


	   patch &main = 0
	   patch foo = 20 or patch &foo	= 20
	   patch 0xnnnnn = 0xnnnnn

  stop variable

  stop [variable] at source-line [if condition]

  stop [variable] in procedure [if condition]

  stop [variable] if condition
      Stops execution when the specified variable changes value, the speci-
      fied source line is reached, the specified procedure or function is
      called, or the specified condition is true. The condition	must be	a
      Boolean expression. (If variable is a dbx	keyword, it must be enclosed
      within parentheses.)

      If you specify variable with a source line number, the debugger stops
      execution	when the source	line number is reached and the variable
      changes value. If	you specify variable with in procedure,	the debugger
      stops execution when it is executing in the named	procedure or function
      and the named variable changes value.  With if condition,	the debugger
      stops execution when the condition is met	and the	variable changes
      value.

      If you specify a condition with at source-line or	in procedure, the
      debugger stops only if the condition is true.

      The debugger associates an event number with each	stop command you
      issue.  You use the event	number to remove the breakpoint, as described
      with the delete command.

      Predefined aliases for stop command:

      b	  Sets a breakpoint at a specified line.

      bp  Stops	in a specified procedure.

  trace	[at] source-line

  trace	procedure

  trace	variable [at source-line] [if condition]

  trace	variable [in procedure]	[if condition]
      Displays tracing information during program execution.  The dbx
      debugger associates an event number with each trace command you issue.
      You use the event	number to turn off tracing, as described with the
      delete command. (If variable is a	dbx keyword, it	must be	enclosed
      within parentheses.)

      The first	argument to the	trace command specifies	what the debugger is
      to trace.	 You can specify a source line number, a procedure name, or a
      variable name.

      If you specify a source line number, dbx displays	the source line
      immediately prior	to executing it.  You can specify a source line
      number in	a source file that is not the current one.  To do so, precede
      the source line number with the source file name in quotation marks ("
      ") followed by a colon (:), as shown in the following example:


	   (dbx) trace at "source_file.c":17

      The example specifies tracing line 17 in source_file.c.

      Specifying a procedure or	function name causes dbx to display the	name
      of the calling routine, the source line that contains the	call, and the
      parameters that are passed to the	called routine.	 In addition, dbx
      notes the	return of the named procedure or function and displays the
      return value, if any.  The debugger displays this	information each time
      the procedure or function	is called.

      Specifying a variable name causes	dbx to display the name	and value of
      the variable each	time it	changes. Program execution is substantially
      slower during this form of tracing.

      If you specify the in procedure clause, dbx displays tracing informa-
      tion only	while executing	the specified procedure	or function.

      The condition is a Boolean expression that dbx evaluates prior to
      displaying any tracing information.  The debugger	displays tracing
      information only if the condition	is true.

      Predefined alias for trace command: tr

  when [variable] [at line] {command_list}

  when [variable] [in procedure] {command_list}
      Executes the specified dbx command list.	You can	separate the commands
      by commas	(,) or semi-colons (;).

      If you specify variable, the debugger executes the command list when
      the value	of the variable	changes.  Specify at line or in	procedure to
      control which occurrence of the variable causes the debugger to execute
      the command list.	(If variable is	a dbx keyword, it must be enclosed
      within parentheses.)

  Initiating Program Execution


  The following	commands allow you to control program execution:

  call procedure ([parameters])

  print	procedure ([parameters])
      Executes the object code associated with the named procedure or func-
      tion.  This command passes the specified parameters to the procedure or
      function.

      The print	and call commands treat	values returned	by called procedures
      differently: the print command displays them and the call	command	does
      not.

  [n] cont [signal]

  cont [signal]	to source-line

  cont [signal]	in procedure
      Continues	execution from where it	stopped. If you	specify	an integer n,
      the debugger ignores that	number of stops	after it resumes program exe-
      cution. If you specify signal, the process continues as though it
      received the signal.

      If you specify to	source-line, the debugger continues execution until
      it reaches the specified source line.

      If you specify in	procedure, the debugger	continues until	the specified
      procedure	after receiving	the specified signal.

      Predefined alias for cont	command: c

  goto source-line
      Branches to the specified	source line. Execution continues from that
      point when you issue a cont command.

      Predefined alias for goto	command: g

  next [integer]
      Executes up to the next source line.

      The next command does not	step into procedures of	functions; execution
      stops at the source line that follows the	call. If you specify integer,
      the debugger performs the	specified number of next commands.

      Predefined alias for next	command: n

  rerun	[arg1, arg2,...] [<&lt;file1][>&gt;file2]

  rerun	[arg1, arg2,...] [<&lt;file1][>&gt;&&amp;file2]
      Reruns the program, using	the same arguments that	were specified with
      the run command. If you specify new arguments, rerun uses	those argu-
      ments.

      You can use angle	brackets (< or >) to redirect input or output in the
      usual manner.

      Predefined alias for rerun command: r

  run [arg1,arg2,...] [<&lt;file1] [>&gt;file2]

  run [arg1,arg2,...] [<&lt;file1] [>&gt;&&amp;file2]
      Runs the program,	passing	it the specified arguments. Arguments con-
      taining brackets ([]), asterisks (*), or other special characters	must
      be enclosed in quotes or escaped to avoid	parsing	errors.

      You can use angle	brackets (< or >) to redirect input or output in the
      usual manner.

  return [procedure]
      Executes until a return to procedure is executed or until	the current
      procedure	or function returns if you omit	procedure.

  step [integer]
      Executes one source line.	 If the	source line contains a call to a pro-
      cedure or	function, the step command stops at the	first line of the
      procedure	or function.  (The debugger does not stop at the first line
      of a procedure or	function if you	compiled your program without using
      the -g option.)

      If you specify integer, the debugger performs the	specified number of
      step commands.

      Predefined alias for step	command: s

  Examining Program State


  Use the following commands to	determine the state of your program:

  dump [procedure] [.]
      Displays variable	information about the named procedure or function, or
      the current procedure or function	if you do not specify one.  If you
      specify dot (.), the debugger displays information on all	procedures or
      functions	in the stack and their variables.

  down [expression]
      Moves the	current	function down in the stack (based on the number	of
      activation levels	that you specify). The default is one level.

  up [expression]
      Moves the	current	function up in the stack (based	on the number of
      activation levels	that you specify).  The	default	is one level.

  print	expression1,expression2,...
      Displays the value of the	specified expression.  (If a specified
      expression contains the name of a	variable that is also a	dbx keyword,
      the variable name	must be	enclosed within	parentheses.)

      Predefined alias for print command: p

  printf format, arg1,arg2,...
      Formats an expression as specified.  You use the same format specifiers
      for this command as for the printf subroutine.  For information on
      specifying the format, see printf(3). (The %s conversion specification
      is not supported.)

      Predefined aliases for printf command print the following	values:

      pd  The specified	expression or variable in decimal.

      po  The specified	expression or variable in octal.

      px  The specified	expression or variable in hexadecimal.

  printregs
      Displays all register values.

      Predefined alias for printregs command: pr

  where	[n]
      Displays a list of the active procedures and functions. If you specify
      n, the debugger displays only procedures and functions in	the top	n
      levels of	the stack.

      Predefined alias for where command: t

  Attaching to a Running Process


  The dbx debugger supports /proc debugging.  The major	advantage of this is
  that it allows attaching to a	running	process	and this can be	used to
  attach to a child process.  In order to do this, the /proc filesystem	must
  be mounted. The following commands are available to attach to, and detach
  from,	a running process:

  attach xxx
      Use this command to attach to a running process, where xxx is the	proc
      id of the	process	you want to attach to.	This command checks to see if
      /proc is mounted.	 If it is mounted, dbx will then look for the proc id
      in /proc.	 If the	proc id	is present, dbx	will attempt to	open the pro-
      cess, issue a stop command, report the current position, and issue the
      dbx>&gt; prompt.

  detach [xxx]
      Use this command to detach from a	running	process, where the optional
      xxx is the proc id of the	process	you want to detach from.

  switch xxx
      Use this command to switch from one process to another, where xxx	is
      the proc id of the process you want to switch to.	 You must already
      have attached to the target process using	the attach command.

  plist
      Use this command to display a list of active processes and their
      status.  The debugger indicates the current process with a marker: -->&gt;



  Debugging at the Machine Code	Level


  You can use machine level commands to	debug any program, regardless of
  whether the program object file contains extended symbol table information.

  You can specify symbolic addresses by	preceding the name with	an ampersand
  (&&amp;).	You denote registers by	$rN, where N is	the number of the register.
  Addresses may	be expressions made up of other	addresses and the operators
  plus (+), minus (-), and indirection (unary asterisk,	*).

  Use the following commands to	debug programs at the machine code level:

  address/count	mode

  address?count	mode
      Searches forward (or backward, if	you specify ?) and displays the	con-
      tents of address or disassembles the code	for the	instruction address.
      The count	argument specifies the number of items that the	debugger
      displays at the specified	address. The mode determines how dbx displays
      memory; if you omit it, the debugger uses	the previous mode. The ini-
      tial mode	is X.  You can specify the following modes:

      b	  Displays a byte in octal.

      c	  Displays a byte as a character.

      d	  Displays a 16-bit value in decimal.

      dd  Displays a 32-bit value in decimal.

      D	  Displays a 64-bit value in decimal.

      f	  Displays a single precision real number.

      g	  Displays a double precision real number.

      i	  Displays machine instructions.

      n	  Displays data	in typed format.

      o	  Displays a 16-bit value in octal.

      oo  Displays a 32-bit value in octal.

      O	  Displays a 64-bit value in octal.

      s	  Displays a string of characters that ends in a null.

      x	  Displays a 16-bit value in hexadecimal.

      xx  Displays a 32-bit value in hexadecimal.

      X	  Displays a 64-bit value in hexadecimal.

      The debugger maintains the next address to be displayed in dot (.).  To
      display the next address,	you can	use the	following command:


	   (dbx) ./

      The debugger will	display	the next count locations in the	mode speci-
      fied in the previous command.

  address/countM value mask
      Searches for a 64-bit word that satisfies	the mask. The debugger starts
      searching	at the specified address. The count argument specifies the
      number of	words the debugger processes during the	search.	 You type the
      M	to specify a match.

      The debugger masks the word stored at address using the value specified
      in mask. If the masked value equals value, the debugger displays the
      address of the masked value.  Otherwise, the debugger increments
      address and continues to search.

  [n] conti [signal]

  conti	[signal] to address

  conti	[signal] in procedure
      Continues	execution of assembly code from	where it stopped. If you
      specify an integer n, the	debugger ignores that number of	stops after
      it resumes program execution. If you specify signal, the process con-
      tinues as	though it received the signal.

      If you specify to	address, the debugger continues	execution until	it
      reaches the specified address.

      If you specify in	procedure, the debugger	resumes	execution in the
      named procedure or function.

  nexti	[integer]
      Executes up to the next machine instruction. The nexti command does not
      step into	procedures or functions; execution stops at the	machine
      instruction that follows the call.

      If you specify an	integer, the debugger performs integer nexti instruc-
      tions.

      Predefined alias for nexti command: ni

  stepi	[integer]
      Executes the specified number of machine instructions.  If one of	the
      machine instructions contains a call to a	procedure or function, the
      debugger stops at	the first instruction of the procedure or function.
      The default is to	execute	one instruction.

      Predefined alias for stepi command: si

  stopi	variable

  stopi	[variable] [at address]	[if condition]

  stopi	[variable] [in procedure] [if condition]
      Stops when the specified variable	changes	value, the specified address
      is reached, the specified	condition is true, or the specified procedure
      or function is reached.  (If variable is a dbx keyword, it must be
      enclosed within parentheses.)

      By combining the arguments, you can cause	the debugger to	stop, for
      example, only when the occurrence	of variable at the specified address
      changes value and	condition is true.

  tracei variable [at address] [if expression]

  tracei variable [in procedure] [at address] [if expression]

  tracei address [if condition]
      Traces the value of variable or the execution of a particular address.
      (If variable is a	dbx keyword, it	must be	enclosed within	parentheses.)

      When you trace the value of a variable, you can use at address, in pro-
      cedure, and if condition to control the specific variable	that is
      traced.

      You can specify a	condition when you trace the execution of an address.
      The debugger displays tracing information	only when the condition	is
      true.

  wheni	[variable] [at address]	{command_list}

  wheni	[variable] [in procedure] {command_list}
      Executes the specified dbx machine command list.	You can	separate the
      commands by commas (,) or	semi-colons (;).

      If you specify variable, the debugger executes the command list when
      the value	of the variable	changes.  Specify at address or	in procedure
      to control which occurrence of the variable causes the debugger to exe-
      cute the command list.  (If variable is a	dbx keyword, it	must be
      enclosed within parentheses.)

PREDEFINED DBX VARIABLES

  The debugger contains	variables that control certain aspects of its opera-
  tions.  Some debugger	variables are used internally by dbx.  You must	not
  change the value of those variables.	The debugger allows you	to change the
  values of other variables using the set and unset commands.  The following
  list describes the debugger variables	you can	control:

  $addrfmt
      Specifies	the format for addresses.  You can set this variable to	any
      format that you can use with the printf function,	except %s because the
      %s conversion specification is not supported by dbx.  See	printf(3)
      reference	page for information on	valid formats.	By default, this
      variable is set to 0x%x, which specifies hexadecimal format.

  $asynch_interface
      When set to a positive nonzero value, indicates that dbx is in asyn-
      chronous mode.  When 0 (zero) or negative, indicates that	asynchronous
      debugging	is disabled.  Incremented by 1 when a new process is attached
      and decremented by 1 when	a process terminates or	is detached.  The
      default value is 0. To prevent dbx from entering asynchronous mode, set
      $asynch_interface	to a negative value.

  $casesense
      When set to a nonzero value, specifies that uppercase and	lowercase
      letters be treated as different characters during	a search.  When
      $casesense is set	to zero, dbx ignores the case of letters.  The
      default is zero.	The $casesense variable	has no effect on the
      interpretation of	eight-bit characters; thus, for	example, A-acute-
      accent and a-acute-accent	are always treated as different	characters.

  $datacache
      Caches information from the data space so	that dbx must access the data
      space only once. If this variable	is set to zero,	the debugger does not
      cache data space.	If your	program	contains any data declared as vola-
      tile, you	may want to set	this variable to zero.	To debug the operat-
      ing system, set this variable to zero; otherwise,	set it to a nonzero
      value.  The default is a nonzero value.

  $dispix
      Causes the debugger to be	in the correct mode to debug pixie code. When
      set to zero, the debugger	displays machine code while debugging. When
      set to a nonzero value, the debugger displays pixie code.	The default
      is zero.

  $hexchars
      When set to a nonzero value, causes the debugger to display characters
      in hexadecimal format.

  $hexin
      When set to a nonzero value, causes the debugger to interpret input
      constants	as hexadecimal.	 When set, this	variable overrides the $octin
      variable.

  $hexints
      When set to a nonzero value, changes the default output constants	to
      hexadecimal.  When set, this variable overrides the $octints variable.

  $hexstrings
      When set to a nonzero value, causes the debugger to display all strings
      in hexadecimal format.  When set to zero,	causes the debugger to
      display strings in character format.

  $historyevent
      Stores the current history line.

  $lines
      Determines how many lines	the debugger stores in its history list. The
      default is 20 lines.

  $listwindow
      Specifies	how many lines the list	command	displays. The default is 10
      lines.

  $main
      Specifies	the name of the	procedure or function that dbx begins when
      running the process. The debugger	can begin a process at any procedure
      or function.  By default,	the debugger begins a process at a procedure
      named main.

  $maxstrlen
      Specifies	how many characters of a string	dbx displays for pointers to
      strings.	The default is 128 characters.

  $module_path
      Specifies	the directory path where dbx should search for shared
      libraries	(or loadable kernel modules). This variable is useful if, for
      example, you are debugging a core	dump (or a kernel crash	dump) and the
      version of a shared library (or module) that was running when the	dump
      occurred has been	moved to a different location. Setting this variable
      with the set command affects only	any files that are loaded after	the
      variable is set. To affect files that are	loaded at dbx startup, use
      the -module_path option or the DBX_MODULE_PATH environment variable.
      See also the addobj command. For information on kernel debugging see
      the Kernel Debugging manual.

  $module_verbose
      When set to a nonzero value, causes dbx to print the location of shared
      libraries	(or loadable kernel modules, if	debugging a kernel) as they
      are being	loaded.	By default, or when this variable is set to zero, dbx
      does not print the location. See also the	-module_verbose	option and
      the DBX_MODULE_VERBOSE environment variable. For information on kernel
      debugging, see the Kernel	Debugging manual.

  $octin
      When set to a nonzero value, changes the default input constants to
      octal.  When set,	the $hexin variable overrides this variable.

  $octints
      When set to a nonzero value, causes dbx to display integers in octal
      format.  When set, the $hexints variable overrides this variable.

  $page
      Specifies	whether	to page	long information. A nonzero value turns	on
      paging; a	zero turns it off.  The	default	is one.

  $pagewindow
      Specifies	how many lines the debugger displays when information runs
      longer than one screen.  You can change this variable to match the
      number of	lines on any terminal.	If set to zero,	this variable assumes
      one line.	 The default is	65.

  $printcplusparams
      This variable affects only C++ modules. It specifies whether to print
      function parameters from C++ modules when	displaying a stack trace (as
      from a where command). A nonzero value enables this feature. A value of
      zero (the	default) disables it --	that is, a C++ parameter list is
      shown empty in the stack trace (for example, my_routine()).

      The default was chosen because dbx does not support complex C++ types
      beyond those supported for C, and	a segmentation fault will occur	if
      dbx tries	to print function parameters of	complex	C++ types in a stack
      trace. (However, dbx then	regains	control	and displays its prompt.) If
      you are debugging	C++ modules that have only simple (C) function-
      parameter	types, setting $printcplusparams to 1 will enable dbx to
      print these parameters in	a stack	trace.

  $printwhilestep
      Determines whether the debugger displays source lines or instructions
      when executing the step[n] and stepi[n] commands.	When set to a nonzero
      value, causes dbx	to display all n lines or instructions.	 When set to
      zero, causes dbx to display only the last	line or	instruction.  The
      default is zero.

  $pimode
      Displays input when used with the	playback input command.	The default
      is zero.

  $printdata
      When set to a nonzero value, causes the debugger to display the con-
      tents of registers next to each instruction it displays. The debugger
      displays the registers used by the instruction.  The default is zero.

  $printwide
      When set to a nonzero value, causes the debugger to display the con-
      tents of variables in a horizontal format. The default is	zero.

  $prompt
      Sets the prompt for dbx.

  $readtextfile
      When set to a nonzero value, causes dbx to read instructions from	the
      object file rather than the process. This	variable should	always be set
      to zero when the process being debugged copies in	code during the
      debugging	process.  The default is a nonzero value.

  $regstyle
      When set to a nonzero value, causes the debugger to display registers
      during disassembly in their normal r format (r0,r1,...,r31). When	set
      to zero, causes the debugger to display registers	in a special format
      (zero, at, v0, v1,...), which is commonly	used in	debugging programs
      written in assembly language. The	default	is a nonzero value.

      Setting this variable does not affect how	the debugger displays the
      names of registers when you issue	the printregs command.	This variable
      affects the debugger's machine level commands.

  $repeatmode
      When set to a nonzero value, causes dbx to repeat	the previous command
      if you press the Return key at the dbx prompt.  The default is a
      nonzero value.

  $rimode
      When set to a nonzero value, causes the debugger to record input while
      recording	output.	 The default is	zero.

  $sigvec
      Tells dbx	the name of the	code called by the system to invoke user sig-
      nal handlers.  This variable is set to sigaction on Tru64	UNIX systems.

  $stop_all_forks
      Meaningful only when $stop_on_fork is set.  If set to 1, dbx stops
      every time a new image is	forked.	If set to 0, dbx ignores most forks
      arising from system and library calls.  The default is 0.

  $stop_on_exec
      When set to 1, *Ldbx detects calls to execl and execv and	stops the
      newly executed images at the first line of executable code.  The
      default is 1.

  $stop_on_fork
      If set to	1, specifies that dbx should stop when a new image is forked.
      If set to	0, instructs dbx to continue into the new image	without	stop-
      ping.  The default is 1.

  $tagfile
      Names the	file that contains tags	for the	current	program.  The tag and
      tagvalue commands	search the named file to resolve references to tags.
      For more information on using tag	files, see ctags(1).

  $traploops
      Specifies	the number of times dbx	can ignore a SIGTRAP without being
      interrupted by another signal or breakpoint type.	 This variable helps
      avoid the	infinite loop that can occur when you set a breakpoint in a
      SIGTRAP signal handler function.	The default number for this variable
      is 3.

DESCRIPTION

  The dbx command invokes a source-level debugger.  You	can use	dbx to debug
  programs written in C, Fortran, Pascal, assembly language, and machine
  code.	Languages other	than these are not supported by	dbx. After invoking
  the dbx debugger, you	issue dbx commands that	allow you to examine source
  files, control program execution, display the	state of the program, and
  debug	at the machine level.

  The OPERANDS section describes the objectfile	and corefile operands. Be
  sure to compile your program with the	-g option so that the object file
  contains the symbol table information	needed for source-level	debugging.

  You can use command options to modify	some steps that	dbx performs during
  startup. (For	information on the available options, see the OPTIONS sec-
  tion.) Unless	you specify the	-r option, dbx prompts you for a command
  before it begins executing your program. The dbx prompt appears as follows:

       (dbx)


  To leave dbx,	issue the quit command.

  See the Guide	to the POSIX Threads Library for information on	how to debug
  multithreaded	applications.



  Initialization File


  During its startup, dbx reads	and executes the commands in an	initializa-
  tion file (if	present).  By default, dbx searches for	the initialization
  file .dbxinit	in the current directory.  If no .dbxinit file exists in the
  current directory, dbx searches your home directory for the file. You	can
  use the initialization file to issue setup commands automatically when you
  begin	a dbx session. (See the	section	PREDEFINED DBX VARIABLES for informa-
  tion on the debugger variables that you can control in the initialization
  file.)

  Debugger Expressions


  You specify dbx expressions using the	C syntax for expressions.  The
  debugger supports a subset of	the expression syntax. For example, you	can
  denote indirection using either an asterisk (*) as a prefix or a circumflex
  (^) as a suffix. You can use the field reference operator (.)	with pointers
  as well as with records or structures, making	the C operator (->) unneces-
  sary (although it is supported).

  You must enclose array expressions in	brackets ([ ]).

  You can also specify a register name in an expression. You denote registers
  by $rN where N is the	number of the register.

  The debugger supports	symbol names and string	literals containing display-
  able characters in the eight-bit ISO Latin-1 character set.

  Debugger Name	Resolution


  The debugger resolves	names by searching for the name	in the static scope
  of the current function.  If no name is defined in the static	scope, the
  debugger searches the	dynamic	scope.	If neither scope yields	a defined
  name,	the debugger chooses an	arbitrary symbol and displays the following
  message:

       [using qualified.name]

  The debugger substitutes the qualified name of the arbitrary symbol for
  qualified.name in the	message.

  You can override this	name resolution	procedure by qualifying	identifiers
  with a block name, as	in module.variable. For	the C language,	the debugger
  treats a source file as a module named from the filename without the .c
  suffix.

  Command Line Editing


  The dbx monitor provides commands that permit	command-line editing. These
  commands allow you to	correct	mistakes without re-entering an	entire com-
  mand.	 There are two line-editing modes, vi mode and emacs mode.

  To enable a mode similar to the Korn shell's vi mode,	set the	EDITOR or
  EDITMODE environment variable	to a path ending in vi before starting dbx.
  In vi	mode, the following editing keys are recognized:

       $ + - 0 A B C D E F I R S W X ^
       a b c d e f h i j k l r s w x ~
       Ctrl/D
       Ctrl/H
       Ctrl/J
       Ctrl/L
       Ctrl/M
       Ctrl/C

  See ksh(1) for more information.

  To enable a mode similar to the Korn shell's emacs mode, set the LINEEDIT
  environment variable to any value, or	set EDITOR or EDITMODE to a path end-
  ing in emacs,	before starting	dbx.  The debugger treats ^K differently
  depending on whether the mode	is enabled by LINEEDIT or by EDITOR or EDIT-
  MODE.	In emacs mode, the following editing keys are recognized:

  ^A  Move the cursor to the beginning of the command line.

  ^B  Move the cursor back one character.

  ^C  Clear the	line.

  ^D  Delete the character at the cursor.

  ^E  Move the cursor to the end of the	line.

  ^F  Move the cursor ahead one	character.

  ^H  Delete the character immediately preceding the cursor.

  ^J  Execute the line.

  ^K<char>
      (When enabled by LINEEDIT) Delete	characters until the cursor rests on
      the next occurrence of char.

  ^K  (When enabled by EDITOR or EDITMODE)   Delete from the cursor to the
      end of the line.	If preceded by a numerical parameter whose value is
      less than	the current cursor position, delete from given position	up to
      the cursor.  If preceded by a numerical parameter	whose value is
      greater than the current cursor position,	delete from cursor up to
      given position.

  ^L  Redisplay	the current line.

  ^M  Execute the line.

  ^N  Move to the next line in the history list.

  ^P  Move to the previous line	in the history list.

  ^R<char>
      Search back in the current line for the specified	character.

  ^T  Interchange the two characters immediately preceding the cursor.

  ^U  Repeat the next character	four times.

  ^W  Delete the entire	line.

  ^Y  Insert immediately before	the cursor any text cut	with ^K.

  ^Z  Try to complete a	file or	symbol name.

  Escape
      Try to complete a	file or	symbol name.

  Down Arrow
      Move to the next line in the history list.

  Up Arrow
      Move to the previous line	in the history list.

  Left Arrow
      Move the cursor back one character.

  Right	Arrow
      Move the cursor ahead one	character.

				     Note

       The notation ^ represents the CTRL key. For example, ^A indicates that
       the CTRL	and A keys should be pressed simultaneously.

RESTRICTIONS

  The printf debugger command does not support the %s conversion specifica-
  tion.

ENVIRONMENT VARIABLES

  DBX_MODULE_PATH
      Specifies	the directory path where dbx should search for shared
      libraries	(or loadable kernel modules). This environment variable	is
      useful if, for example, you are debugging	a core dump (or	a kernel
      crash dump) and the version of a shared library (or module) that was
      running when the dump occurred has been moved to a different location.
      Setting this environment variable	automatically sets the $module_path
      dbx variable to the specified path.  If dbx cannot find a	file in	the
      specified	directory, it looks in the directory where that	file was ori-
      ginally, as recorded in the dump.	See also the -module_path option. For
      information on kernel debugging see the Kernel Debugging manual.

  DBX_MODULE_VERBOSE
      When set to any value, causes dbx	to print the path of shared libraries
      (or loadable kernel modules, if debugging	a kernel) as they are being
      loaded. By default, dbx does not print the path. Setting this environ-
      ment variable to any value automatically sets the	$module_verbose	dbx
      variable to the value 1.	See  also the -module_verbose option. For
      information on kernel debugging, see the Kernel Debugging	manual.

FILES

  a.out
      Object file

  core
      Core dump	file

  .dbxinit
      Initialization file

SEE ALSO

  Commands: as(1), cc(1), coredump(1), ctags(1), pixie(5), vi(1)

  Routines: printf(3), signal(4), kdbx(8)

  Kernel Debugging

  Programmer's Guide

  Guide	to the POSIX Threads Library