Man Page dbx.1




NAME

     dbx - source-level debugging tool


SYNOPSIS

     dbx [ -B ] [ -c  cmd ] [ -C ] [ -d ] [ -e ] [ -f ] [ -h ]  [
     -Idir  ] [ -k ] [ -q ] [ -r ] [ -R ] [ -s startup ] [ -S ] [
     -V ] [ -wcount ] [ -x exec32 ] [ execfile [ .class | .jar  ]
     [ corefile | process-id ] ] [ arguments ]


DESCRIPTION

     dbx is a utility for source-level debugging and execution of
     programs written in C++, ANSI C, Fortran 77, Fortran 95, and
     Java programming languages.

     execfile is an executable file, produced by a  Sun  compiler
     with  the  -g option which includes debugging symbols in the
     execfile or its associated object files. For Java  code,  it
     can be a .class or .jar file.  The symbol table contains the
     names of all the source files used to  create  the  execfile
     (all  of  which  may be browsed), as well as a wide range of
     debugging information.  Debugging  support  is  limited  for
     parts of a program not compiled with the -g option.

     Initially, symbol table information is stored  piecemeal  in
     each  of  the object files the compiler creates. If compila-
     tion does not create an object file, all debugging  informa-
     tion  is  stored in the execfile. Distributing the debugging
     information in the object files allows dbx to read and  load
     debugging  information  as  needed, a feature known as Auto-
     Read. If you need to move object files from  their  original
     location, make sure that dbx knows where to find them.  (See
     the pathmap command.)  If it is not feasible to keep program
     .o  files  around,  you  can  disable Auto-Read by compiling
     using the -xs option, which instructs the compiler  to  have
     the  linker  place  all debugging information in the program
     executable.

     If, when starting dbx , no execfile is  specified,  use  the
     debug command to specify a program to be debugged.

     If you know a process-id but not the execfile, you  can  use
     the - (dash) as the execfile and enter the process-id option
     to attach the process to dbx.

     If a corefile argument is specified,  you  can  use  dbx  to
     examine the state of the program when the core file was pro-
     duced.

     You can specify arguments to be passed to the  program  only
     if  you  specify the -r option.  For a Java program, specify
     only arguments to be passed to the program, not arguments to
     be passed to the JVM[tm] software.
     During startup, dbx searches for .dbxrc first in the instal-
     lation directory.  If .dbxrc is not found, dbx then searches
     for ./.dbxrc (ksh mode).  If  ./.dbxrc  is  not  found,  dbx
     prints  a  warning  message  and  searches for ~/.dbxrc (dbx
     mode).

     Runtime Checking (RTC) is a fully integrated feature of  dbx
     using its full capabilities for setting breakpoints and exa-
     mining variables. With RTC, you can detect runtime errors in
     an  application  at any stage. Additionally, you can monitor
     memory usage.

     The -g flag provides source line number correlation  in  the
     error  messages.   RTC  can check programs compiled with the
     optimization -O flag. You do not have to recompile,  relink,
     or modify the makefile to use RTC.

     For proper operation, RTC requires dynamic linking with libc
      and use of the standard libc functions malloc/free/realloc.

     To use RTC, issue a check  type-of-checking  command  within
     dbx  before running the program. It is also recommended that
     you start dbx with the -C option for early  loading  of  the
     RTC  library.  Alternatively, RTC can be used in Batch mode.
     See bcheck (1). Access checking is  supported  only  on  the
     SPARC hardware architecture.


AVAILABILITY

     Sun Studio 11 dbx is available on the following platforms:

     o Solaris[tm] Operating System, version  9  and  version  10
     1/06

     o Linux operating system:
          SuSE Linux Enterprise Server 9 with Service Pack 3

          RedHat Enterprise Linux 4


OPTIONS

     B           Suppress all messages; return with exit code  of
                 program being debugged.

     -c cmd      Execute cmd after loading the program  and  just
                 before  prompting  for  input. For more than one
                 cmd, use quotes around the string  of  commands,
                 separating  them  with a semi-colon. If the com-
                 mands include a $ (dollar sign), the quotes will
                 not work.

     -C          Causes early loading of the RTC  library.  (This
                 does  not  turn  on  checking)  If  not  used on
                 startup, then the RTC library is loaded  on  the
                 next run, after a check command.

     -d          Delete startup after processing it.

     -e          Echo input commands.

     -f          Force loading of core file, even if it does  not
                 match.

     -h          Print help before prompting for input.

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

     -k          Debug a program that sets the keyboard into  up-
                 down  translation  mode.  Necessary if a program
                 uses up-down decoding.

     -q          Quiet mode, or silence echoing  of  two  loading
                 messages:  "Reading  symbol  table  for..."  and
                 "Attached to ...".

     -r          Run execfile immediately. Parameters follow  the
                 execfile  name  (including  redirection). If the
                 program terminates successfully, dbx exits. Oth-
                 erwise,  if a fault occurs, dbx reports the rea-
                 son and waits for a response.

     -R          Print the README file.

     -sstartup   Read  initialization  commands  from  the   file
                 startup script instead of from .dbxrc.

     -S          Suppress reading of site-specific .dbxrc.

     -V          Print the version of dbx being used.

     -w          Count - skip the top N frames in the where  com-
                 mand.

     -xexec32    Run the 32-bit dbx binary instead of the  64-bit
                 dbx  binary that runs by default on systems run-
                 ning a 64-bit OS.


USAGE

     The basic commands to know are:

     run         to run the program being debugged

     where       to obtain a stack trace with line numbers

     print       to display variables

     stop        to set breakpoints


  Scope Rules
     dbx resolves scope conflicts based  on  the  values  of  the
     current file and function. These values are updated as files
     and functions are entered and exited during  execution.  You
     can also change them explicitly using the file and func com-
     mands. When the current function  is  changed,  the  current
     file is updated along with it, and vice versa.


  Thread Identification
     In some commands the use of id refers to the thread id (tid)
     or light weight process id (lid). These take the form of t@N
     or l@N.

  Handler Identification
     Event handlers are identified with  an  integer  number  hid
     (see status, delete, and handler commands).


COMMANDS

     For a listing of all dbx commands, type help commands at the
     dbx command line.



LIMITATIONS

     The following features of dbx are  not  available  on  Linux
     platforms:

     o Fix and continue

     o Java debugging

     o Core file debugging

     Memory access checking is not available on  Linux  platforms
     or on the Solaris OS x86 Platform Edition..



ENVIRONMENT

     dbx checks the environment variable EDITOR for the  name  of
     the  text  editor to use with the edit command. The environ-
     ment variable TMPDIR (if set) is used to replace /tmp as the
     location  for  temporary  files  needed by dbx.  Several ksh
     environment variables are also used. For information on set-
     ting  dbx  environment  variables, type "help dbxenv" on the
     dbx command line.


FILES

     .dbxrc              local dbx initialization file
     ~/.dbxrc            your dbx initialization file
     libcollector.so     shared library used with  the  collector
                         command
     libdbx_agent.so     shared library used for Java debugging
     librtc.so           shared library used for RTC (check  com-
                         mand)
     libdbxadb.so        shared library used with the adb command
     libdbxFintr.so      shared library used for Fortran  intrin-
                         sic function calls
     debugging.so        debugging aid  for  dbx  engineers  when
                         tracking dbx problems


SEE ALSO

     bcheck(1),  csh(1),  dbxrc(4),  kill(1),  ksh(1),  make(1S),
     rtc_patch_area(1).