dbx(1)								       dbx(1)



NAME

  dbx - source level debugger

SYNOPSIS

  dbx [-I dir] [-c file] [-k] [-i] [-r] [-pixie] [-pid xxx] [object [core]]

DESCRIPTION

  The dbx command invokes a source-level debugger.  You can use dbx with code
  produced by the cc and as compilers and with machine code.  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.

  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 fol-
  lows:

       (dbx)

  To leave dbx issue the quit command.

  Arguments

  On the command line, the object argument names 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 name of all the source files
  translated by the compiler to create the object file.	 This information
  allows you to look at all of the source code that went into creating an
  object file during your debugging session.  (The extended symbol table also
  contains other information.)

  If your object file does not contain the extended symbol table information,
  use the commands described in the Debugging at the Machine Code Level sec-
  tion to debug your program.

  If you omit the object argument, 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.

  The core argument names a core dump file.  You can examine the core dump
  file to determine the state of the program when it failed.



  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 infor-
  mation 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 (->)
  unnecessary (although it is supported).

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

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

  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.	 To enable command-line editing, you must enter the following command
  from the C shell (before you invoke dbx):

       % setenv LINEEDIT

  The following commands are used in dbx command line editing:

  ^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
	  Delete all characters until the cursor is on the specified
	  character.

  ^L	  Redisplay the current line.

  ^M	  Execute the line.

  ^N	  Move ahead one line.	(This line comes from the history list.)

  ^P	  Move back one line.  (This line comes from the history list.)

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

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

FLAGS

  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 mul-
      tiple -I options.

  -k  Maps memory addresses.  This option is useful for kernel debugging.
      (Refer to kdbx(8) for information on kernel debugging.)

  -pixie
      Reads in output from the pixie code profiler utility.  For this option
      to work, you must have executable pixie output and the nonpixie execut-
      able file in the same directory.	The pixie output must be named
      filename.pixie, where filename is the name of the executable file.

  -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 with the kdebug kernel debugger.	(Refer to kdebug(8) for
      information on breakpoint kernel debugging.)

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

  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
      commands 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 Debugger Variables.	 (Use the assign command to
      change the value of variables in your program.  See the section Prepar-
      ing 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 pro-
      cedure 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 instruc-
	  tion.

      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, speci-
  fying what signals your program should recognize or ignore, and setting
  breakpoints.	The following commands allow you to perform these tasks:

  addobj lib_path
      Loads shared libraries.  The lib_path argument specifies the absolute
      or relative pathname of the shared library.  dbx reads in the shared
      library's symbol table.

      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.

  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
      execution.  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 resumes execution in the
      named procedure or function.

      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,...] [file2]

  rerun [arg1, arg2,...] [&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,...] [file2]

  run [arg1,arg2,...] [&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> 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: -->

  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
  (&).	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 initial 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 speci-
      fies 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.

  $casesense
      When set to a nonzero value, specifies that uppercase and lowercase
      letters be treated as different characters during a search.  When set
      to zero, dbx ignores the case of letters.	 The default is zero.

  $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
      volatile, you may want to set this variable to zero.  To debug the
      operating 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.

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

  $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 OSF/1 systems.

  stopall_on_step
      Specifies whether dbx should run all threads of a multithreaded appli-
      cation (1) or only the thread being stepped (0)  The default is zero.

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

RESTRICTIONS

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

FILES

  a.out	       Object file

  core	       Core dump file

  .dbxinit     Initialization file

RELATED INFORMATION

  COMMANDS: as(1), cc(1), ctags(1), pixie(1), printf(3), vi(1), kdbx(8)

  FILES: signal(3)

  Programmer's Guide.