This is the First Edition, 31 March, 2003, of `Debugging with DDD' for
DDD Version 3.3.8.

Copyright (C) 2001 Universität des Saarlandes
Lehrstuhl Softwaretechnik
Postfach 15 11 50
66041 Saarbrücken
GERMANY

Distributed by
Free Software Foundation, Inc.
59 Temple Place - Suite 330
Boston, MA 02111-1307
USA

DDD and this manual are available via the DDD WWW page
(http://www.gnu.org/software/ddd/).

   Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts and no Back-Cover Texts.  A
copy of the license is included in the section entitled "GNU Free
Documentation License".

   Send questions, comments, suggestions, etc. to <ddd@gnu.org>.
Send bug reports to <bug-ddd@gnu.org>.

Debugging with DDD
******************

   DDD is a graphical front-end for GDB and other command-line
debuggers.

   This is the First Edition of `Debugging with DDD', 31 March, 2003,
for DDD Version 3.3.8.

   The first part of this master menu lists the major nodes in this Info
document, including the label and command indices.  The rest of the menu
lists all the lower level nodes in the document.

Summary of DDD
**************

   The purpose of a debugger such as DDD is to allow you to see what is
going on "inside" another program while it executes--or what another
program was doing at the moment it crashed.

   DDD can do four main kinds of things (plus other things in support
of these) to help you catch bugs in the act:

   * Start your program, specifying anything that might affect its
     behavior.

   * Make your program stop on specified conditions.

   * Examine what has happened, when your program has stopped.

   * Change things in your program, so you can experiment with
     correcting the effects of one bug and go on to learn about another.

   Technically speaking, DDD is a front-end to a command-line debugger
(called "inferior debugger", because it lies at the layer beneath DDD).
DDD supports the following inferior debuggers:

   * To debug _executable binaries_, you can use DDD with "GDB", "DBX",
     "Ladebug", or "XDB".

        - "GDB", the GNU debugger, is the recommended inferior debugger
          for DDD.  GDB supports native executables binaries originally
          written in C, C++, Java, Modula-2, Modula-3, Pascal, Chill,
          Ada, and FORTRAN.  (see Using GDB with Different Languages (gdb),
          for information on language support in GDB.)

        - As an alternative to GDB, you can use DDD with the "DBX"
          debugger, as found on several UNIX systems.  Most DBX
          incarnations offer fewer features than GDB, and some of the
          more advanced DBX features may not be supported by DDD.
          However, using DBX may be useful if GDB does not understand
          or fully support the debugging information as generated by
          your compiler.

        - As an alternative to GDB and DBX, you can use DDD with
          "Ladebug", as found on Compaq and DEC systems.  Ladebug
          offers fewer features than GDB, and some of the more advanced
          Ladebug features may not be supported by DDD.  However, using
          Ladebug may be useful if GDB or DBX do not understand or
          fully support the debugging information as generated by your
          compiler.(1)

        - As another alternative to GDB, you can use DDD with the "XDB"
          debugger, as found on HP-UX systems.(2).

   * To debug _Java byte code programs_, you can use DDD with "JDB",
     the Java debugger, as of JDK 1.1 and later.  (DDD has been tested
     with JDK 1.1 and JDK 1.2.)

   * To debug _Python programs_, you can use DDD with "PYDB", a Python
     debugger.

   * To debug _Perl programs_, you can use DDD with the "Perl
     debugger," as of Perl 5.003 and later.

   * To debug _Bash programs_, you need a version Bash that supports
     extended debugging support. To get this enhanced version see
     `http://bashdb.sourceforge.net'. You will need version
     2.05b-debugger-0.32 or later to work with DDD.

   See Choosing an Inferior Debugger, for choosing the appropriate
inferior debugger.  See Sample Session, for getting a first
impression of DDD.

   ---------- Footnotes ----------

   (1) Within DDD (and this manual), Ladebug is considered a DBX
variant.  Hence, everything said for DBX also applies to Ladebug,
unless stated otherwise.

   (2) XDB will no longer be maintained in future DDD releases.  Use a
recent GDB version instead.

About this Manual
=================

   This manual comes in several formats:

   * The _Info_ format is used for browsing on character devices; it
     comes without pictures.  You should have a local copy installed,
     which you can browse via Emacs, the stand-alone `info' program, or
     from DDD via `Help => DDD Reference'.

     The DDD source distribution `ddd-3.3.8.tar.gz' contains this
     manual as pre-formatted info files; you can also download them
     from
     the DDD WWW page (http://www.gnu.org/software/ddd/).

   * The _PostScript_ format is used for printing on paper; it comes
     with pictures as well.

     The DDD source distribution `ddd-3.3.8.tar.gz' contains this
     manual as pre-formatted PostScript file; you can also download it
     from
     the DDD WWW page (http://www.gnu.org/software/ddd/).

   * The _PDF_ format is used for printing on paper as well as for
     online browsing; it comes with pictures as well.

     The DDD source distribution `ddd-3.3.8.tar.gz' contains this
     manual as pre-formatted PDF file; you can also download it from
     the DDD WWW page (http://www.gnu.org/software/ddd/).

   * The _HTML_ format is used for browsing on bitmap devices; it
     includes several pictures.  You can view it using a HTML browser,
     typically from a local copy.

     A pre-formatted HTML version of this manual comes in a separate
     DDD package
     `ddd-3.3.8-html-manual.tar.gz'; you can browse and download it via
     the DDD WWW page (http://www.gnu.org/software/ddd/).

   The manual itself is written in TeXinfo format; its source code
`ddd.texi' is contained in the DDD source distribution
`ddd-3.3.8.tar.gz'.

   The picture sources come in a separate package
`ddd-3.3.8-pics.tar.gz'; you need this package only if you want to
re-create the PostScript, HTML, or PDF versions.

Free software
=============

   DDD is "free"; this means that everyone is free to use it and free
to redistribute it on a free basis.  DDD is not in the public domain;
it is copyrighted and there are restrictions on its distribution, but
these restrictions are designed to permit everything that a good
cooperating citizen would want to do.  What is not allowed is to try to
prevent others from further sharing any version of DDD that they might
get from you.  The precise conditions are found in the GNU General
Public License that comes with DDD; see License, for details.

   The easiest way to get a copy of DDD is from someone else who has
it.  You need not ask for permission to do so, or tell any one else;
just copy it.

Getting DDD
===========

   If you have access to the Internet, you can get the latest version of
DDD from the anonymous FTP server `ftp.gnu.org' in the directory
`/gnu/ddd'.  This should contain the following files:

``ddd-VERSION.tar.gz''
     The DDD source distribution.  This should be all you need.

``ddd-VERSION-html-manual.tar.gz''
     The DDD manual in HTML format.  You need this only if you want to
     install a local copy of the DDD manual in HTML format.

``ddd-VERSION-pics.tar.gz''
     Sources of images included in the DDD manual.  You need this only
     if you want to recreate the DDD manual.

   DDD can also be found at numerous other archive sites around the
world; check the file `ANNOUNCE' in a DDD distribution for the latest
known list.

Contributors to DDD
===================

   Dorothea Lütkehaus and Andreas Zeller were the original authors of
DDD.  Many others have contributed to its development.  The files
`ChangeLog' and `THANKS' in the DDD distribution approximates a
blow-by-blow account.

History of DDD
==============

   The history of DDD is a story of code recycling.  The oldest parts of
DDD were written in 1990, when _Andreas Zeller_ designed VSL, a
box-based visual structure language for visualizing data and program
structures.  The VSL interpreter and the Box library became part of
Andreas' Diploma Thesis, a graphical syntax editor based on the
Programming System Generator PSG.

   In 1992, the VSL and Box libraries were recycled for the NORA
project.  For NORA, an experimental inference-based software
development tool set, Andreas wrote a graph editor (based on VSL and
the Box libraries) and facilities for inter-process knowledge exchange.
Based on these tools, _Dorothea Lütkehaus_ (now _Dorothea Krabiell_)
realized DDD as her Diploma Thesis, 1994.

   The original DDD had no source window; this was added by Dorothea
during the winter of 1994-1995.  In the first quarter of 1995, finally,
Andreas completed DDD by adding command and execution windows,
extensions for DBX and remote debugging as well as configuration
support for several architectures.  Since then, Andreas has further
maintained and extended DDD, based on the comments and suggestions of
several DDD users around the world.  See the comments in the DDD source
for details.

   Major DDD events:

April, 1995
     DDD 0.9: First DDD beta release.

May, 1995
     DDD 1.0: First public DDD release.

December, 1995
     DDD 1.4: Machine-level debugging, glyphs, Emacs integration.

October, 1996
     DDD 2.0: Color displays, XDB support, generic DBX support, command
     tool.

May, 1997
     DDD 2.1: Alias detection, button tips, status displays.

November, 1997
     DDD 2.2: Sessions, display shortcuts.

June, 1998
     DDD 3.0: Icon tool bar, Java support, JDB support.

December, 1998
     DDD 3.1: Data plotting, Perl support, Python support, Undo/Redo.

January, 2000
     DDD 3.2: New manual, Readline support, Ladebug support.

January, 2001
     DDD 3.3: Data themes, JDB 1.2 support, VxWorks support.

November, 2002
     DDD 3.3.2: Bash support.

March, 2003
     DDD 3.3.3: Better Bash support. Compiles using modern tools thanks
     to Daniel Schepler.

A Sample DDD Session
********************

   You can use this manual at your leisure to read all about DDD.
However, a handful of features are enough to get started using the
debugger.  This chapter illustrates those features.

   The sample program `sample.c' (see Sample Program) exhibits the
following bug.  Normally, `sample' should sort and print its arguments
numerically, as in the following example:

     $ ./sample 8 7 5 4 1 3
     1 3 4 5 7 8

   However, with certain arguments, this goes wrong:

     $ ./sample 8000 7000 5000 1000 4000
     1000 1913 4000 5000 7000

   Although the output is sorted and contains the right number of
arguments, some arguments are missing and replaced by bogus numbers;
here, `8000' is missing and replaced by `1913'.(1)

   Let us use DDD to see what is going on.  First, you must compile
`sample.c' for debugging (see Compiling for Debugging), giving the
`-g' flag while compiling:

     $ gcc -g -o sample sample.c

   Now, you can invoke DDD (see Invocation) on the `sample'
executable:

     $ ddd sample

   After a few seconds, DDD comes up.  The "Source Window" contains the
source of your debugged program; use the "Scroll Bar" to scroll through
the file.

   The "Debugger Console" (at the bottom) contains DDD version
information as well as a GDB prompt.(2)

     GNU DDD Version 3.3.8, by Dorothea Lütkehaus and Andreas Zeller.
     Copyright (C) 1995-1999 Technische Universität Braunschweig, Germany.
     Copyright (C) 1999-2001 Universität Passau, Germany.
     Copyright (C) 2001 Universität des Saarlandes, Germany.
     Reading symbols from sample...done.
     (gdb)

   The first thing to do now is to place a "Breakpoint" (see
Breakpoints), making `sample' stop at a location you are interested
in.  Click on the blank space left to the initialization of `a'.  The
"Argument field" `():' now contains the location (`sample.c:31').  Now,
click on `Break' to create a breakpoint at the location in `()'.  You
see a little red stop sign appear in line 31.

   The next thing to do is to actually "execute" the program, such that
you can examine its behavior (see Running).  Select `Program =>
Run' to execute the program; the `Run Program' dialog appears.

   In `Run with Arguments', you can now enter arguments for the
`sample' program.  Enter the arguments resulting in erroneous behavior
here--that is, `8000 7000 5000 1000 4000'.  Click on `Run' to start
execution with the arguments you just entered.

   GDB now starts `sample'.  Execution stops after a few moments as the
breakpoint is reached.  This is reported in the debugger console.

     (gdb) break sample.c:31
     Breakpoint 1 at 0x8048666: file sample.c, line 31.
     (gdb) run 8000 7000 5000 1000 4000
     Starting program: sample 8000 7000 5000 1000 4000

     Breakpoint 1, main (argc=6, argv=0xbffff918) at sample.c:31
     (gdb)

   The current execution line is indicated by a green arrow.

     => a = (int *)malloc((argc - 1) * sizeof(int));

   You can now examine the variable values.  To examine a simple
variable, you can simply move the mouse pointer on its name and leave
it there.  After a second, a small window with the variable value pops
up (see Value Tips).  Try this with `argc' to see its value (`6').
The local variable `a' is not yet initialized; you'll probably see
`0x0' or some other invalid pointer value.

   To execute the current line, click on the `Next' button on the
command tool.  The arrow advances to the following line.  Now, point
again on `a' to see that the value has changed and that `a' has
actually been initialized.

   To examine the individual values of the `a' array, enter `a[0]' in
the argument field (you can clear it beforehand by clicking on `():')
and then click on the `Print' button.  This prints the current value of
`()' in the debugger console (see Printing Values).  In our case,
you'll get

     (gdb) print a[0]
     $1 = 0
     (gdb)

or some other value (note that `a' has only been allocated, but the
contents have not yet been initialized).

   To see all members of `a' at once, you must use a special GDB
operator.  Since `a' has been allocated dynamically, GDB does not know
its size; you must specify it explicitly using the `@' operator (see
Array Slices).  Enter `a[0]@(argc - 1)' in the argument field and
click on the `Print' button.  You get the first `argc - 1' elements of
`a', or

     (gdb) print a[0]@(argc - 1)
     $2 = {0, 0, 0, 0, 0}
     (gdb)

   Rather than using `Print' at each stop to see the current value of
`a', you can also "display" `a', such that its is automatically
displayed.  With `a[0]@(argc - 1)' still being shown in the argument
field, click on `Display'.  The contents of `a' are now shown in a new
window, the "Data Window".  Click on `Rotate' to rotate the array
horizontally.

   Now comes the assignment of `a''s members:

     =>  for (i = 0; i < argc - 1; i++)
             a[i] = atoi(argv[i + 1]);

   You can now click on `Next' and `Next' again to see how the
individual members of `a' are being assigned.  Changed members are
highlighted.

   To resume execution of the loop, use the `Until' button.  This makes
GDB execute the program until a line greater than the current is
reached.  Click on `Until' until you end at the call of `shell_sort' in

     =>  shell_sort(a, argc);

   At this point, `a''s contents should be `8000 7000 5000 1000 4000'.
Click again on `Next' to step over the call to `shell_sort'.  DDD ends
in

     =>  for (i = 0; i < argc - 1; i++)
             printf("%d ", a[i]);

and you see that after `shell_sort' has finished, the contents of `a'
are `1000, 1913, 4000, 5000, 7000'--that is, `shell_sort' has somehow
garbled the contents of `a'.

   To find out what has happened, execute the program once again.  This
time, you do not skip through the initialization, but jump directly into
the `shell_sort' call.  Delete the old breakpoint by selecting it and
clicking on `Clear'.  Then, create a new breakpoint in line 35 before
the call to `shell_sort'.  To execute the program once again, select
`Program => Run Again'.

   Once more, DDD ends up before the call to `shell_sort':
     =>  shell_sort(a, argc);

   This time, you want to examine closer what `shell_sort' is doing.
Click on `Step' to step into the call to `shell_sort'.  This leaves
your program in the first executable line, or

     => int h = 1;

   while the debugger console tells us the function just entered:

     (gdb) step
     shell_sort (a=0x8049878, size=6) at sample.c:9
     (gdb)

   This output that shows the function where `sample' is now suspended
(and its arguments) is called a "stack frame display".  It shows a
summary of the stack.  You can use `Status => Backtrace' to see where
you are in the stack as a whole; selecting a line (or clicking on `Up'
and `Down') will let you move through the stack.  Note how the `a'
display disappears when its frame is left.

   Let us now check whether `shell_sort''s arguments are correct.
After returning to the lowest frame, enter `a[0]@size' in the argument
field and click on `Print':

     (gdb) print a[0] @ size
     $4 = {8000, 7000, 5000, 1000, 4000, 1913}
     (gdb)

   Surprise!  Where does this additional value `1913' come from?  The
answer is simple: The array size as passed in `size' to `shell_sort' is
_too large by one_--`1913' is a bogus value which happens to reside in
memory after `a'.  And this last value is being sorted in as well.

   To see whether this is actually the problem cause, you can now assign
the correct value to `size' (see Assignment).  Select `size' in the
source code and click on `Set'.  A dialog pops up where you can edit
the variable value.

   Change the value of `size' to `5' and click on `OK'.  Then, click on
`Finish' to resume execution of the `shell_sort' function:

     (gdb) set variable size = 5
     (gdb) finish
     Run till exit from #0  shell_sort (a=0x8049878, size=5) at sample.c:9
     0x80486ed in main (argc=6, argv=0xbffff918) at sample.c:35
     (gdb)

   Success!  The `a' display now contains the correct values `1000,
4000, 5000, 7000, 8000'.

   You can verify that these values are actually printed to standard
output by further executing the program.  Click on `Cont' to continue
execution.

     (gdb) cont
     1000 4000 5000 7000 8000

     Program exited normally.
     (gdb)

   The message `Program exited normally.' is from GDB; it indicates
that the `sample' program has finished executing.

   Having found the problem cause, you can now fix the source code.
Click on `Edit' to edit `sample.c', and change the line

     shell_sort(a, argc);

to the correct invocation

     shell_sort(a, argc - 1);

   You can now recompile `sample'

     $ gcc -g -o sample sample.c

and verify (via `Program => Run Again') that `sample' works fine now.

     (gdb) run
     `sample' has changed; re-reading symbols.
     Reading in symbols...done.
     Starting program: sample 8000 7000 5000 1000 4000
     1000 4000 5000 7000 8000

     Program exited normally.
     (gdb)

   All is done; the program works fine now.  You can end this DDD
session with `Program => Exit' or `Ctrl+Q'.

   ---------- Footnotes ----------

   (1) Actual numbers and behavior on your system may vary.

   (2) Re-invoke DDD with `--gdb', if you do not see a `(gdb)' prompt
here (see Choosing an Inferior Debugger)

Sample Program
==============

   Here's the source `sample.c' of the sample program.

     /* sample.c -- Sample C program to be debugged with DDD */

     #include <stdio.h>
     #include <stdlib.h>

     static void shell_sort(int a[], int size)
     {
         int i, j;
         int h = 1;
         do {
             h = h * 3 + 1;
         } while (h <= size);
         do {
             h /= 3;
             for (i = h; i < size; i++)
             {
                 int v = a[i];
                 for (j = i; j >= h && a[j - h] > v; j -= h)
                     a[j] = a[j - h];
                 if (i != j)
                     a[j] = v;
             }
         } while (h != 1);
     }

     int main(int argc, char *argv[])
     {
         int *a;
         int i;

         a = (int *)malloc((argc - 1) * sizeof(int));
         for (i = 0; i < argc - 1; i++)
             a[i] = atoi(argv[i + 1]);

         shell_sort(a, argc);

         for (i = 0; i < argc - 1; i++)
             printf("%d ", a[i]);
         printf("\n");

         free(a);
         return 0;
     }

Getting In and Out of DDD
*************************

This chapter discusses how to start DDD, and how to get out of it.  The
essentials are:

   * Type `ddd' to start DDD (see Invoking).

   * Use `File => Exit' or `Ctrl+Q' to exit (see Quitting).

Invoking DDD
============

   Normally, you can run DDD by invoking the program `ddd'.

   You can also run DDD with a variety of arguments and options, to
specify more of your debugging environment at the outset.

   The most usual way to start DDD is with one argument, specifying an
executable program:

     ddd PROGRAM

If you use GDB, DBX, Ladebug, or XDB as inferior debuggers, you can also
start with both an executable program and a core file specified:

     ddd PROGRAM CORE

   You can, instead, specify a process ID as a second argument, if you
want to debug a running process:

     ddd PROGRAM 1234

would attach DDD to process `1234' (unless you also have a file named
`1234'; DDD does check for a core file first).

   You can further control DDD by invoking it with specific "options".
To get a list of DDD options, invoke DDD as

     ddd --help

   Most important are the options to specify the inferior debugger
(see Choosing an Inferior Debugger), but you can also customize
several aspects of DDD upon invocation (see Options).

   DDD also understands the usual X options such as `-display' or
`-geometry'.  See X Options, for details.

   All arguments and options that are not understood by DDD are passed
to the inferior debugger; see Inferior Debugger Options, for a
survey.  To pass an option to the inferior debugger that conflicts with
an X option, or with a DDD option listed here, use the `--debugger'
option (see Options).

Choosing an Inferior Debugger
-----------------------------

   The most frequently required options are those to choose a specific
inferior debugger.

   Normally, the inferior debugger is determined by the program to
analyze:

   * If the program requires a specific interpreter, such as Java,
     Python, Perl or Bash, then you should use a JDB, PYDB, Perl, or
     Bash inferior debugger.

     Use

          ddd --jdb PROGRAM

          ddd --pydb PROGRAM

          ddd --perl PROGRAM

          ddd --bash PROGRAM
          ddd --interpreter='_path-to-debugger-bash_ --debugger' PROGRAM

     to run DDD with JDB, PYDB, Perl, or Bash as an inferior debugger.

   * If the program is an executable binary, you should use GDB, DBX,
     Ladebug, or XDB.  In general, GDB (or its HP variant, WDB)
     provides the most functionality of these debuggers.

     Use

          ddd --gdb PROGRAM

          ddd --wdb PROGRAM

          ddd --dbx PROGRAM

          ddd --ladebug PROGRAM

          ddd --xdb PROGRAM

     to run DDD with GDB, WDB, DBX, Ladebug, or XDB as inferior
     debugger.

   If you invoke DDD without any of these options, but give a PROGRAM
to analyze, then DDD will automatically determine the inferior debugger:

   * If PROGRAM is a Python program, a Perl script, or a Java class,
     DDD will invoke the appropriate debugger.

   * If PROGRAM is an executable binary, DDD will invoke its default
     debugger for executables (usually GDB).

   See Customizing Debugger Interaction, for more details on
determining the inferior debugger.