@DDD@ can do four main kinds of things (plus other things in support of these) to help you catch bugs in the act:
``Classical'' UNIX debuggers such as the GNU debugger (GDB) provide a command-line interface and a multitude of commands for these and other debugging purposes. @DDD@ is a wrapper around an inferior GDB or DBX debugger. In addition to the GDB or DBX command-line interface, @DDD@ provides a graphical user interface to support common debugging tasks. The @DDD@ graphical data display allows for interactive exploration of data structures.
@ddd@ program
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).
By default, @DDD@ uses GDB as inferior debugger. Use
@ddd@ --dbx program
to run DBX as inferior debugger for the program.
To learn more about @DDD@ options, run
@ddd@ --help
to get a list of frequently used options, or see the `OPTIONS' section, below.
You can get help on GDB and DBX commands by entering the `help' command at the `(gdb)' or `(dbx)' prompt (see next section).
You can repeat previous and next commands by pressing the `Up' and `Down' keys, respectively. If you enter an empty line, the last command is repeated as well. The `Command History...' item in the `Commands...' menu shows the command history.
Using GDB, you can complete commands and arguments by pressing the TAB key; pressing the TAB key multiple times shows one possible expansion after the other.
Here are some of the most frequently needed debugger commands:
For full details on GDB commands, see Using GDB: A Guide to the GNU Source-Level Debugger, by Richard M. Stallman and Roland H. Pesch. The same text is available online as the gdb entry in the info program.
For full details on DBX commands, see the DBX documentation.
To open a program to be debugged, select `Open Program' from the `File' menu.
To open a core dump for the program, select `Open Core' from the `File' menu.
To open an arbitrary source file, select `Open Source' from the `File' menu.
Using the source window, you can make the program stop at certain breakpoints and trace its execution.
As an alternative, you can simply press the right mouse button on the source line number and select the `Set Breakpoint' item from the popup menu.
As another alternative, you can enter the line number in the argument field (indicated by `():') and click on the `Break()' button.
As yet another alternative, you can select `Edit Breakpoints...' in the `Source' menu, click on the `New' button and enter the line number.
And finally, you can also use the GDB `break' command or the DBX `stop' command. Type `help break' at the `(gdb)' prompt (or `help stop' at the `(dbx)' prompt) for details.
(If you find this number of alternatives confusing, be aware that @DDD@ users fall into three categories, which must all be supported. Novice users explore @DDD@ and may prefer to use one single mouse button. Advanced users know how to use shortcuts and prefer popup menus. Experienced GDB and DBX users prefer the command line interface.)
Breakpoints are indicated by a plain stop sign, or as `#n#', where n is the breakpoint number.
As a shorter alternative, you can simply press the right mouse button on the function name and select the `break' item from the popup menu.
As another alternative, you can enter the function name in the argument field (possibly using name completion by pressing the `Tab' key) and click on the `Break()' button.
As yet another alternative, you can click on `New' from the Breakpoint editor (invoked through `Edit Breakpoints...' in the `Source' menu) and enter the function name.
Finally, you can use the GDB `break' command or the DBX `stop' command. Type `help break' at the `(gdb)' prompt (or `help stop' at the `(dbx)' prompt) for details.
Press the right mouse button on the breakpoint name and select the `Disable Breakpoint' item (or the `Enable Breakpoint' item, respectively) from the popup menu.
As an alternative, you can select the breakpoint and click on `Disable' or `Enable' in the Breakpoint editor (invoked through `Edit Breakpoints...' in the `Source' menu).
Disabled breakpoints are indicated by a grey stop sign, or `_n_', where n is the breakpoint number.
Finally, you can use the GDB `disable' command. Type `help disable' at the `(gdb)' prompt for details.
Temporary breakpoints are convenient to make the program continue up to a specific location: just set the temporary breakpoint at this location and continue execution.
The `Continue Until Here' item from the popup menu sets a temporary breakpoint on the source line number and immediately continues execution. In GDB, execution stops when a source line greater than the source line is reached, or when the current stack frame is exited. In DBX, execution stops when the temporary breakpoint is reached.
If the function name is visible, click with the left mouse button on the function name. The function name is copied to the argument field. Click on the `Clear()' button to set a breakpoint there.
As a shorter alternative, you can simply press the right mouse button on the function name and select the `clear' item from the popup menu.
As yet another alternative, you can select the breakpoint and click on `Delete' from the Breakpoint editor (invoked through `Edit Breakpoints...' in the `Source' menu).
Finally, you can use the GDB `clear' and `delete' commands. Type `help clear' or `help delete' at the `(gdb)' prompt for details.
More breakpoint features can be invoked through the command window. Enter `help breakpoints' at the `(gdb)' prompt.
As a shorter alternative, you can simply press the right mouse button on the function name and select the `lookup' item from the popup menu.
As another alternative, you can enter the function name in the argument field and click on the `Lookup()' button to find its definition.
Finally, you can use the GDB `info line' command. Type `help info line' at the `(gdb)' prompt for details.
As an alternative, you can enter the item in the argument field and click on one of the `Find' buttons.
By default, @DDD@ finds only complete words. To search for arbitrary substrings, change the value of the `Find Words Only' option in the `Source Options' menu.
As an alternative, you can enter `#n' in the argument field, where n is the breakpoint number and click on the `Lookup()' button to find its definition.
To run your program again, with the same arguments, select `Run Again' from the `Program' menu or press the `Run' button below. You may also enter `run', followed by arguments at the `(gdb)' or `(dbx)' prompt instead.
When the program is first started, @DDD@ invokes an execution window, where the program terminal input and output is shown. (You can disable this feature by starting @DDD@ with the `--no-exec-window' option.)
You can interrupt a running program any time by clicking the `Interrupt' button or typing Ctrl+C in a @DDD@ window.
To execute just one source line, click on the `Step' button. The program is executed until control reaches a different source line, which may be in a different function.
To continue to the next line in the current function, click on the `Next' button. This is similar to `Step', but any function calls appearing within the line of code are executed without stopping.
To continue running until the current function returns, use the `Finish' button. The returned value (if any) is printed.
To continue running until a line after the current source line is reached, use the `Continue Until Here' facility from the line popup menu. See `Temporary Breakpoints', above, for a discussion.
The `Up' button selects the function that called the current one.
The `Down' button selects the function that was called by the current one.
You can also type the GDB and DBX `up' and `down' commands at the `(gdb)' or `(dbx)' prompt.
As a shorter alternative, you can simply press the right mouse button on the variable name and select the `display' item from the popup menu.
As another alternative, you may also enter the variable name in the argument field and press the `Display()' button.
If the data window is visible, you may invoke the `Edit Displays...' item from the `Data' menu and click on the `New...' button. Enter the variable name in the resulting prompt dialog.
Finally, you may enter
graph display expr
at the `(gdb)' or `(dbx)' prompt.
You can select individual displays by clicking on them with the left mouse button. The resulting expression is shown in the argument field, below.
You can extend an existing selection by pressing the Shift Key while selecting.
Single displays may also be selected by using the arrow keys.
By double-clicking on a display, the display itself and all connected displays are automatically selected.
Selection of multiple display parts is not supported.
To show details about an aggregate, select the aggregate by clicking the left mouse button on its name or value and click on the `Show()' button.
To hide details about an aggregate, select the aggregate by clicking the left mouse button on its name or value and click on the `Hide()' button.
As a faster alternative, you can also press the right mouse button on the aggregate and select the appropriate menu item.
Arrays can be aligned horizontally or vertically. To change the alignment of an array, select it and then click on the `Rotate()' button.
As a faster alternative, you can also press the right mouse button on the array and select the `Rotate' menu item.
To create a dependent display, select the originating display or display part and click on the `Dependent()' button. A prompt dialog appears where you can enter a new expression EXPR in the argument field. By clicking on `OK', the new display showing EXPR is created.
As a faster alternative, you can also press the right mouse button on the originating display part and select the `Dependent Display...' menu item.
Using dependent displays, you can investigate the data structure of a ``tree'' for example and lay it out according to your intuitive image of the ``tree'' data structure.
To dereference a pointer, select the originating pointer value or name and click on the `Dereference()' button. A new display showing the dereferenced pointer value is created.
As a faster alternative, you can also press the right mouse button on the originating pointer value or name and select the `Dereference' menu item.
To display several successive objects of the same type (a section of an array, or an array of dynamically determined size), use the notation [FROM..TO] in display expressions. FROM and TO denote the first and last array position to display. Thus,
graph display argv[0..9]
creates ten new display nodes for `argv[0]',
`argv[1]', ..., `argv[9]'.
As an alternative, you can use GDB artificial arrays. Typing
graph display argv[0] @ 10
creates a single array display node containing `argv[0]' up to
`argv[9]'. Generally, by using the `@' operator, you
can specify the number of array elements to be displayed.
For more details on artificial arrays, see the GDB documentation.
When a display is deleted, its immediate ancestors and descendants are automatically selected, so that you can easily delete entire graphs.
To delete several displays at once, select the `Delete...' item in the Display Editor (invoked through the `Edit Displays...' item in the `Data' menu). Select any number of display items in the usual way and delete them by pressing `Delete'.
As an alternative, you can also type
undisplay NUM...
at the `(gdb)' or `(dbx)' prompt, where NUM... is a
space-separated list of the displays to delete. You may need to
refresh the data window afterwards (see below).
Unlike a deleted display item, a disabled display item remains in the display, but its value is not shown until it is enabled again.
Displays are enabled and disabled the same way they are deleted, using the `Disable()'/`Enable()' button, the `Disable'/`Enable Display' popup menu item, or the `Disable'/`Enable' buttons in the Display Editor.
The corresponding GDB commands are
disable display NUM...
and
enable display NUM...
The data window should be refreshed whenever:
You can refresh the data window by selecting the `Refresh Displays' item in the `Data' menu.
As an alternative, you can press the right mouse button on the background of the data window and select the `Refresh Display' item.
Typing
graph refresh
at the `(gdb)' or `(dbx)' prompt has the same effect.
If the data window becomes too small to hold all displays, scroll bars are created. If your @DDD@ is set up to use panners instead, a panner is created in the lower right edge. When the panner is moved around, the window view follows the position of the panner. See `CUSTOMIZING @DDD@', below, for details on how to set up scroll bars or panners.
For fine-grain movements, selected displays may also be moved using the arrow keys. Pressing Shift and an arrow key moves displays by single pixels. Pressing Ctrl and arrow keys moves displays by grid positions.
You can enforce alignment by selecting `Snap to Grid' in the `Data Options' menu. If `Snap to Grid' is enabled, displays can be moved on grid positions only.
Layouting the graph may introduce edge hints; that is, edges are no more straight lines, but lead to an edge hint and from there to their destination. You can make edge hints visible by selecting `Show Edge Hints' in the `Data Options' menu. Edge hints can be moved around like arbitrary displays.
To enable a more compact layout, you can set the `Compact Layout' option in the `Data Options' menu. This realizes an alternate layout algorithm, where successors are placed next to their parents. This algorithm is suitable for homogeneous data structures only.
You can enforce layout by setting the `Automatic Layout' option in the `Data Options' menu. If `Automatic Layout' is enabled, the graph is layouted after each change.
If the graph was previously layouted, you may need to layout it again. Subsequent layouts will respect the direction of the last rotation.
To print the graph on a PostScript printer, select the `Print Graph...' item from the `File' menu. Enter the printing command in the `Printer Command' field. Click on the `Print' button to start printing.
To re-print the display graph using the previous settings, select the `Print Again' item from the `File' menu.
As an alternative, you may also print the graph in a file. Click on the `File' button and enter the file name in the `File Name' field. Click on the `Print' button to create the file.
When the graph is printed in a file, two formats are available:
Sometimes, it is desirable to examine a program not only at the source level, but also at the machine level. @DDD@ provides special machine code and register windows for this task.
The machine code window works very much like the source window. You can set, clear, and change breakpoints by selecting the address and pressing a `Break()' or `Clear()' button; the usual popup menus are also available. Breakpoints and the current execution position are displayed simultaneously in both source and machine code.
The `Lookup()' button can be used to look up the machine code for a specific function---or the function for a specific address. Just click on the location in one window and press `Lookup()' to see the corresponding code in the other window.
If source code is not available, only the machine code window is updated.
To execute just one machine instruction, click on the `Stepi' button.
To continue to the next instruction in the current function, click on the `Nexti' button. This is similar to `Stepi', but any subroutine calls are executed without stopping.
By selecting one of the registers, its name is copied to the argument field. You can use it as value for `Display()', for instance, to have its value displayed in the data window.
The editor command is specified in the `editCommand' resource.
By default, @DDD@ tries to invoke the first available editor
from the following list:
After the editor has exited, the source code shown is automatically brought up-to-date.
If you have @DDD@ and an editor running in parallel, you can also update the source code manually by selecting the `Reload Source...' item from the `Source' menu. This reloads the source code shown from the source file. As @DDD@ automatically reloads the source code if the debugged program has been recompiled, this should seldom be necessary.
An interrupt (Ctrl+C) does not exit from @DDD@, but rather terminates the action of any GDB or DBX 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.
You may also interrupt @DDD@ using an interrupt signal (SIGINT)---for instance by pressing Ctrl+C in the shell @DDD@ was started from, or by using the UNIX `kill' command. This interrupts any @DDD@ action; the inferior GDB or DBX debugger is interrupted as well. Use this as a last resort in emergencies only---if @DDD@ hangs, for example.
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
instead.
There are a few caveats in remote mode:
In case your debugger front-end uses the GDB `-fullname' option to have GDB report source code positions, the `--tty' option is not required. @DDD@ recognizes the `-fullname' option, finds that it has been invoked from a debugger front-end and automatically enables the TTY interface.
You may also invoke `@ddd@ --tty' directly, entering @DDD@ commands from your TTY, or use @DDD@ as the end of a pipe, controlled by a remote program. Be aware, however, that the TTY interface does not support line editing and command completion and that @DDD@ exits as soon as it receives a EOF on its standard input. Also, do not try to run @DDD@ with @DDD@ as inferior debugger.
(setq gdb-command-name "@ddd@")
Use `M-x gdb' to start a debugging session. Proceed as usual.
xxgdb -db_name ddd -db_prompt '(gdb) '
If you frequently switch between @DDD@ and other multi-window applications, you may like to set the `Group Iconify' option. This way, all @DDD@ windows are iconified and deiconified as a group.
If you want to use TAB key completion in all text windows, set the `Global Tab Completion' option. This is useful if you have pointer-driven keyboard focus (see below) and no special usage for the TAB key.
If you want to run your debugged process in a separate terminal emulator window, set the `Run in Execution Window' option. This is useful for programs that have special terminal requirements not provided by the debugger window, as raw keyboard processing or terminal control sequences.
If you want to save changed options automatically for the next @DDD@ invocation, set the `Save Options on Exit' option.
If you want to save the command history for the next @DDD@ invocation, set the `Save Options on Exit' option. Note: This option is always set if your GDB is set up to save its command history.
If you wish to display machine code of selected funtions, set the `Display Machine Code' option. This makes @DDD@ run a little slower, so it is disabled by default.
As of this @DDD@ release, the current execution position and breakpoints are indicated by symbols (``glyphs'') in the source text. Previous releases used special texts for this purpose. If you wish to disable glyphs, unset the `Display Glyphs' option. This also makes @DDD@ run slightly faster, especially when scrolling.
By default, @DDD@ caches source files in memory. This is convenient for remote debugging, since remote file access may be slow. If you want to reduce memory usage, unset the `Cache Sources' option.
By default, @DDD@ caches machine code in memory. This is bad for memory usage, but convenient for speed, since disassembling a function each time it is reached may take time. If you want to reduce memory usage, unset the `Cache Machine Code' option.
Layouting the display graph may introduce edge hints; that is, edges are no more straight lines, but lead to an edge hint and from there to their destination. These edge hints can be selected and moved around like displays. You can make edge hints visible by setting the `Show Edge Hints' option.
To enforce alignment, you can set the `Snap to Grid' option. If `Snap to Grid' is enabled, displays can be moved on grid positions only.
To enable a more compact layout, you can set the `Compact Layout' option. This realizes an alternate layout algorithm, where successors are placed next to their parents. This algorithm is suitable for homogeneous data structures only.
To enforce layout, you can set the `Automatic Layout' option. If `Automatic Layout' is enabled, the graph is layouted after each change.
By default, @DDD@ directs keyboard input to the item your mouse pointer points at. If you prefer a click-to-type keyboard focus (that is, click on an item to make it accept keyboard input), set the `Keyboard Focus' option on `Click to type'.
By default, @DDD@ uses Motif scroll bars to scroll the data window. Many people find this inconvenient, since you can scroll in the horizontal or vertical direction only. As an alternative, @DDD@ provides a panner (a kind of two-dimensional scroll bar). This is much more comfortable, but may be incompatible with your Motif toolkit. To set up @DDD@ such that it uses panners by default, set the `Data Scrolling' option to `Panner'. This change takes only effect after you have saved options and restarted @DDD@. See also the `--panned-graph' and `--scrolled-graph' options, below.
By default, @DDD@ runs with GDB as inferior debugger. To change this default, set the `Debugger Type' option to another debugger. This change takes only effect after you have saved options and restarted @DDD@. See also the `--gdb' and `--dbx' options, below.
If you wish something done in @DDD@, but cannot do it yourself, you can finance specific @DDD@ extensions. For details, contact `ddd@ips.cs.tu-bs.de'; direct mail is also welcome.
Some of the people offering @DDD@ support may also accept offers to extend @DDD@. For a list of people offering @DDD@ support, see the file `SERVICE' in the @DDD@ distribution.
If you appreciate this software, or have any suggestions, please send us a picture postcard. Our address is:
Technische Universitaet Braunschweig
Institut fuer Programmiersprachen und Informationssysteme
Abteilung Softwaretechnologie
Gaussstrasse 17
D-38092 Braunschweig
GERMANY
You may also leave a message in the DDD guestbook (accessible via the @DDD@ WWW page, `http://www.cs.tu-bs.de/softech/ddd/')
`gdb' entry in info.
Using GDB: A Guide to the GNU Source-Level Debugger, by Richard M. Stallman and Roland H. Pesch.
DDD---A Free Graphical Front-End for UNIX Debuggers, by Andreas Zeller and Dorothea Luetkehaus, Computer Science Report 95-07, Technische Universitaet Braunschweig, 1995.
DDD --- ein Debugger mit graphischer Datendarstellung, by Dorothea Luetkehaus, Diploma Thesis, Technische Universitaet Braunschweig, 1994.
The @DDD@ FTP site,
ftp://ftp.ips.cs.tu-bs.de/pub/local/softech/ddd/
The @DDD@ World-Wide-Web page,
http://www.cs.tu-bs.de/softech/ddd/
The @DDD@ Mailing List,
For more information on this list, send a mail to
ddd-users-request@ips.cs.tu-bs.de
set height 0
set width 0
set print pretty
set print repeats 0
set verbose off
set prompt (gdb)
@DDD@ sets these values automatically when invoking GDB.
If these values are changed, there may be some malfunctions, especially in the data display. If you want to display C strings (i.e., `char *'-fields), it might be useful to change the settings of `print repeats' and `print elements'. But to recognize array structures correctly, you should have `print repeats' set to 0. Also, do not change the setting of `print elements' while there are array structures in the data display.
When debugging at the machine level with GDB 4.12 and earlier as inferior debugger, use a `display /x $pc' command to ensure the program counter value is updated correctly at each stop. You may also enter the command in $HOME/.gdbinit or (better yet) upgrade to the most recent GDB version.
Using DBX 3.x or later as inferior debugger, @DDD@
strips C-style and C++-style comments from the DBX2+2 output in
order to operate properly. This also affects the output of the
debugged program when sent to the command window. Using the separate
execution window avoids these problems.
Paper sizes larger than 2,147,483,648pt (757km, 470 miles) can not be handled.
As a last resort, send bug reports on paper to:
Technische Universitaet Braunschweig
Institut fuer Programmiersprachen und Informationssysteme
Abteilung Softwaretechnologie
DDD-Bugs
Gaussstrasse 17
D-38092 Braunschweig
GERMANY
Fax: +49 531 391-8140
@ddd@ --check-configuration
checks for common problems and gives hints on how to repair them.
Another potential cause of problems is the inferior GDB or
DBX debugger; although unlikely, they may have bugs. To find
out whether a bug was caused by GDB or DBX, run
@DDD@ as
@ddd@ --trace-dialog
This shows the dialog between @DDD@ and the inferior
debugger on standard error while @DDD@ is running. Compare
the debugger output to the @DDD@ output and determine which
one is wrong.
@ddd@ --configuration
to get the configuration information. If this does not work, please
include at least the @DDD@ version, the type of machine you
are using, and its operating system name and version number.
Be sure to include this information in every single bug report.
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 Luetkehaus 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, many people have contributed to the success of @DDD@; see the file `CONTRIBUTORS' in the @DDD@ distribution for details.
@DDD@ 1.0 was released in May, 1995.
Permission is granted to make and distribute verbatim copies of this manual page provided the copyright notice and this permission notice are preserved on all copies.
Permission is granted to copy and distribute modified versions of this manual page under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.
Permission is granted to copy and distribute translations of this manual page into another language, under the above conditions for modified versions, except that this permission notice may be included in translations approved by the Free Software Foundation instead of in the original English.
A PostScript copy of this manual page, suitable for printing, is included in the DDD source distribution and available separately as
ftp://ftp.ips.cs.tu-bs.de/pub/local/softech/ddd/doc/ddd-man.ps.gz
A ROFF copy of this manual page, suitable for installation as manual page on UNIX systems (as `/usr/local/man/man1/ddd.1' or similar), is included in the DDD source distribution.