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, 15 January, 2004, for DDD Version 3.3.9.

• Summary: Summary of DDD.
• Sample Session: A sample DDD session.
• Invocation: Getting in and out of DDD.
• Windows: The DDD windows, menus, and buttons.
• Navigating: Moving through the source code.
• Stopping: Making your program stop at specific locations.
• Running: Running programs under DDD.
• Examining Data: Examining variable values and data structures.
• Machine-Level Debugging: Examining machine code and registers.
• Changing the Program: Changing source and object code.
• Commands: Entering and editing DDD commands.
• Application Defaults: Resources used in DDD.
• Bugs: How, when, and why to report DDD bugs.
• Configuration Notes: Configuration-specific notes.
• Dirty Tricks: Room for your contributions.
• Extending: Extending DDD.
• FAQ: Frequently Answered Questions.
• License: The DDD license.
• Help and Assistance: Mailing Lists and other resources.
• Documentation License: The license of this document.
• Label Index: All labels shown on the DDD GUI.
• Key Index: Keys used to control DDD.
• Command Index: Commands that can be typed within DDD.
• Resource Index: All resources and environment variables.
• File Index: All programs and files referenced by DDD.
• Concept Index: All concepts as mentioned in this manual.

Copyright © 2004 Universit? des Saarlandes
Lehrstuhl Softwaretechnik
Postfach 15 11 50
66041 Saarbr?ken
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.

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"; See Documentation License, for details.

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

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, 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.¹
  • As another alternative to GDB, you can use DDD with the XDB debugger, as found on HP-UX systems.².
• 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.

• About this Manual: Getting copies in various formats.
• Typographic Conventions: Typographic conventions.
• Free Software: How to copy and redistribute DDD.
• Getting DDD: How to obtain copies of DDD.
• Contributors: Who has done all this?
• History: Old DDD versions.

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.9.tar.gz contains this manual as pre-formatted info files; you can also download them from
  the DDD WWW page.

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

  The DDD source distribution ddd-3.3.9.tar.gz contains this manual as pre-formatted PostScript file; you can also download it from
  the DDD WWW page.

• 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.9.tar.gz contains this manual as pre-formatted PDF file; you can also download it from
  the DDD WWW page.

• 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.9-html-manual.tar.gz; you can browse and download it via
  the DDD WWW page.

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

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

Typographic conventions

<Ctrl+A>

The name for a key on the keyboard (or multiple keys pressed simultaneously)

run

A sequence of characters to be typed on the keyboard.

~/.ddd/init

A file.

Help

A graphical control element, such as a button or menu item.

File => Open Program

A sequence of menu items, starting at the top-level menu bar.

argc - 1

Program code or debugger command.

-g

A command-line option.

$

System prompt.

(gdb)

Debugger prompt.

_

Cursor position.

version

A metasyntactic variable; something that stands for another piece of text.

definition

A definition.

caution

Emphasis.

A warning

Strong emphasis.

DDD

An acronym.

Here's an example. break location is a typed command at the (gdb) prompt; the metasyntactic variable location would be replaced by the actual location. _ is the cursor position after entering the command.

     (gdb) break location

     Breakpoint number at location

     (gdb) _

     

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?kehaus 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?kehaus (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.³

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

     $ _

     

• Sample Program: Source 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.⁴

     GNU DDD Version 3.3.9, by Dorothea L?kehaus and Andreas Zeller.

     Copyright © 1995-1999 Technische Universit? Braunschweig, Germany.

     Copyright © 1999-2001 Universit? Passau, Germany.

     Copyright © 2001-2004 Universit? 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.

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: How to invoke DDD.
• Quitting: How to quit DDD.
• Sessions: Saving work across invocations.
• Remote Debugging: Running DDD on a different host.
• Customizing Debugger Interaction: How DDD and GDB communicate.

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: Which debugger to use?
• Options: How to invoke DDD
• X Options: Setting X properties
• Inferior Debugger Options: Customizing GDB, DBX, and so on
• Multiple Instances: Running multiple DDD instances
• X Warnings: Turning off obnoxious warnings

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.

DDD Options

You can further control how DDD starts up using the following options. All options may be abbreviated, as long as they are unambiguous; single dashes - instead of double dashes -- may also be used. Almost all options control a specific DDD resource or resource class (see Customizing).

--attach-windows

Attach the source and data windows to the debugger console, creating one single big DDD window. This is the default setting.

Giving this option is equivalent to setting the DDD Separate resource class to off. See Window Layout, for details.

--attach-source-window

Attach only the source window to the debugger console.

Giving this option is equivalent to setting the DDD separateSourceWindow resource to off. See Window Layout, for details.

--attach-data-window

Attach only the source window to the debugger console.

Giving this option is equivalent to setting the DDD separateDataWindow resource to off. See Window Layout, for details.

--automatic-debugger

Determine the inferior debugger automatically from the given arguments.

Giving this option is equivalent to setting the DDD autoDebugger resource to on. See Customizing Debugger Interaction, for details.

--button-tips

Enable button tips.

Giving this option is equivalent to setting the DDD buttonTips resource to on. See Customizing Help, for details.

--configuration

Print the DDD configuration settings on standard output and exit.

Giving this option is equivalent to setting the DDD showConfiguration resource to on. See Diagnostics, for details.

--check-configuration

Check the DDD environment (in particular, the X configuration), report any possible problem causes and exit.

Giving this option is equivalent to setting the DDD checkConfiguration resource to on. See Diagnostics, for details.

--data-window

Open the data window upon start-up.

Giving this option is equivalent to setting the DDD openDataWindow resource to on. See Toggling Windows, for details.

--dbx

Run DBX as inferior debugger.

Giving this option is equivalent to setting the DDD debugger resource to dbx. See Customizing Debugger Interaction, for details.

--debugger name

Invoke the inferior debugger name. This is useful if you have several debugger versions around, or if the inferior debugger cannot be invoked under its usual name (i.e. gdb, wdb, dbx, xdb, jdb, pydb, or perl).

This option can also be used to pass options to the inferior debugger that would otherwise conflict with DDD options. For instance, to pass the option -d directory to XDB, use:

          ddd --debugger "xdb -d directory"

          

If you use the --debugger option, be sure that the type of inferior debugger is specified as well. That is, use one of the options --gdb, --dbx, --xdb, --jdb, --pydb, or --perl (unless the default setting works fine).

Giving this option is equivalent to setting the DDD debuggerCommand resource to name. See Customizing Debugger Interaction, for details.

--debugger-console

Open the debugger console upon start-up.

Giving this option is equivalent to setting the DDD openDebuggerConsole resource to on. See Toggling Windows, for details.

--disassemble

Disassemble the source code. See also the --no-disassemble option, below.

Giving this option is equivalent to setting the DDD disassemble resource to on. See Customizing Source, for details.

--exec-window

Run the debugged program in a specially created execution window. This is useful for programs that have special terminal requirements not provided by the debugger window, as raw keyboard processing or terminal control sequences. See Using the Execution Window, for details.

Giving this option is equivalent to setting the DDD separateExecWindow resource to on. See Customizing the Execution Window, for details.

--font fontname

-fn fontname

Use fontname as default font.

Giving this option is equivalent to setting the DDD defaultFont resource to fontname. See Customizing Fonts, for details.

--fonts

Show the font definitions used by DDD on standard output.

Giving this option is equivalent to setting the DDD showFonts resource to on. See Diagnostics, for details.

--fontsize size

Set the default font size to size (in 1/10 points). To make DDD use 12-point fonts, say --fontsize 120.

Giving this option is equivalent to setting the DDD FontSize resource class to size. See Customizing Fonts, for details.

--fullname

-f

Enable the TTY interface, taking additional debugger commands from standard input and forwarding debugger output on standard output. Current positions are issued in GDB -fullname format suitable for debugger front-ends. By default, both the debugger console and source window are disabled. See TTY mode, for a discussion.

Giving this option is equivalent to setting the DDD TTYMode resource class to on. See TTY mode, for details.

--gdb

Run GDB as inferior debugger.

Giving this option is equivalent to setting the DDD debugger resource to gdb. See Customizing Debugger Interaction, for details.

--glyphs

Display the current execution position and breakpoints as glyphs. See also the --no-glyphs option, below.

Giving this option is equivalent to setting the DDD displayGlyphs resource to on. See Customizing Source, for details.

--help

-h

-?

Give a list of frequently used options. Show options of the inferior debugger as well.

Giving this option is equivalent to setting the DDD showInvocation resource to on. See Diagnostics, for details.

--host hostname

--host username@hostname

Invoke the inferior debugger directly on the remote host hostname. If username is given and the --login option is not used, use username as remote user name. See Remote Debugger, for details.

Giving this option is equivalent to setting the DDD debuggerHost resource to hostname. See Remote Debugger, for details.

--jdb

Run JDB as inferior debugger.

Giving this option is equivalent to setting the DDD debugger resource to gdb. See Customizing Debugger Interaction, for details.

--ladebug

Run Ladebug as inferior debugger.

Giving this option is equivalent to setting the DDD debugger resource to ladebug. See Customizing Debugger Interaction, for details.

--lesstif-hacks

Equivalent to --lesstif-version 999. Deprecated.

Giving this option is equivalent to setting the DDD lessTifVersion resource to 999. See LessTif, for details.

--lesstif-version version

Enable some hacks to make DDD run properly with LessTif. See LessTif, for a discussion.

Giving this option is equivalent to setting the DDD lessTifVersion resource to version. See LessTif, for details.

--license

Print the DDD license on standard output and exit.

Giving this option is equivalent to setting the DDD showLicense resource to on. See Diagnostics, for details.

--login username

-l username

Use username as remote user name. See Remote Debugger, for details.

Giving this option is equivalent to setting the DDD debuggerHostLogin resource to username. See Remote Debugger, for details.

--maintenance

Enable the top-level Maintenance menu with options for debugging DDD. See Maintenance Menu, for details.

Giving this option is equivalent to setting the DDD maintenance resource to on. See Maintenance Menu, for details.

--manual

Print the DDD manual on standard output and exit.

Giving this option is equivalent to setting the DDD showManual resource to on. See Diagnostics, for details.

--news

Print the DDD news on standard output and exit.

Giving this option is equivalent to setting the DDD showNews resource to on. See Diagnostics, for details.

--no-button-tips

Disable button tips.

Giving this option is equivalent to setting the DDD buttonTips resource to off. See Customizing Help, for details.

--no-data-window

Do not open the data window upon start-up.

Giving this option is equivalent to setting the DDD openDataWindow resource to off. See Toggling Windows, for details.

--no-debugger-console

Do not open the debugger console upon start-up.

Giving this option is equivalent to setting the DDD openDebuggerConsole resource to off. See Toggling Windows, for details.

--no-disassemble

Do not disassemble the source code.

Giving this option is equivalent to setting the DDD disassemble resource to off. See Customizing Source, for details.

--no-exec-window

Do not run the debugged program in a specially created execution window; use the debugger console instead. Useful for programs that have little terminal input/output, or for remote debugging. See Using the Execution Window, for details.

Giving this option is equivalent to setting the DDD separateExecWindow resource to off. See Customizing the Execution Window, for details.

--no-glyphs

Do not use glyphs; display the current execution position and breakpoints as text characters.

Giving this option is equivalent to setting the DDD displayGlyphs resource to off. See Customizing Source, for details.

--no-lesstif-hacks

Equivalent to --lesstif-version 1000. Deprecated.

Giving this option is equivalent to setting the DDD lessTifVersion resource to 1000. See LessTif, for details.

--no-maintenance

Do not enable the top-level Maintenance menu with options for debugging DDD. This is the default. See Maintenance Menu, for details.

Giving this option is equivalent to setting the DDD maintenance resource to off. See Maintenance Menu, for details.

--no-source-window

Do not open the source window upon start-up.

Giving this option is equivalent to setting the DDD openSourceWindow resource to off. See Toggling Windows, for details.

--no-value-tips

Disable value tips.

Giving this option is equivalent to setting the DDD valueTips resource to off. See Value Tips, for details.

--nw

Do not use the X window interface. Start the inferior debugger on the local host.

--perl

Run Perl as inferior debugger.

Giving this option is equivalent to setting the DDD debugger resource to perl. See Customizing Debugger Interaction, for details.

--pydb

Run PYDB as inferior debugger.

Giving this option is equivalent to setting the DDD debugger resource to pydb. See Customizing Debugger Interaction, for details.

--panned-graph-editor

Use an Athena panner to scroll the data window. Most people prefer panners on scroll bars, since panners allow two-dimensional scrolling. However, the panner is off by default, since some M*tif implementations do not work well with Athena widgets. See Display Resources, for details; see also --scrolled-graph-editor, below.

Giving this option is equivalent to setting the DDD pannedGraphEditor resource to on. See Display Resources, for details.

--play-log log-file

Recapitulate a previous DDD session.

          ddd --play-log log-file

          

invokes DDD as inferior debugger, simulating the inferior debugger given in log-file (see below). This is useful for debugging DDD.

Giving this option is equivalent to setting the DDD playLog resource to on. See Customizing Debugger Interaction, for details.

--PLAY log-file

Simulate an inferior debugger. log-file is a ~/.ddd/log file as generated by some previous DDD session (see Logging). When a command is entered, scan log-file for this command and re-issue the logged reply; if the command is not found, do nothing. This is used by the --play option.

--rhost hostname

--rhost username@hostname

Run the inferior debugger interactively on the remote host hostname. If username is given and the --login option is not used, use username as remote user name. See Remote Debugger, for details.

Giving this option is equivalent to setting the DDD debuggerRHost resource to hostname. See Remote Debugger, for details.

--scrolled-graph-editor

Use M*tif scroll bars to scroll the data window. This is the default in most DDD configurations. See Display Resources, for details; see also --panned-graph-editor, above.

Giving this option is equivalent to setting the DDD pannedGraphEditor resource to off. See Display Resources, for details.

--separate-windows

--separate

Separate the console, source and data windows. See also the --attach options, above.

Giving this option is equivalent to setting the DDD Separate resource class to off. See Window Layout, for details.

--session session

Load session upon start-up. See Resuming Sessions, for details.

Giving this option is equivalent to setting the DDD session resource to session. See Resuming Sessions, for details.

--source-window

Open the source window upon start-up.

Giving this option is equivalent to setting the DDD openSourceWindow resource to on. See Toggling Windows, for details.

--status-at-bottom

Place the status line at the bottom of the source window.

Giving this option is equivalent to setting the DDD statusAtBottom resource to on. See Window Layout, for details.

--status-at-top

Place the status line at the top of the source window.

Giving this option is equivalent to setting the DDD statusAtBottom resource to off. See Window Layout, for details.

--sync-debugger

Do not process X events while the debugger is busy. This may result in slightly better performance on single-processor systems.

Giving this option is equivalent to setting the DDD synchronousDebugger resource to on. See Customizing Debugger Interaction, for details.

--toolbars-at-bottom

Place the toolbars at the bottom of the respective window.

Giving this option is equivalent to setting the DDD toolbarsAtBottom resource to on. See Window Layout, for details.

--toolbars-at-top

Place the toolbars at the top of the respective window.

Giving this option is equivalent to setting the DDD toolbarsAtBottom resource to off. See Window Layout, for details.

--trace

Show the interaction between DDD and the inferior debugger on standard error. This is useful for debugging DDD. If --trace is not specified, this information is written into ~/.ddd/log (~ stands for your home directory), such that you can also do a post-mortem debugging. See Logging, for details about logging.

Giving this option is equivalent to setting the DDD trace resource to on. See Diagnostics, for details.

--tty

-t

Enable TTY interface, taking additional debugger commands from standard input and forwarding debugger output on standard output. Current positions are issued in a format readable for humans. By default, the debugger console is disabled.

Giving this option is equivalent to setting the DDD ttyMode resource to on. See TTY mode, for details.

--value-tips

Enable value tips.

Giving this option is equivalent to setting the DDD valueTips resource to on. See Value Tips, for details.

--version

-v

Print the DDD version on standard output and exit.

Giving this option is equivalent to setting the DDD showVersion resource to on. See Diagnostics, for details.

--vsl-library library

Load the VSL library library instead of using the DDD built-in library. This is useful for customizing display shapes and fonts.

Giving this option is equivalent to setting the DDD vslLibrary resource to library. See VSL Resources, for details.

--vsl-path path

Search VSL libraries in path (a colon-separated directory list).

Giving this option is equivalent to setting the DDD vslPath resource to path. See VSL Resources, for details.

--vsl-help

Show a list of further options controlling the VSL interpreter. These options are intended for debugging purposes and are subject to change without further notice.

--wdb

Run WDB as inferior debugger.

Giving this option is equivalent to setting the DDD debugger resource to wdb. See Customizing Debugger Interaction, for details.

--xdb

Run XDB as inferior debugger.

Giving this option is equivalent to setting the DDD debugger resource to xdb. See Customizing Debugger Interaction, for details.

X Options

DDD also understands the following X options. Note that these options only take a single dash -.

-display display

Use the X server display. By default, display is taken from the DISPLAY environment variable.

-geometry geometry

Specify the initial size and location of the debugger console.

-iconic

Start DDD iconified.

-name name

Give DDD the name name.

-selectionTimeout timeout

Specify the timeout in milliseconds within which two communicating applications must respond to one another for a selection request.

-title name

Give the DDD window the title name.

-xrm resourcestring

Specify a resource name and value to override any defaults.

Inferior Debugger Options

All options that DDD does not recognize are passed to the inferior debugger. This section lists the most useful options of the different inferior debuggers supported by DDD. In case these options do not work as expected, please lookup the appropriate reference.

• GDB Options:
• DBX and Ladebug Options:
• XDB Options:
• JDB Options:
• PYDB Options:
• Perl Options:
• Bash Options:

GDB Options

These GDB options are useful when using DDD with GDB as inferior debugger. Single dashes - instead of double dashes -- may also be used.

-b baudrate

Set serial port baud rate used for remote debugging.

--cd dir

Change current directory to dir.

--command file

Execute GDB commands from file.

--core corefile

Analyze the core dump corefile.

--directory dir

-d dir

Add directory to the path to search for source files.

--exec execfile

Use execfile as the executable.

--mapped

Use mapped symbol files if supported on this system.

--nx

-n

Do not read .gdbinit file.

--readnow

Fully read symbol files on first access.

--se file

Use file as symbol file and executable file.

--symbols symfile

Read symbols from symfile.

See Invoking GDB, for further options that can be used with GDB.

DBX and Ladebug Options

DBX variants differ widely in their options, so we cannot give a list here. Check out the dbx(1) and ladebug(1) manual pages.

XDB Options

These XDB options are useful when using DDD with XDB as inferior debugger.

-d dir

Specify dir as an alternate directory where source files are located.

-P process-id

Specify the process ID of an existing process the user wants to debug.

-l library

Pre-load information about the shared library library. -l ALL means always pre-load shared library information.

-S num

Set the size of the string cache to num bytes (default is 1024, which is also the minimum).

-s

Enable debugging of shared libraries.

Further options can be found in the xdb(1) manual page.

JDB Options

JDB as of JDK 1.2

The following JDB options are useful when using DDD with JDB (from JDK 1.2) as inferior debugger.

-attach address

attach to a running virtual machine (VM) at address using standard connector

-listen address

wait for a running VM to connect at address using standard connector

-listenany

wait for a running VM to connect at any available address using standard connector

-launch

launch VM immediately instead of waiting for run command

These JDB options are forwarded to the debuggee:

-verbose[:class|gc|jni]

-v

Turn on verbose mode.

-Dname=value

Set the system property name to value.

-classpath path

List directories in which to look for classes. path is a list of directories separated by colons.

-X option

Non-standard target VM option

JDB as of JDK 1.1

The following JDB options are useful when using DDD with JDB (from JDK 1.1) as inferior debugger.

-host hostname

host machine of interpreter to attach to

-password psswd

password of interpreter to attach to (from -debug)

These JDB options are forwarded to the debuggee:

-verbose

-v

Turn on verbose mode.

-debug

Enable remote Java debugging,

-noasyncgc

Don't allow asynchronous garbage collection.

-verbosegc

Print a message when garbage collection occurs.

-noclassgc

Disable class garbage collection.

-checksource

-cs

Check if source is newer when loading classes.

-ss number

Set the maximum native stack size for any thread.

-oss number

Set the maximum Java stack size for any thread.

-ms number

Set the initial Java heap size.

-mx number

Set the maximum Java heap size.

-Dname=value

Set the system property name to value.

-classpath path

List directories in which to look for classes. path is a list of directories separated by colons.

-prof

-prof:file

Output profiling data to ./java.prof. If file is given, write the data to ./file.

-verify

Verify all classes when read in.

-verifyremote

Verify classes read in over the network (default).

-noverify

Do not verify any class.

-dbgtrace

Print info for debugging JDB.

Further options can be found in the JDB documentation.

PYDB Options

For a list of useful PYDB options, check out the PYDB documentation.

Perl Options

The most important Perl option to use with DDD is -w; it enables several important warnings. For further options, see the perlrun(1) manual page.

Bash Options

If you have the proper bash installed, the option needed to specify debugging support is --debugger. (If your bash doesn't understand this option you need to pick up a version of bash that does from http://bashdb.sourceforge.net.)

Multiple DDD Instances

If you have multiple DDD instances running, they share common preferences and history files. This means that changes applied to one instance may get lost when being overwritten by the other instance. DDD has two means to protect you against unwanted losses. The first means is an automatic reloading of changed options, controlled by the following resource (see Customizing):

Normally, automatic reloading of options should already suffice. If you need stronger protection, DDD also provides a warning against multiple instances. This warning is disabled by default, If you want to be warned about multiple DDD invocations sharing the same preferences and history files, enable Edit => Preferences => Warn if Multiple DDD Instances are Running.

This setting is tied to the following resource (see Customizing):

X warnings

If you are bothered by X warnings, you can suppress them by setting Edit => Preferences => General => Suppress X warnings.

This setting is tied to the following resource (see Customizing):

Quitting DDD

To exit DDD, select File => Exit. You may also type the quit command at the debugger prompt or press <Ctrl+Q>. GDB and XDB also accept the q command or an end-of-file character (usually <Ctrl+D>). Closing the last DDD window will also exit DDD.

An interrupt (<ESC> or Interrupt) does not exit from DDD, but rather terminates the action of any debugger command that is in progress and returns to the debugger command level. It is safe to type the interrupt character at any time because the debugger does not allow it to take effect until a time when it is safe.

In case an ordinary interrupt does not succeed, you can also use an abort (<Ctrl+\> or Abort), which sends a SIGABRT signal to the inferior debugger. Use this in emergencies only; the inferior debugger may be left inconsistent or even exit after a SIGABRT signal.

As a last resort (if DDD hangs, for example), you may also interrupt DDD itself using an interrupt signal (SIGINT). This can be done by typing the interrupt character (usually <Ctrl+C>) in the shell DDD was started from, or by using the UNIX kill command. An interrupt signal interrupts any DDD action; the inferior debugger is interrupted as well. Since this interrupt signal can result in internal inconsistencies, use this as a last resort in emergencies only; save your work as soon as possible and restart DDD.

Persistent Sessions

If you want to interrupt your current DDD session, you can save the entire the entire DDD state as session on disk and resume later.

• Saving Sessions:
• Resuming Sessions:
• Deleting Sessions:
• Customizing Sessions:

Saving Sessions

To save a session, select File => Save Session As. You will be asked for a symbolic session name session.

If your program is running (see Running), or if you have opened a core file (see Opening Core Dumps), DDD can also include a core file in the session such that the debuggee data will be restored when re-opening it. To get a core file, DDD typically must kill the debuggee. This means that you cannot resume program execution after saving a session. Depending on your architecture, other options for getting a core file may also be available.

Including a core dump is necessary for restoring memory contents and the current execution position. To include a core dump, enable Include Core Dump.

After clicking on Save, the session is saved in ~/.ddd/sessions/session.

Here's a list of the items whose state is saved in a session:

• The state of the debugged program, as a core file.⁵
• All breakpoints and watchpoints (see Stopping).
• All signal settings (see Signals).
• All displays (see Displaying Values).⁶
• All DDD options (see Saving Options).
• All debugger settings (see Debugger Settings).
• All user-defined buttons (see Defining Buttons).
• All user-defined commands (see Defining Commands).
• The positions and sizes of DDD windows.
• The command history (see Command History).

After saving the current state as a session, the session becomes active. This means that DDD state will be saved as session defaults:

• User options will be saved in ~/.ddd/sessions/session/init instead of ~/.ddd/init. See Saving Options, for details.
• The DDD command history will be saved in ~/.ddd/sessions/session/history instead of ~/.ddd/history. See Command History, for details.

To make the current session inactive, open the default session named [None]. See Resuming Sessions, for details on opening sessions.

Resuming Sessions

To resume a previously saved session, select File => Open Session and choose a session name from the list. After clicking on Open, the entire DDD state will be restored from the given session.

The session named [None] is the default session which is active when starting DDD. To save options for default sessions, choose the default session before exiting DDD. See Saving Options, for details.

If a the restored session includes a core dump, the program being debugged will be in the same state at the time the session was saved; in particular, you can examine the program data. However, you will not be able to resume program execution since the process and its environment (open files, resources, etc.) no longer exist. However, you can restart the program, re-using the restored breakpoints and data displays.

Opening sessions also restores command definitions, buttons, display shortcuts and the source tab width. This way, you can maintain a different set of definitions for each session.

You can also specify a session to open when starting DDD. To invoke DDD with a session session, use

     ddd --session session

     

There is also a shortcut that opens the session session and invokes the inferior debugger on an executable named session (in case session cannot be opened):

     ddd =session

     

There is no need to give further command-line options when restarting a session, as they will be overridden by the options saved in the session.

You can also use an X session manager such as xsm to save and restore DDD sessions.⁷ When being shut down by a session manager, DDD saves its state under the name specified by the session manager; resuming the X session makes DDD reload its saved state.

Deleting Sessions

To delete sessions that are no longer needed, select File => Open Session or File => Save Session. Select the sessions you want to delete and click on Delete.

The default session [None] cannot be deleted.

Customizing Sessions

You can change the place where DDD saves its sessions by setting the environment variable DDD_SESSIONS to the name of a directory. Default is ~/.ddd/sessions/.

Where applicable, DDD supports a gcore command to obtain core files of the running program. You can enter its path via Edit => Preferences => Helpers => Get Core File. Leave the value empty if you have no gcore or similar command.

This setting is tied to the following resource (see Customizing):

Remote Debugging

You can have each of DDD, the inferior debugger, and the debugged program run on different machines.

• Remote Host: Running DDD on a Remote Host
• Remote Debugger: Using a Remote Inferior Debugger
• Remote Program: Debugging a Remote Program

Running DDD on a Remote Host

You can run DDD on a remote host, using your current host as X display. On the remote host, invoke DDD as

     ddd -display display

     

where display is the name of the X server to connect to (for instance, hostname:0.0, where hostname is your host).

Instead of specifying -display display, you can also set the DISPLAY environment variable to display.

Using DDD with a Remote Inferior Debugger

In order to run the inferior debugger on a remote host, you need remsh (called rsh on BSD systems) access on the remote host.

To run the debugger on a remote host hostname, invoke DDD as

     ddd --host hostname remote-program

     

If your remote username differs from the local username, use

     ddd --host hostname --login username remote-program

     

or

     ddd --host username@hostname remote-program

     

instead.

There are a few caveats in remote mode:

• The remote debugger is started in your remote home directory. Hence, you must specify an absolute path name for remote-program (or a path name relative to your remote home directory). Same applies to remote core files. Also, be sure to specify a remote process id when debugging a running program.
• The remote debugger is started non-interactively. Some DBX versions have trouble with this. If you do not get a prompt from the remote debugger, use the --rhost option instead of --host. This will invoke the remote debugger via an interactive shell on the remote host, which may lead to better results.

  Note: using --rhost, DDD invokes the inferior debugger as soon as a shell prompt appears. The first output on the remote host ending in a space character or > and not followed by a newline is assumed to be a shell prompt. If necessary, adjust your shell prompt on the remote host.

• To run the remote program, DDD invokes an xterm terminal emulator on the remote host, giving your current DISPLAY environment variable as address. If the remote host cannot invoke xterm, or does not have access to your X display, start DDD with the --no-exec-window option. The program input/output will then go through the DDD debugger console.
• In remote mode, all sources are loaded from the remote host; file dialogs scan remote directories. This may result in somewhat slower operation than normal.
• To help you find problems due to remote execution, run DDD with the --trace option. This prints the shell commands issued by DDD on standard error.

See Customizing Remote Debugging, for customizing remote mode.

• Customizing Remote Debugging:

Customizing Remote Debugging

When having the inferior debugger run on a remote host (see Remote Debugging), all commands to access the inferior debugger as well as its files must be run remotely. This is controlled by the following resources (see Customizing):

          Ddd*listCoreCommand: \

          file @MASK@ | grep '.*:.*core.*' | cut -d: -f1

          

          Ddd*listDirCommand: \

          file @MASK@ | grep '.*:.*directory.*' | cut -d: -f1

          

          Ddd*listExecCommand: \

          file @MASK@ | grep '.*:.*exec.*' \

            | grep -v  '.*:.*script.*' \

            | cut -d: -f1 | grep -v '.*\.o$'

          

          Ddd*listSourceCommand: \

          file @MASK@ | grep '.*:.*text.*' | cut -d: -f1

          

Debugging a Remote Program

The GDB debugger allows you to run the debugged program on a remote machine (called remote target), while GDB runs on the local machine.

See Remote Debugging, for details. Basically, the following steps are required:

• Transfer the executable to the remote target.
• Start gdbserver on the remote target.
• Start DDD using GDB on the local machine, and load the same executable using the GDB file command.
• Attach to the remote gdbserver using the GDB target remote command.

The local .gdbinit file is useful for setting up directory search paths, etc.

Of course, you can also combine DDD remote mode and GDB remote mode, running DDD, GDB, and the debugged program each on a different machine.

Customizing Interaction with the Inferior Debugger

These settings control the interaction of DDD with its inferior debugger.

• Debugger Invocation:
• Debugger Initialization:
• Debugger Communication:

Invoking an Inferior Debugger

To choose the default inferior debugger, select Edit => Preferences => Startup => Debugger Type. You can

• have DDD determine the appropriate inferior debugger automatically from its command-line arguments. Set Determine Automatically from Arguments to enable.
• have DDD start the debugger of your choice, as specified in Debugger Type.

The following DDD resources control the invocation of the inferior debugger (see Customizing).

Initializing the Inferior Debugger

DDD uses a number of resources to initialize the inferior debugger (see Customizing).

• GDB Initialization:
• DBX Initialization:
• XDB Initialization:
• JDB Initialization:
• PYDB Initialization:
• Perl Initialization:
• Bash Initialization:
• Finding a Place to Start:
• Opening the Selection:

GDB Initialization

            Ddd*gdbInitCommands: \

            set height 0\n\

            set width 0\n\

             set verbose off\n\

            set prompt (gdb) \n

          

            Ddd*gdbSettings: \

            set print asm-demangle on\n

          

DBX Initialization

XDB Initialization

JDB Initialization

PYDB Initialization

Perl Initialization

Bash Initialization

Finding a Place to Start

          main\n\

          MAIN\n\

          main_\n\

          MAIN_\n\

          main__\n\

          MAIN__\n\

          _main\n\

          _MAIN\n\

          __main\n\

          __MAIN

          

Opening the Selection

Communication with the Inferior Debugger

The following resources control the communication with the inferior debugger.

The DDD Windows

DDD is composed of three main windows. From top to bottom, we have:

• The Data Window shows the current data of the debugged program. See Displaying Values, for details.
• The Source Window shows the current source code of the debugged program. See Navigating, for details.
• The Debugger Console accepts debugger commands and shows debugger messages. See Commands, for details.

Besides these three main windows, there are some other optional windows:

• The Command Tool offers buttons for frequently used commands. It is usually placed on the source window. See Command Tool, for details.
• The Machine Code Window shows the current machine code. It is usually placed beneath the current source. See Machine Code, for details.
• The Execution Window shows the input and output of the debugged program. See Using the Execution Window, for details.

• Menu Bar: All DDD pull-down menus.
• Tool Bar: The DDD icon buttons.
• Command Tool: The floating command tool.
• Getting Help: What does this thing mean?
• Undo and Redo: Oops!
• Customizing: You can customize DDD

The Menu Bar

The DDD Menu Bar gives you access to all DDD functions.

File

Perform file-related operations such as selecting programs, processes, and sessions, printing graphs, recompiling, as well as exiting DDD.

Edit

Perform standard editing operations, such as cutting, copying, pasting, and killing selected text. Also allows editing DDD options and preferences.

View

Allows accessing the individual DDD windows.

Program

Perform operations related to the program being debugged, such as starting and stopping the program.

Commands

Perform operations related to DDD commands, such as accessing the command history or defining new commands.

Status

Examine the program status, such as the stack traces, registers, or threads.

Source

Perform source-related operations such as looking up items or editing breakpoints.

Data

Perform data-related operations such as editing displays or layouting the display graph.

Maintenance

Perform operations that are useful for debugging DDD. By default, this menu is disabled.

Help

Give help on DDD usage.

There are two ways of selecting an item from a pull-down menu:

• Select an item in the menu bar by moving the cursor over it and click mouse button 1. Then move the cursor over the menu item you want to choose and click left again.
• Select an item in the menu bar by moving the cursor over it and click and hold mouse button 1. With the mouse button depressed, move the cursor over the menu item you want, then release it to make your selection.

The menus can also be torn off (i.e. turned into a persistent window) by selecting the dashed line at the top.

If a command in the pull-down menu is not applicable in a given situation, the command is disabled and its name appears faded. You cannot invoke items that are faded. For example, many commands on the Edit menu appear faded until you select text on which they are to operate; after you select a block of text, edit commands are enabled.

• File Menu: Selecting programs and processes.
• Edit Menu: Cut, copy, paste, and preferences.
• View Menu: All DDD windows.
• Program Menu: Starting and stopping.
• Commands Menu: All DDD commands.
• Status Menu: Examining the program status.
• Source Menu: Navigating around.
• Data Menu: Examining data.
• Maintenance Menu: Maintaining DDD.
• Help Menu: Getting help.
• Customizing the Menu Bar: Alternate key bindings, etc.

The File Menu

The File menu contains file-related operations such as selecting programs, processes, and sessions, printing graphs, recompiling, as well as exiting DDD.

Open Program

Open Class

Open a program or class to be debugged (<Ctrl+O>). See Opening Programs, for details.

Open Recent

Re-open a recently opened program to be debugged. See Opening Programs, for details.

Open Core Dump

Open a core dump for the currently debugged program. See Opening Core Dumps, for details.

Open Source

Open a source file of the currently debugged program. See Opening Source Files, for details.

Open Session

Resume a previously saved DDD session (<Ctrl+N>). See Resuming Sessions, for details.

Save Session As

Save the current DDD session such that you can resume it later (<Ctrl+S>). See Saving Sessions, for details.

Attach to Process

Attach to a running process of the debugged program. See Attaching to a Process, for details.

Detach Process

Detach from the running process. See Attaching to a Process, for details.

Print Graph

Print the current graph on a printer. See Printing the Graph, for details.

Change Directory

Change the working directory of your program. See Working Directory, for details.

Make

Run the make program (<Ctrl+M>). See Recompiling, for details.

Close

Close this DDD window (<Ctrl+W>). See Quitting, for details.

Restart

Restart DDD.

Exit

Exit DDD (<Ctrl+Q>). See Quitting, for details.

The Edit Menu

The Edit menu contains standard editing operations, such as cutting, copying, pasting, and killing selected text. Also allows editing DDD options and preferences.

Undo

Undo the most recent action (<Ctrl+Z>). Almost all commands can be undone this way. See Undo and Redo, for details.

Redo

Redo the action most recently undone (<Ctrl+Y>). Every command undone can be redone this way. See Undo and Redo, for details.

Cut

Removes the selected text block from the current text area and makes it the X clipboard selection (<Ctrl+X> or <Shift+Del>; See Customizing the Edit Menu, for details). Before executing this command, you have to select a region in a text area--either with the mouse or with the usual text selection keys.

This item can also be applied to displays (see Deleting Displays).

Copy

Makes a selected text block the X clipboard selection (<Ctrl+C> or <Ctrl+Ins>; See Customizing the Edit Menu, for details). You can select text by selecting a text region with the usual text selection keys or with the mouse. See Customizing the Edit Menu, for changing the default accelerator.

This item can also be applied to displays (see Deleting Displays).

Paste

Inserts the current value of the X clipboard selection in the most recently selected text area (<Ctrl+V> or <Shift+Ins>; See Customizing the Edit Menu, for details). You can paste in text you have placed in the clipboard using Copy or Cut. You can also use Paste to insert text that was pasted into the clipboard from other applications.

Clear

Clears the most recently selected text area (<Ctrl+U>).

Delete

Removes the selected text block from the most recently selected text area, but does not make it the X clipboard selection.

This item can also be applied to displays (see Deleting Displays).

Select All

Selects all characters from the most recently selected text area (<Ctrl+A> or or <Ctrl+Shift+A>; see Customizing the Edit Menu, for details).

Preferences

Allows you to customize DDD interactively. See Customizing, for details.

Debugger Settings

Allows you to customize the inferior debugger. See Debugger Settings, for details.

Save Options

If set, all preferences and settings will be saved for the next DDD invocation. See Saving Options, for details.

The View Menu

The View menu allows accessing the individual DDD windows.

Command Tool

Open and recenter the command tool (<Alt+8>). See Command Tool, for details.

Execution Window

Open the separate execution window (<Alt+9>). See Using the Execution Window, for details.

Debugger Console

Open the debugger console (<Alt+1>). See Commands, for details.

Source Window

Open the source window (<Alt+2>). See Navigating, for details.

Data Window

Open the data window (<Alt+3>). See Displaying Values, for details.

Machine Code Window

Show machine code (<Alt+4>). See Machine Code, for details.

The Program Menu

The Program menu performs operations related to the program being debugged, such as starting and stopping the program.

Most of these operations are also found on the command tool (see Command Tool).

Run

Start program execution, prompting for program arguments (<F2>). See Starting Program Execution, for details.

Run Again

Start program execution with the most recently used arguments (<F3>). See Starting Program Execution, for details.

Run in Execution Window

If enabled, start next program execution in separate execution window. See Using the Execution Window, for details.

Step

Continue running your program until control reaches a different source line, then stop it and return control to DDD (<F5>). See Resuming Execution, for details.

Step Instruction

Execute one machine instruction, then stop and return to DDD (<Shift+F5>). See Machine Code Execution, for details.

Next

Continue to the next source line in the current (innermost) stack frame (<F6>). This is similar to Step, but function calls that appear within the line of code are executed without stopping. See Resuming Execution, for details.

Next Instruction

Execute one machine instruction, but if it is a function call, proceed until the function returns (<Shift+F6>). See Machine Code Execution, for details.

Until

Continue running until a source line past the current line, in the current stack frame, is reached (<F7>). See Resuming Execution, for details.

Finish

Continue running until just after function in the selected stack frame returns (<F8>). Print the returned value (if any). See Resuming Execution, for details.

Continue

Resume program execution, at the address where your program last stopped (<F9>); any breakpoints set at that address are bypassed. See Resuming Execution, for details.

Continue Without Signal

Continue execution without giving a signal (<Shift+F9>). This is useful when your program stopped on account of a signal and would ordinary see the signal when resumed with Continue. See Signals, for details.

Kill

Kill the process of the debugged program (<F4>). See Killing the Program, for details.

Interrupt

Interrupt program execution (<Esc> or <Ctrl+C>; see Customizing the Edit Menu, for details). This is equivalent to sending an interrupt signal to the process. See Interrupting, for details.

Abort

Abort program execution (and maybe debugger execution, too; <Ctrl+\>). This is equivalent to sending a SIGABRT signal to the process. See Quitting, for details.

The Commands Menu

The Commands menu performs operations related to DDD commands, such as accessing the command history or defining new commands.

Most of these items are not meant to be actually executed via the menu; instead, they serve as reminder for the equivalent keyboard commands.

Command History

View the command history. See Command History, for details.

Previous

Show the previous command from the command history (<Up>). See Command History, for details.

Next

Show the next command from the command history (<Down>). See Command History, for details.

Find Backward

Do an incremental search backward through the command history (<Ctrl+B>). See Command History, for details.

Find Forward

Do an incremental search forward through the command history (<Ctrl+F>). See Command History, for details.

Quit Search

Quit incremental search through the command history (<Esc>). See Command History, for details.

Complete

Complete the current command in the debugger console (<Tab>). See Entering Commands, for details.

Apply

Apply the current command in the debugger console (<Apply>). See Entering Commands, for details.

Clear Line

Clear the current command line in the debugger console (<Ctrl+U>). See Entering Commands, for details.

Clear Window

Clear the debugger console (<Shift+Ctrl+U>). See Entering Commands, for details.

Define Command

Define a new debugger command. See Defining Commands, for details.

Edit Buttons

Customize DDD buttons. See Defining Buttons, for details.

The Status Menu

The Status menu lets you examine the program status, such as the stack traces, registers, or threads.

Backtrace

View the current backtrace. See Backtraces, for a discussion.

Registers

View the current register contents. See Registers, for details.

Threads

View the current threads. See Threads, for details.

Signals

View and edit the current signal handling. See Signals, for details.

Up

Select the stack frame (i.e. the function) that called this one (<Ctrl+Up>). This advances toward the outermost frame, to higher frame numbers, to frames that have existed longer. See Stack, for details.

Down

Select the stack frame (i.e. the function) that was called by this one (<Ctrl+Down>). This advances toward the innermost frame, to lower frame numbers, to frames that were created more recently. See Stack, for details.

The Source Menu

The Source menu performs source-related operations such as looking up items or editing breakpoints.

Breakpoints

Edit all Breakpoints. See Editing all Breakpoints, for details.

Lookup ()

Look up the argument () in the source code (<Ctrl+/>). See Looking up Definitions, for details.

Find >> ()

Look up the next occurrence of the argument () in the current source code (<Ctrl+.>). See Textual Search, for details.

Find << ()

Look up the previous occurrence of the argument () in the current source code (<Ctrl+,>). See Textual Search, for details.

Find Words Only

If enabled, find only complete words (<Alt+W>). See Textual Search, for details.

Find Case Sensitive

If enabled, find is case-sensitive (<Alt+I>). See Textual Search, for details.

Display Line Numbers

If enabled, prefix source lines with their line number (<Alt+N>). See Customizing Source, for details.

Display Machine Code

If enabled, show machine code (<Alt+4>). See Machine Code, for details.

Edit Source

Invoke an editor for the current source file (<Shift+Ctrl+V>). See Editing Source Code, for details.

Reload Source

Reload the current source file (<Shift+Ctrl+L>). See Editing Source Code, for details.

The Data Menu

The Data menu performs data-related operations such as editing displays or layouting the display graph.

Displays

Invoke the Display Editor. See Editing all Displays, for details.

Watchpoints

Edit all Watchpoints. See Editing all Watchpoints, for details.

Memory

View a memory dump. See Examining Memory, for details.

Print ()

Print the value of () in the debugger console (<Ctrl+=>). See Printing Values, for details.

Display ()

Display the value of () in the data window (<Ctrl+->). See Displaying Values, for details.

Detect Aliases

If enabled, detect shared data structures (<Alt+A>). See Shared Structures, for a discussion.

Display Local Variables

Show all local variables in a display (<Alt+L>). See Displaying Local Variables, for details.

Display Arguments

Show all arguments of the current function in a display (<Alt+U>). See Displaying Local Variables, for details.

Status Displays

Show current debugging information in a display. See Displaying Program Status, for details.

Align on Grid

Align all displays on the grid (<Alt+G>). See Aligning Displays, for a discussion.

Rotate Graph

Rotate the graph by 90 degrees (<Alt+R>). See Rotating the Graph, for details.

Layout Graph

Layout the graph (<Alt+Y>). See Layouting the Graph, for details.

Refresh

Update all values in the data window (<Ctrl+L>). See Refreshing the Data Window, for details.

The Maintenance Menu

The Maintenance menu performs operations that are useful for debugging DDD.

By default, this menu is disabled; it is enabled by specifically requesting it at DDD invocation (via the --maintenance option; see Options). It is also enabled when DDD gets a fatal signal.

Debug DDD

Invoke a debugger (typically, GDB) and attach it to this DDD process (<F12>). This is useful only if you are a DDD maintainer.

Dump Core Now

Make this DDD process dump core. This can also be achieved by sending DDD a SIGUSR1 signal.

Tic Tac Toe

Invoke a Tic Tac Toe game. You must try to get three stop signs in a row, while preventing DDD from doing so with its skulls. Click on New Game to restart.

When DDD Crashes

Select what to do when DDD gets a fatal signal.

Debug DDD

Invoke a debugger on the DDD core dump when DDD crashes. This is useful only if you are a DDD maintainer.

Dump Core

Just dump core when DDD crashes; don't invoke a debugger. This is the default setting, as the core dump may contain important information required for debugging DDD.

Do Nothing

Do not dump core or invoke a debugger when DDD crashes.

Remove Menu

Make this menu inaccessible again.

The Help Menu

The Help menu gives help on DDD usage. See Getting Help, for a discussion on how to get help within DDD.

Overview

Explains the most important concepts of DDD help.

On Item

Lets you click on an item to get help on it.

On Window

Gives you help on this DDD window.

What Now?

Gives a hint on what to do next.

Tip of the Day

Shows the current tip of the day.

DDD Reference

Shows the DDD Manual.

DDD News

Shows what's new in this DDD release.

Debugger Reference

Shows the on-line documentation for the inferior debugger.

DDD License

Shows the DDD License (see License).

DDD WWW Page

Invokes a WWW browser for the DDD WWW page.

About DDD

Shows version and copyright information.

Customizing the Menu Bar

The Menu Bar can be customized in various ways (see Customizing).

• Auto-Raise Menus:
• Customizing the Edit Menu:

Auto-Raise Menus

You can cause pull-down menus to be raised automatically.

Customizing the Edit Menu

In the Menu Bar, the Edit Menu can be customized in various ways. Use Edit => Preferences => Startup to customize these keys.

The <Ctrl+C> key can be bound to different actions, each in accordance with a specific style guide.

Copy

This setting binds <Ctrl+C> to the Copy operation, as specified by the KDE style guide. In this setting, use <ESC> to interrupt the debuggee.

Interrupt

The <Ctrl+A> key can be bound to different actions, too.

Select All

This (default) setting binds <Ctrl+A> to the Select All operation, as specified by the KDE style guide. In this setting, use <Home> to move the cursor to the beginning of a line.

Beginning of Line

This setting binds <Ctrl+A> to the Beginning of Line operation, as used in several UNIX text-editing programs. In this setting, use <Ctrl+Shift+A> to select all text.

Here are the related DDD resources: