unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-4.1.3)
Page:
Section:
Apropos / Subsearch:
optional field

DBX(1)                      General Commands Manual                     DBX(1)



NAME
       dbx - source-level debugger

SYNOPSIS
       dbx [ -f fcount ] [ -i ] [ -Idir ] [ -k ] [ -kbd ]
            [ -P fd ] [ -r ] [ -s startup ] [ -sr tstartup ]
            [ objfile [ corefile | process-id ] ]

AVAILABILITY
       This  command  is  available  with  the Debugging software installation
       option.  Refer to for information on how to install optional software.

DESCRIPTION
       dbx is a utility for source-level debugging and execution  of  programs
       written  in  C, or other supported languages such as Pascal and FORTRAN
       77.  dbx accepts the same commands as dbxtool(1), but uses  a  standard
       terminal (tty) interface.

       objfile is an object file, produced by cc(1V) or another compiler, with
       the -g option to include a symbol table.  This  symbol  table  contains
       the  names  of  all the source files used to create it, and these files
       are available for perusal while using the debugger.

       If no objfile is specified, you can use dbx's debug command to  specify
       the program to debug.

       If  there  is a file named core in the current directory, or a corefile
       argument is specified, you can use dbx to examine the state of the pro-
       gram when the core file was produced.

       dbx  commands  in the file .dbxinit are executed immediately before the
       symbol table is read, if that file exists in the current directory,  or
       in  the user's home directory if .dbxinit does not exist in the current
       directory.

OPTIONS
       -f fcount   Alter the initial estimate of the number functions  in  the
                   program being debugged.  The initial setting is 500.

       -i          Force dbx to act as though the standard input were a termi-
                   nal or terminal emulator.

       -I dir      Add dir to the list of directories in which to search for a
                   source  file.  dbx normally searches the current directory,
                   and the directory where objfile is located.  The  directory
                   search path can be reset with the use command.

       -k          Kernel debugging.

       -kbd        Debug  a program that sets the keyboard into up-down trans-
                   lation mode.  This flag is necessary if a program uses  up-
                   down decoding.

       -P fd       Create  a pipeline to a dbxtool(1) process.  fd is the file
                   descriptor through which to pipe output  to  the  front-end
                   process.   This  option  is  passed automatically to dbx by
                   dbxtool.

       -r          Execute objfile immediately.  Parameters follow the  object
                   file  name  (redirection is handled properly).  If the pro-
                   gram terminates successfully, dbx  exits.   Otherwise,  dbx
                   reports   the  reason  for  termination  and  waits  for  a
                   response.  dbx reads from the terminal (/dev/tty)  when  -r
                   is specified and standard input is a file or pipe.

       -s startup  Read initialization commands from the file named startup.

       -sr tstartup
                   Read  initialization commands from the temporary file named
                   startup, and then remove that file.

USAGE
       Refer to dbx in the manual.

       The most useful basic commands to know about are run, to run  the  pro-
       gram  being debugged, where, to obtain a stack trace with line numbers,
       print, to display variables, and stop, to set breakpoints.

   Filenames
       Filenames in dbx may include shell metacharacters.  The shell used  for
       pattern matching is determined by the SHELL environment variable.

   Expressions
       dbx  expressions  are  combinations  of variables, constants, procedure
       calls, and operators.  Variables are either variables  in  the  program
       being  debugged  or  special  dbx  variables  whose names begin with $.
       Hexadecimal constants must be preceded by a `0x' and octal constants by
       a `0'.  Character constants must be enclosed in single quotes.  Expres-
       sions cannot involve strings, structures, or arrays, although  elements
       of structures or arrays may be used.

   Operators
       +   -   *   /   div   % Add,  subtract, multiply, divide, integer divi-
                               sion, and remainder, respectively.

                               dbx has two  division  operators.   `/'  always
                               yields  a  floating-point result and div always
                               yields an integral result.

       <&lt;<&lt;   >&gt;>&gt;    &&amp;   |   ~    Left-shift, right-shift, bitwise  AND,  bitwise
                               OR, and bitwise complement.

       &&amp;   *                   Address of operator, and contents of operator.

       <&lt;   >&gt;   <&lt;=   >&gt;=   ==   !=   !
                               Less than, greater than, less than or equal to,
                               greater than or equal to, equal, not equal, and
                               negation.

       &&amp;&&amp;   ||                 Logical AND, and logical OR

       sizeof (cast)           Size of variable or type and type cast.

       .   ->&gt;                  Field reference, and pointed-to-field reference
                               (however, dot works for both in dbx).

       Precedence and associativity of operators are the same as for C; paren-
       theses can be used for grouping.

       If  there  is  no  corefile,  only expressions containing constants are
       available.  Procedure calls require an active child process.

   Scope Rules
       dbx uses the current file and  function  to  resolve  scope  conflicts.
       Their  values are updated as files and functions are entered and exited
       during execution.  You can also change them  explicitly  by  using  the
       file and func commands.  When the current function is changed, the cur-
       rent file is updated along with it, but not vice versa.

   Execution and Tracing Commands
       ^C     Interrupt.  Stop the program being debugged and enter dbx.

       run [ args ] [ <&lt; infile ] [ >&gt;| >&gt;>&gt; outfile ]
              Start executing objfile, reading in any new information from it.
              With  no  args, use the argument list from the previous run com-
              mand.

                     args        Pass args as command-line  arguments  to  the
                                 program.
                     <&lt;|>&gt;|>&gt;>&gt;      Redirect input or output, or append output to
                                 a file.

       rerun [ args ] [ <&lt; infile ] [ >&gt;| >&gt;>&gt; outfile ]
              Like the run command, except that when args  are  omitted,  none
              are passed to the program.

       cont [ at sourceline ] [ sig signal ]
              Continue execution from where it stopped.

                     at sourceline
                                 Start from sourceline
                     sig signal  Continue  as  if signal had occurred.  signal
                                 may be a number or a name as with catch.

       trace [ in function ] [ if condition ]
       trace sourceline [ if condition ]
       trace function [ if condition ]
       trace expression at sourceline [ if condition ]
       trace variable [ in function ] [ if condition ]
              Display tracing information.  If no argument is specified,  each
              source  line  is  displayed before execution.  Tracing is turned
              off when the function or procedure is exited.

                     in function Display tracing information only  while  exe-
                                 cuting the function or procedure function.
                     if condition
                                 Display tracing information only if condition
                                 is true.
                     sourceline  Display the line immediately prior to execut-
                                 ing  it.   Source  line-numbers  from another
                                 file are written as filename:n.
                     function    Display the routine and  source  line  called
                                 from, parameters passed in, and return value.
                     expression at sourceline
                                 Display  the  value  of  expression  whenever
                                 sourceline is reached.
                     variable    Display the name and value whenever  variable
                                 changes.

       stop at sourceline [ if condition ]
       stop in function [ if condition ]
       stop variable [ if condition ]
       stop if condition
              Stop  execution  when  the  sourceline  is  reached, function is
              called, variable is changed, or condition becomes true.

       when in function { command ; [ command ; ] ... }
       when at sourceline { command ; [ command ; ] ... }
       when condition { command ; [ command ; ] ... }
              Execute the dbx command(s) when function is  called,  sourceline
              is reached, or condition is true.

       status [ >&gt; filename ]
              Display  active  trace,  stop  and when commands, and associated
              command numbers.

       delete all
       delete cmd-no [ , cmd-no ] ...
              Remove all traces, stops and whens, or  those  corresponding  to
              each dbx cmd-no (as displayed by status).

       clear [ sourceline]
              Clear  all  breakpoints  at  the  current  stopping point, or at
              sourceline.

       catch [ signal [ , signal ] ... ]
              Display all signals currently  being  caught,  or  catch  signal
              before  it  is sent to the program being debugged.  A signal can
              be specified either by name (with the  SIG  prefix  omitted,  as
              with  kill(1))  or  number.   Initially  all  signals are caught
              except SIGHUP, SIGEMT, SIGFPE, SIGKILL, SIGALRM,  SIGTSTP,  SIG-
              CONT, SIGCHLD, and SIGWINCH.

       ignore [ signal [ , signal ]  ... ]
              Display  all  signals  currently being ignored, or stop catching
              signal, which may be specified by name or number as with catch.

       step [n]
              Execute the next n source lines.  If omitted, n is taken  to  be
              1.  Steps into functions.

       next [n]
              Execute  the  next n source lines.  If omitted, n is taken to be
              1.  next steps past functions.

   Naming, Printing and Displaying Data
       Variables from another function or procedure  with the same name as one
       in the current block must be qualified as follows:

              [`sourcefile`]function`variable

       For  Pascal  variables there may be more than one function or procedure
       name, each separated by a backquote.

       print expression [ , expression ] ...
              Print the value of each expression, which may  involve  function
              calls.   Program  execution  halts when a breakpoint is reached,
              and dbx resumes.

       display [ expression [ , expression ] ... ]
              Print a list of the expressions currently  being  displayed,  or
              display the value of each expression whenever execution stops.

       undisplay [ expression [ , expression ] ... ]
              Stop  displaying the value of each expression whenever execution
              stops.  If expression is a constant, it refers to a display-num-
              ber as shown by the display command with no arguments.

       whatis identifier
       whatis type
              Print  the  declaration  of the given identifier or type.  types
              are useful to print all the members of a  structure,  union,  or
              enumerated type.

       which identifier
              Print the fully-qualified name of the given identifier.

       whereis identifier
              Print  the  fully qualified name of all symbols matching identi-
              fier.

       assign variable = expression
       set variable = expression
              Assign the value of expression to variable.  There  is  no  type
              conversion for operands of differing type.

       set81 fpreg=word1 word2 word3
              Treat  the  concatenation of word1 word2 word3 as a 96-bit, IEEE
              floating-point value and assign it to the MC68881 floating-point
              register fpreg.  (Supported only on Sun-3).

       call function(parameters)
              Execute  the  named function.  Arguments are passed according to
              the rules for the source-language of function.

       where[ n]
              List all, or the top n, active functions on the stack.

       dump [ function ]
              Display the names and values of local variables  and  parameters
              in the current or specified function.

       up [n]
       down [n]
              Move up (towards ``main'') or down the call stack, one or n lev-
              els.

   File Access Commands
       edit [ filename | function ]
              Edit the current source file, or the given filename or the  file
              that contains function.

       file [ filename ]
              Print the name of the current source file, or change the current
              source file to filename.

       func [ function| program | objfile ]
              Print the name of the current function, or change to  the  given
              function, program, or objfile.  Also changes the current scope.

       list [ startline [ , endline ] ]
       list function
              List  the  next  ten  lines  from current source file, list from
              startline through endline, or and list from five lines above, to
              five lines below the first line of function.

       use [ directory-list ]
              Print  or  set  the  list  of directories in which to search for
              source files.

       cd [ directory ]
              Change the current working directory for dbx to directory (or to
              the value of the HOME environment variable).

       pwd    Print the current working directory for dbx.

       /reg-exp[/]
       ?reg-exp [?]
              Search the current file for the regular expression reg-exp, from
              the next (previous) line to the end (top).   The  matching  line
              becomes the new current line.

   Miscellaneous Commands
       sh command-line
              Pass  the  command  line  to the shell for execution.  The SHELL
              environment variable determines which shell is used.

       alias new-command-name character-sequence
              Respond  to  new-command-name  as  though  it  were   character-
              sequence.   Special  characters  occurring in character-sequence
              must be enclosed in quotation marks.  Alias substitution as with
              the C shell (csh(1)) also occurs.

       help [ command ]
              Display  a  synopsis  of  dbx commands, or print a short message
              explaining command.

       make   Invoke make(1) with the name of the  program  as  its  argument.
              Any arguments set using dbxenv makeargs are also passed as argu-
              ments.

       setenv name string
              Set environment variable name to string.

       source filename
              Read and execute dbx commands from filename.   Useful  when  the
              filename  has been created by redirecting an earlier status com-
              mand.

       quit   Exit dbx.

       dbxenv
       dbxenv case   sensitive | insensitive
       dbxenv fpaasm   on | off
       dbxenv fpabase   a[0-7] | off
       dbxenv makeargs string
       dbxenv  stringlen num
       dbxenv  speed seconds
              Display dbx attributes or set the named attribute:

                     case      Controls whether upper- and lower-case  charac-
                               ters  are  treated  as  different  values.  The
                               default is sensitive.
                     fpaasm    Controls  FPA  instruction  disassembly.    The
                               default is on.  (Supported only on Sun-3).
                     fpabase   Sets the base register for FPA instruction dis-
                               assembly.  The default is off.  (Supported only
                               on Sun-3 systems).
                     makeargs  Sets arguments to pass to make.  The default is
                               CC=cc -g.
                     speed     Set the interval between execution during trac-
                               ing.  The default is 0.5 seconds.
                     stringlen Controls   the  maximum  number  of  characters
                               printed for a ``char *'' variable in a  C  pro-
                               gram.  The default is 512.

       debug [ -k ] [ objfile [ corefile | pid ] ]
              With  no arguments, print the name of the current program.  With
              arguments, stop debugging the current program and  begin  debug-
              ging  objfile  having  either corefile or the current process ID
              pid.  The -k option indicates kernel debugging.

       kill   Stop debugging of the current program, but  be  ready  to  debug
              another.

       detach Detach  the  current  program  (process)  from dbx.  dbx will be
              unable to access or modify its state.

       modules
       modules select [ all| objfile...  ]
       modules append objfile [ objfile...  ]
              The modules command displays or sets the current modules  selec-
              tion  list.   If the modules selection list is set, the debugger
              reads debugging information only for object files in this  list.
              Debugging information for object files not in the modules selec-
              tion list is ignored.

              modules with no arguments displays the set of object  files  for
              which source level debugging information is currently available,
              including the path names of any associated source files.  If the
              debugger  cannot access a source file for which it has debugging
              information, it displays the source file name  with  a  trailing
              `?'   (question mark) character.  Source file path names reflect
              the current search path as set by the  use  command  or  the  -I
              option.

              modules select displays the current modules selection list if no
              objfile is given.  Otherwise, modules select  sets  the  modules
              selection  list  to the specified object files.  To get complete
              debugging information, the debugger  may  need  to  read  object
              files  not in the modules selection list.  `modules select' dis-
              plays these "implied" file names with  trailing  `*'  (asterisk)
              characters  (see NOTES).  `modules select all' discards the mod-
              ules selection list.

              modules append appends the specified object files to the modules
              selection list.

              If the modules selection list includes an object file not in the
              executable being debugged, the debugger issues a warning.

       proc [ pid ]
              For kernel debugging.  Display which process is mapped into  the
              user area, or map pid to the user area.

   Machine-Level Commands
       tracei [ address ] [ if condition ]
       tracei [ variable ] [at address ] [ if condition ]
              Trace execution of a specific machine-instruction address.

       stopi [ variable ] [ if condition ]
       stopi [at address ] [ if condition ]
              Set a breakpoint at a machine instruction address.

       stepi
       nexti  Single step as in step or next, but do a single machine instruc-
              tion rather than a source line.

       address,address / [ mode ]
       address / [count ] [ mode ]
              Display the contents of memory starting at the  first  (or  cur-
              rent)  address  up  to  the second address, or until count items
              have been displayed.  The initial display mode is X.   The  fol-
              lowing modes are supported:

                     i           the machine instruction
                     d           word in decimal
                     D           longword in decimal
                     o           word in octal
                     O           longword in octal
                     x           word in hexadecimal
                     X           longword in hexadecimal
                     b           byte in octal
                     c           byte as a character
                     s           strings as characters terminated by a null
                     f           single precision real number
                     F           double-precision real number
                     E           extended-precision real number (not supported
                                 on Sun-4)

              An address can be specified as an item from the following  list,
              as  an  expression  made up of other addresses and the operators
              `+', `-', `*', and indirection (unary `*'), or as  an  arbitrary
              expression enclosed in parentheses.

                     &&amp;name       symbolic address
                     integer     numeric address

       address = [ mode ]
              Display the value of the address.

   Machine Registers
       The  machine  registers for the current machine type are represented as
       special dbx variables.  They can be used in expressions  as  any  other
       dbx variable can.  The registers and their variable names are:

   Sun-2 and Sun-3 Registers
              $d[0-7]     data registers
              $a[0-7]     address registers
              $fp         frame pointer, equivalent to register a6
              $sp         stack pointer, equivalent to register a7
              $pc         program counter
              $ps         program status

   Sun-3-Only Registers
              $fp[0-7]    MC68881 data registers
              $fpc        MC68881 control register
              $fps        MC68881 status register
              $fpi        MC68881 instruction address register
              $fpf        MC68881 flags register (unused, idle, busy)
              $fpa[0-31]  double-precision interpretation of FPA registers.
              $sfpa[0-31] single-precision interpretation of FPA registers.

   Sun-4 Registers
              $g[0-7]     global registers
              $o[0-7]     ``out'' registers
              $i[0-7]     ``in'' registers
              $l[0-7]     ``local'' registers
              $fp         frame pointer, equivalent to register i6
              $sp         stack pointer, equivalent to register o6
              $y          Y register
              $psr        processor state register
              $wim        window invalid mask register
              $tbr        trap base register
              $pc         program counter
              $npc        next program counter
              $f[0-31]    FPU ``f'' registers
              $fsr        FPU status register
              $fq         FPU queue

   Sun386i Registers
              $ss         stack segment register
              $eflags     flags
              $cs         code segment register
              $eip        instruction pointer
              $eax        general register
              $ecx        general register
              $edx        general register
              $ebx        general register
              $esp        stack pointer
              $ebp        frame pointer
              $esi        source index register
              $edi        destination index register
              $ds         data segment register
              $es         alternate data segment register
              $fs         alternate data segment register
              $gs         alternate data segment register

       Registers for the 80386 lower halves (16 bits) are:

              $ax         general register
              $cx         general register
              $dx         general register
              $bx         general register
              $sp         stack pointer
              $bp         frame pointer
              $si         source index register
              $di         destination index register
              $ip         instruction pointer, lower 16 bits
              $flags      flags, lower 16 bits

       The first four Sun386i 16-bit registers can be split into 8-bit parts:

              $al         lower (right) half of register $ax
              $ah         higher (left) half of register $ax
              $cl         lower (right) half of register $cx
              $ch         higher (left) half of register $cx
              $dl         lower (right) half of register $dx
              $dh         higher (left) half of register $dx
              $bl         lower (right) half of register $bx
              $bh         higher (left) half of register $bx
       Registers for the 80387 are:
              $fctrl      control register
              $fstat      status register
              $ftag       tag register
              $fip        instruction pointer offset
              $fcs        code segment selector
              $fopoff     operand pointer offset
              $fopsel     operand pointer selector
              $st0 - $st7 data registers

ENVIRONMENT
       dbx  checks  the  environment  variable EDITOR for the name of the text
       editor to use with the edit command.

FILES
       core                default core file
       .dbxinit            local dbx initialization file
       ~/.dbxinit          user's dbx initialization file

SEE ALSO
       cc(1V), csh(1), dbxtool(1), kill(1), lex(1), make(1), yacc(1)

NOTES
       Because the cc command does not generate or support 8-bit symbol names,
       it  is inappropriate to make dbx 8-bit clean.  See cc(1V) for an expla-
       nation about why cc is not 8-bit clean.

       To save space, the linker eliminates debugging information  redundantly
       defined  in multiple include files.  If the linker excluded some of the
       symbols for an object file in the modules selection list, the  debugger
       must  read debugging information from the object files where these sym-
       bols were first defined.  If these "implied" modules  are  not  in  the
       modules  selection  list,  `modules  select'  displays their names with
       trailing `*' (asterisk) characters.

BUGS
       dbx does not correctly handle C variables that are  local  to  compound
       statements.   When  printing  these  variables it often gives incorrect
       results.

       dbx does not handle FORTRAN entry points well -- it treats them  as  if
       they were independent routines.

       dbx  does  not handle assigning to FORTRAN complex types correctly (see
       the assign/set command).

       Unlike C, dbx does not recognize an  array  or  function  name  as  the
       address  of the array or function.  In dbx, an array name signifies the
       entire array, and a function name signifies a call to the function with
       no  arguments.  To get the address of an array, take the address of its
       first element.  To get the address of a function, take the  address  of
       its name.

       Casts do not work with FORTRAN 77 or Pascal.

       Executable  code incorporated into a source file using an #include pre-
       processor directive confuses dbx.

       dbx is confused by the output of program generators such as yacc(1) and
       lex(1).

       A  step  command issued at a procedure call will not work properly when
       debugging information is available for the function  being  called  and
       that function is in a shared library.



                                6 December 1989                         DBX(1)