dbx man page on DigitalUNIX

Printed from http://www.polarhome.com/service/man/?qf=dbx&af=0&tf=2&of=DigitalUNIX

dbx(1)									dbx(1)

NAME
       dbx - source level debugger

SYNOPSIS
       dbx   [-I  dir]	[-c file] [-k] [-i] [-r] [-pid xxx] [objectfile [core‐
       file]]

OPTIONS
       The dbx debugger accepts the following options: Selects a command  file
       other  than  Invokes  dbx  in interactive mode.	This option causes the
       debugger to not treat source lines beginning with number signs  (#)  as
       comments.   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 multiple -I options.  Maps memory addresses.  This  option  is
       useful  for  kernel debugging. For information on kernel debugging, see
       the Kernel Debugging manual.  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	 loca‐
       tion.  Using  this option automatically sets the $module_path dbx vari‐
       able 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	 vari‐
       able.  For  information	on  kernel debugging, see the Kernel Debugging
       manual.	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.  Executes the object file
       immediately.  If program execution terminates with an error,  dbx  dis‐
       plays  the message that describes the error. You can then either invoke
       the debugger or let the program continue	 exiting.   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.	  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).)
       Outputs file and line number information in a  format  compatible  with
       the  emacs  function  gdb.  Attaches dbx to a currently running process
       specified by process id xxx.

OPERANDS
       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 information 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 con‐
	      tain  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.  Specifies a core dump	 file,	created	 if  a
	      program  failed  during  execution 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  com‐
	      mand  line, dbx identifies where the program failed or the snap‐
	      shot 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 Program‐
	      mer'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 separat‐
       ing them with a semicolon (;).

       You  can repeat dbx commands by pressing carriage return. Pressing car‐
       riage 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: Executes a com‐
       mand 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.  With no argument, displays a list of  top‐
       ics  for	 which help information is available. If you name a topic, the
       debugger displays help information on that topic.  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  Exit  dbx.   Predefined
	      alias for quit command: q

   Controlling dbx
       Use  the	 following commands to control the operation of the dbx debug‐
       ger.  Lists all existing aliases or defines an alias. If you  omit  all
       arguments  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 command.	 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
	      substitutes 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  com‐
	      mand:

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

	      Once  you	 issue this command, dbx interprets the following com‐
	      mands 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  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 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.	  Replays  commands  that  were saved with the
	      record input command in a text  file.  If	 you  omit  file,  the
	      debugger	reads  commands	 from the temporary file it creates by
	      default when you issue the record input command.

	      Predefined alias for  playback  input  command:  pi  or  source.
	      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  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 Records all dbx
	      output.  If you omit file, the debugger creates a temporary 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 Executes the  dbx
	      commands	from the specified file.  This command is an alias for
	      the playback input command.  Lists current  breakpoints,	record
	      events, and trace events.

	      Predefined  alias	 for status command: j 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 hexadecimal format.  When set to zero, this vari‐
	      able 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 variables, see PREDEFINED DBX VARIABLES.  (Use
	      the assign command to change the value of variables in your pro‐
	      gram. See the section Preparing for Program Execution for infor‐
	      mation on the assign command.)  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	 vari‐
	      able, specify a null string.  The following example shows how to
	      reset the EDITOR environment variable:

	      (dbx) setenv EDITOR "" 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.	  Returns  the
	      value  of	 tagname, where tagname is a tag that marks a function
	      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
	      following command is valid:

	      (dbx) call tagvalue(getline) ()

	      This command causes execution to begin at the  location  associ‐
	      ated 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 resolving references to tags.  Removes the speci‐
	      fied alias.  Removes the setting of a specified  debugger	 vari‐
	      able.

   Examining Source Code
       The  following commands allow you to examine your source files during a
       debugging session: Searches forward or backward in the source code  for
       the  regular  expression.   Invokes  an	editor	on file or the current
       source file if none is specified.  By default, dbx invokes the vi  edi‐
       tor.   You  can	override  the  default setting by modifying the EDITOR
       environment variable.  Changes the current file to  file,  or,  if  you
       omit file, displays the name of the current file.

	      Predefined  alias for file command: e Changes the current proce‐
	      dure 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 Lists the lines in the cur‐
	      rent 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
	      continues 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  dis‐
	      plays 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: The next 10 lines of source
	      code.   The  next	 10  machine  instructions  after  the current
	      machine instruction.  The previous 10 lines of source code.  The
	      five  lines  before  and	after  the current line.  The 10 lines
	      before and after the current line.  The  five  machine  instruc‐
	      tions before and after the current one.  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
	      information.   The debugger uses the tag file named in the $tag‐
	      file debugger variable to resolve references to tags.   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  con‐
	      sisting  of the complete source path used when the file was com‐
	      piled 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 Displays the type declaration  for
	      variable.	 (If  variable	is  a dbx keyword, it must be enclosed
	      within parentheses.)  Displays the fully qualified name of  each
	      occurrence of variable. The order in which the debugger displays
	      the qualified names is not meaningful.  (If variable  is	a  dbx
	      keyword,	it must be enclosed within parentheses.)  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
       perform setup tasks, such as changing the value of debugger  variables,
       specifying  what	 signals  your program should recognize or ignore, and
       setting breakpoints. The following commands allow you to perform	 these
       tasks: 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 spec‐
	      ify  only the library file name (file), dbx first looks for that
	      file in the directory specified 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 mod‐
	      ules. For complete information on kernel debugging, see the Ker‐
	      nel Debugging  manual.   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 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 sig‐
	      nals  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.
	      Lists all signals that dbx ignores.  If you  specify  a  signal,
	      this command 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.   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 Stops execution when the  specified  variable  changes
	      value,  the specified source line is reached, the specified pro‐
	      cedure 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	proce‐
	      dure,  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:	Sets a breakpoint at a
	      specified line.  Stops in a specified procedure.	Displays trac‐
	      ing  information during program execution.  The dbx debugger as‐
	      sociates 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  rou‐
	      tine.   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
	      information  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  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 key‐
	      word, it must be enclosed within parentheses.)

   Initiating Program Execution
       The following commands allow you to control program execution: Executes
       the  object code associated with the named procedure or function.  This
       command passes the specified parameters to the procedure or function.

	      The print and call commands treat values returned by called pro‐
	      cedures  differently:  the  print	 command displays them and the
	      call command  does  not.	 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 spec‐
	      ify signal, the process continues as though it received the sig‐
	      nal.

	      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 Branches to	the  specified
	      source  line. Execution continues from that point when you issue
	      a cont command.

	      Predefined alias for goto command: g 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 Reruns the  program,	 using
	      the  same arguments that were specified with the run command. If
	      you specify new arguments, rerun uses those arguments.

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

	      Predefined  alias for rerun command: r Runs the program, passing
	      it the specified arguments. Arguments containing 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.  Executes until a return to procedure is
	      executed or until the current procedure or function  returns  if
	      you  omit	 procedure.   Executes one source line.	 If the source
	      line contains a call to a procedure or function, the  step  com‐
	      mand stops at the first line of the procedure or function.  (The
	      debugger does not stop at the first line of a procedure or func‐
	      tion if you compiled your program without using the -g option.)

	      If you specify integer, the debugger performs the specified num‐
	      ber of step commands.

	      Predefined alias for step command: s

   Examining Program State
       Use the following commands to determine the state of your program: Dis‐
       plays  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.  Moves the current function
       down  in	 the  stack (based on the number of activation levels that you
       specify). The default is one level.  Moves the current function	up  in
       the  stack (based on the number of activation levels that you specify).
       The default is one level.  Displays the value of the specified  expres‐
       sion.   (If a specified expression contains the name of a variable that
       is also a dbx keyword, the variable name must be enclosed within paren‐
       theses.)

	      Predefined  alias	 for print command: p 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 val‐
	      ues: The specified expression or variable in decimal.  The spec‐
	      ified expression or variable in octal.  The specified expression
	      or variable in hexadecimal.  Displays all register values.

	      Predefined alias for printregs command: pr 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 filesys‐
       tem must be mounted. The following commands are available to attach to,
       and  detach  from,  a  running process: 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 process, issue a stop command,
       report the current position, and issue the dbx> prompt.	Use this  com‐
       mand  to	 detach	 from a running process, where the optional xxx is the
       proc id of the process you want to detach from.	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.	 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 informa‐
       tion.

       You can specify symbolic addresses by preceding the name with an amper‐
       sand (&).  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:
       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 dis‐
       plays 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: Displays  a  byte
       in  octal.  Displays a byte as a character.  Displays a 16-bit value in
       decimal.	 Displays a 32-bit value in decimal.  Displays a 64-bit	 value
       in  decimal.  Displays a single precision real number.  Displays a dou‐
       ble precision real number.  Displays  machine  instructions.   Displays
       data  in	 typed	format.	 Displays a 16-bit value in octal.  Displays a
       32-bit value in octal.  Displays a 64-bit value in octal.   Displays  a
       string  of  characters that ends in a null.  Displays a 16-bit value in
       hexadecimal.  Displays a	 32-bit	 value	in  hexadecimal.   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
	      specified in the previous command.  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 debug‐
	      ger displays the address of the masked  value.   Otherwise,  the
	      debugger	increments address and continues to search.  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
	      continues 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.   Executes  up  to the next
	      machine instruction. The nexti command does not step into proce‐
	      dures  or	 functions; execution stops at the machine instruction
	      that follows the call.

	      If you specify an integer, the debugger performs	integer	 nexti
	      instructions.

	      Predefined  alias	 for  nexti command: ni Executes the specified
	      number of machine instructions.  If one of the machine  instruc‐
	      tions  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 Stops when the specified
	      variable changes value, the specified address  is	 reached,  the
	      specified condition is true, or the specified procedure or func‐
	      tion 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	speci‐
	      fied  address  changes  value and condition is true.  Traces the
	      value of variable or the execution of a particular address.  (If
	      variable	is a dbx keyword, it must be enclosed within parenthe‐
	      ses.)

	      When you trace the value of a variable, you can use at  address,
	      in  procedure, 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.  Executes the specified dbx machine  com‐
	      mand 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 execute 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
       operations.   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 com‐
       mands.  The following list describes the	 debugger  variables  you  can
       control: 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.  When
       set to a positive nonzero value, indicates that dbx is in  asynchronous
       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.  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.   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 con‐
       tains 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.
       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.	 When set to a nonzero value, causes the debugger  to  display
       characters  in hexadecimal format.  When set to a nonzero value, causes
       the debugger to interpret input constants as  hexadecimal.   When  set,
       this  variable  overrides  the  $octin variable.	 When set to a nonzero
       value, changes the default output constants to hexadecimal.  When  set,
       this  variable  overrides the $octints variable.	 When set to a nonzero
       value, causes the debugger to display all strings in  hexadecimal  for‐
       mat.  When set to zero, causes the debugger to display strings in char‐
       acter format.  Stores the current history line.	 Determines  how  many
       lines the debugger stores in its history list. The default is 20 lines.
       Specifies how many lines the list command displays. The default	is  10
       lines.  Specifies the name of the procedure or function that dbx begins
       when running the process. The debugger can begin a process at any  pro‐
       cedure  or  function.   By  default, the debugger begins a process at a
       procedure named main.  Specifies how many characters of	a  string  dbx
       displays	 for  pointers	to  strings.   The  default is 128 characters.
       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.  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 vari‐
       able. For information on kernel debugging,  see	the  Kernel  Debugging
       manual.	 When  set  to a nonzero value, changes the default input con‐
       stants to octal.	 When set, the $hexin variable	overrides  this	 vari‐
       able.   When  set to a nonzero value, causes dbx to display integers in
       octal format.  When set, the $hexints variable overrides this variable.
       Specifies  whether  to  page long information. A nonzero value turns on
       paging; a zero turns it off.  The default is one.  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.  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_rou‐
       tine()).

	      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  $printc‐
	      plusparams  to  1 will enable dbx to print these parameters in a
	      stack trace.  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 dis‐
	      play only the last line or instruction.  The  default  is	 zero.
	      Displays	input  when  used with the playback input command. The
	      default is zero.	When set to a nonzero value, causes the debug‐
	      ger  to  display the contents of registers next to each instruc‐
	      tion it displays. The debugger displays the  registers  used  by
	      the  instruction.	  The  default is zero.	 When set to a nonzero
	      value, causes the debugger to display the contents of  variables
	      in  a  horizontal	 format. The default is zero.  Sets the prompt
	      for dbx.	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.  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.
	      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.  When set to a nonzero value, causes
	      the  debugger  to	 record	 input	while  recording  output.  The
	      default is zero.	Tells dbx the name of the code called  by  the
	      system  to invoke user signal handlers.  This variable is set to
	      sigaction	 on  Tru64  UNIX  systems.    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.  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.  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 stopping.  The default is  1.	 Names
	      the  file	 that  contains tags for the current program.  The tag
	      and tagvalue commands search the named file  to  resolve	refer‐
	      ences  to	 tags.	 For  more information on using tag files, see
	      ctags(1).	 Specifies the number of times dbx can ignore  a  SIG‐
	      TRAP  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 debug‐
       ging.

       You can use command options to modify some steps that dbx performs dur‐
       ing startup. (For information on the available options, see the OPTIONS
       section.) Unless you specify the -r option, dbx prompts you for a  com‐
       mand 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 initial‐
       ization file (if present).  By default, dbx searches for	 the  initial‐
       ization	file  in the current directory.	 If no file exists in the cur‐
       rent 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
       information  on the debugger variables that you can control in the ini‐
       tialization 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 reg‐
       isters by $rN where N is the number of the register.

       The debugger supports symbol names and string literals containing  dis‐
       playable 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  identi‐
       fiers 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 with‐
       out the 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  command.	  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 ending in emacs, before starting dbx.	The debugger treats ^K
       differently depending on whether the mode is enabled by LINEEDIT or  by
       EDITOR  or EDITMODE. In emacs mode, the following editing keys are rec‐
       ognized: Move the cursor to the beginning of the	 command  line.	  Move
       the  cursor  back one character.	 Clear the line.  Delete the character
       at the cursor.  Move the cursor to the end of the line.	Move the  cur‐
       sor  ahead  one	character.  Delete the character immediately preceding
       the cursor.  Execute the line.  (When enabled by LINEEDIT) Delete char‐
       acters  until  the  cursor rests on the next occurrence of char.	 (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	 posi‐
       tion.  Redisplay the current line.  Execute the line.  Move to the next
       line in the history list.  Move to the previous	line  in  the  history
       list.   Search  back  in	 the current line for the specified character.
       Interchange  the	 two  characters  immediately  preceding  the  cursor.
       Repeat  the next character four times.  Delete the entire line.	Insert
       immediately before the cursor any text cut with ^K.  Try to complete  a
       file  or	 symbol name.  Try to complete a file or symbol name.  Move to
       the next line in the history list.  Move to the previous	 line  in  the
       history	list.	Move  the  cursor back one character.  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 specifi‐
       cation.

ENVIRONMENT VARIABLES
       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
       originally, as recorded in the dump. See also the -module_path  option.
       For  information	 on  kernel debugging see the Kernel Debugging manual.
       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
       Object file Core dump file 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

									dbx(1)
[top]

List of man pages available for DigitalUNIX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net