ddd(1)

NAME
ddd, xddd - the data display debugger

SYNOPSIS

ddd [--help] [--gdb] [--dbx] [--xdb] [--debugger name ] [--session name ] [--host hostname [--login username ]] [--rhost hostname [--login username ]] [--attach-windows] [--separate-windows] [--trace] [--nw] [--tty] [--fullname] [--version] [--configuration] [--check-configuration] [--manual] [--news] [--license] [ gdb-options ] [ x-options ] [ program [ core | process-id ]]

but usually just

ddd program

DESCRIPTION
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.

“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, DBX, or XDB debugger. In addition to the command-line interface of the inferior debugger, DDD provides a common graphical user interface to support debugging tasks. The DDD graphical data display allows for interactive exploration of data structures.

INVOKING DDD
You can run DDD with no arguments or options. However, the most usual way to start DDD is with one argument or two, specifying an executable program as the argument:

  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

or

  ddd --xdb program

to run DBX or XDB as inferior debugger.

To learn more about DDD options, run

  ddd --help

to get a list of frequently used options, or see the `OPTIONS' section, below.

THE DDD WINDOWS
DDD is composed of three main windows:

•   The Data Window shows the current data of the debugged program.

•   The Source Window shows the current source code of the debugged program.

•   The Debugger Console accepts debugger commands and shows debugger messages.

By default, DDD groups these main windows into one single window, but DDD can also be configured to treat each one separately.

Besides these 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.

•   The Machine Code Window shows the current machine code. It is usually placed beneath the current source.

•   The Execution Window shows the input and output of the debugged program.

DDD also has several temporary dialogs for showing and entering additional information.

In this manual page, we discuss all the functionality associated with these windows. We start with the debugger console and its commands, continue with the source window, and continue with the data window. But before that, we tell you how to get help while working with DDD.

GETTING HELP

  Button Tips
You can get a short help text on most DDD buttons by simply moving the mouse pointer on it and leave it there. After a second, a small window (called button tip) pops up, giving a hint on the button's meaning. The button tip disappears as soon as you move the mouse pointer to another item.

  The Status Line
The status line also displays information about the currently selected item. By clicking on the status line, you can redisplay the most recent messages.

  Context-Sensitive Help
You can get detailed help on any visible DDD item. Just press the `F1' key and move the question mark arrow on the item you want help for. Clicking on the item pops up a detailed help text.

The DDD dialogs all contain `Help' buttons that give detailed information about the dialog.

  Help on Debugger Commands
You can get help on GDB and DBX commands by entering `help' at the `(gdb)' or `(dbx)' prompt. You can get help on XDB commands by entering `help' at the `>' prompt.

See `Entering Commands', below, for details on entering commands.

  Are You Stuck?
In case you're stuck, try `Help | What Now?' (the `What Now' item in the `Help' menu) or press Shift+F1. Depending on the current state, DDD will give you some hints on what you can do.

ENTERING COMMANDS
In the debugger console, you can interact with the command interface of the inferior debugger. Enter commands at the debugger prompt—that is, `(gdb)' for GDB, `(dbx)' for DBX, and `>' for XDB. You can use arbitrary debugger commands; use the RETURN key to enter them.

You can repeat previous and next commands by pressing the `Up' and `Down' arrow keys, respectively. If you enter an empty line, the last command is repeated as well. `Commands | Command History' shows the command history.

You can search for previous commands by pressing `Ctrl+R'. This invokes incremental search mode, where you can enter a string to be searched in previous commands. Press `Ctrl+R' again to repeat the search, or `Ctrl+S' to search in the reverse direction. To return to normal mode, press ESC, or use any cursor command.

Using GDB, you can also 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.

  Common GDB commands

break [file:]function
    Set a breakpoint at function (in file ).

run [arglist]
    Start your program (with arglist , if specified).

where
    Display the program stack.

print expr
    Display the value of an expression.

cont
    Continue running your program (after stopping, e.g. at a breakpoint).

next
    Execute next program line (after stopping); step over any function calls in the line.

step
    Execute next program line (after stopping); step into any function calls in the line.

help [name]
    Show information about the command name , or general usage information.

quit
    Exit DDD.

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.

  Common DBX commands

stop in function
    Set a breakpoint at function.

stop at line
    Set a breakpoint at line.

file file
    Change the current file to file.

run [arglist]
    Start your program (with arglist , if specified).

where
    Display the program stack.

print expr
    Display the value of an expression.

cont
    Continue running your program (after stopping, e.g. at a breakpoint).

next
    Execute next program line (after stopping); step over any function calls in the line.

step
    Execute next program line (after stopping); step into any function calls in the line.

help [name]
    Show information about the command name , or general usage information.

quit
    Exit DDD.

For full details on DBX commands, see the DBX documentation.

  Common XDB commands

b [file:]line
    Set a breakpoint at line line (in file ).

b function
    Set a breakpoint at function.

r [arglist]
    Start your program (with arglist , if specified).

t   Display the program stack.

p expr
    Display the value of an expression.

c   Continue running your program (after stopping, e.g. at a breakpoint).

S   Execute next program line (after stopping); step over any function calls in the line.

s   Execute next program line (after stopping); step into any function calls in the line.

h [name]
    Show information about the command name , or general usage information.

q   Exit DDD.

For full details on XDB commands, see the XDB documentation.

OPENING FILES
If you did not invoke DDD specifying a program to be debugged, you can use the `File' menu to open programs, core dumps and sources.

To open a program to be debugged, select `File | Open Program'.

To open a core dump for the program, select `File | Open Core Dump' Before `Open Core Dump', you should first use `File | Open Program' to specify the program that generated the core dump and to load its symbol table.

To open an arbitrary source file, select `File | Open Source'. This works best if the given source file is actually related to the debugged program.

Note: With XDB and some DBX versions, the debugged program must be specified upon invocation and cannot be changed at run time.

LOOKING UP ITEMS
If the source of the debugged program is available, the source window displays its current source text. (If a source text cannot be found, use the GDB `directory' command to specify source text directories).

In the source window, you can lookup and examine function and variable definitions as well as search for arbitrary occurrences in the source text.

  Looking up Definitions
If you wish to lookup a specific function or variable definition whose name is visible in the source text, click with mouse button 1 on the function or variable name. The name is copied to the argument field. Click on the `Lookup ()' button to find its definition.

As a shorter alternative, you can simply press mouse button 3 on the function name and select the `Lookup' item from the source 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.

  Textual Search
If the item you wish to search is visible in the source text, click with mouse button 1 on it. The identifier is copied to the argument field. Click on the `Find>> ()' button to find following occurrences and on the `Find<< ()' button to find previous occurrences.

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 `Source | Find Words Only' option.

  Looking up Previous Locations
Use the `Back' and `Forward' buttons to lookup previous or next locations. The location found is underlined.

BREAKPOINTS
Using the source window, you can make the program stop at certain breakpoints and trace its execution.

  Setting Breakpoints by Location
If the source line is visible, click with mouse button 1 on the left of the source line and then on the `Break at ()' button.

As an alternative, you can simply press mouse button 3 on the left of the source line and select the `Set Breakpoint' item from the line popup menu.

As another alternative, you can enter the line number in the argument field (indicated by `():') and click on the `Break at ()' button.

As yet another alternative, you can select `Source | Edit Breakpoints'. 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. The XDB `b' command works as well.

(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 users prefer the command line interface.)

Breakpoints are indicated by a plain stop sign, or as `#n#', where n is the breakpoint number.

  Setting Breakpoints by Name
If the function name is visible, click with mouse button 1 on the function name. The function name is copied to the argument field. Click on the `Break at ()' button to set a breakpoint there.

As a shorter alternative, you can simply press mouse button 3 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 at ()' button.

As yet another alternative, you can click on `New' from the Breakpoint editor (invoked through `Ssource | Edit Breakpoints') 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. The XDB `b' command works as well.

  Disabling Breakpoints
Note: Some DBX variants do not support breakpoint disabling.

To temporarily disable a breakpoint, press mouse button 3 on the breakpoint name and select the `Disable Breakpoint' item from the breakpoint popup menu. To enable it again, select `Enable Breakpoint'.

As an alternative, you can select the breakpoint and click on `Disable' or `Enable' in the Breakpoint editor (invoked through `Source | Edit Breakpoints'.

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.

The `Disable Breakpoint' item is also accessible via the `Clear at ()' button. Just press and hold mouse button 1 on the button to get a popup menu.

  Temporary Breakpoints
A temporary breakpoint is immediately deleted as soon as it is reached. To set a temporary breakpoint, press mouse button 3 on the left of the source line and select the `Set Temporary Breakpoint' item from the popup menu.

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 left of the source line 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 and XDB, execution stops when the temporary breakpoint is reached.

The `Set Temporary Breakpoint' and `Continue Until Here' items are also accessible via the `Break at ()' button. Just press and hold mouse button 1 on the button to get a popup menu.

  Deleting Breakpoints
If the breakpoint is visible, click with mouse button 1 on the breakpoint. The breakpoint location is copied to the argument field. Click on the `Clear at ()' button to delete all breakpoints there.

If the function name is visible, click with mouse button 1 on the function name. The function name is copied to the argument field. Click on the `Clear at ()' button to set a breakpoint there.

As a shorter alternative, you can simply press mouse button 3 on the breakpoint and select the `Delete Breakpoint' item from the popup menu.

As yet another alternative, you can select the breakpoint and click on `Delete' in the Breakpoint editor (invoked through `Source | Edit Breakpoints').

Finally, you can use the GDB `clear' and `delete' commands. Type `help clear' or `help delete' at the `(gdb)' prompt for details.

  Moving Breakpoints
To move a breakpoint to a different location, press mouse button 1 on the stop sign and drag it to the desired location. This is equivalent to deleting the breakpoint at the old location and setting a breakpoint at the new location. The new breakpoint inherits all properties of the old breakpoint, except the breakpoint number.

Note: Dragging breakpoints is not possible when glyphs are disabled. Delete and set breakpoints instead.

  Finding Breakpoints
If you wish to lookup a specific breakpoint, select `Source | Edit Breakpoints | Lookup'. After selecting a breakpoint from the list and clicking the `Lookup' button, the breakpoint location is displayed.

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.

  Breakpoint Conditions
Using the Breakpoint Editor (invoked through `Source | Edit Breakpoints'), you can specify breakpoint conditions. Reaching the breakpoint stops the program only if the associated condition is met—that is, if the condition expression evaluates to a non-zero value.

To set a breakpoint condition, select the appropriate breakpoint in the Breakpoint Editor and click on the `Condition' button. You can then enter (or change) the condition in a special dialog.

As a faster alternative, you can also press mouse button 3 on the breakpoint in the source code and select the `Set Condition' item from the popup menu.

  Breakpoint Ignore Counts
Using the Breakpoint Editor (invoked through `Source | Edit Breakpoints'), you can specify ignore counts. If an ignore count is set, each crossing of the breakpoint decrements the ignore count. The program stops only if the ignore count is zero.

To set a breakpoint ignore count, select the appropriate breakpoint in the Breakpoint Editor and click on the `Ignore Count' button. You can then enter (or change) the ignore count in a special dialog.

As a faster alternative, you can also press mouse button 3 on the breakpoint in the source code and select the `Set Ignore Count' item from the popup menu.

  More Breakpoint Features
More breakpoint features can be invoked through the debugger console. Enter `help breakpoints' at the `(gdb)' prompt.

RUNNING THE PROGRAM

  Using the Command Tool
All functionality you need for running and stopping the debugged program can be found on the command tool.

The command tool is a small window containing the most frequently used commands. It can be moved around on top of the DDD windows, but it can also be placed besides them. Whenever you save DDD state, DDD also saves the distance between command tool and source window, such that you can select your own individual command tool placement. In case you want to move the command tool to its saved position, use `View | Command Tool'.

By default, the command tool sticks to the DDD source window: Whenever you move the DDD source window, the command tool follows such that the distance between source window and command tool remains the same. By default, the command tool also is auto-raised, such that it stays on top of other DDD windows.

  Starting Program Execution
To start execution of the debugged program, select `Program | Run'. You will then be prompted for the arguments to give to your program. You can either select from a list of previously used arguments or enter own arguments in the text field. Afterwards, press the `OK' button to start execution with the selected arguments.

To run your program again, with the same arguments, select `Program | Run Again' or press the `Run' button on the command tool. You may also enter `run', followed by arguments at the debugger prompt instead.

By default, input and output of the debugged program go to the debugger console. As an alternative, DDD can also invoke an execution window, where the program terminal input and output is shown. See `Program | Run in Execution Window' for details.

  Attaching to a Running Process
If the debugged program is already running in some process, you can attach to this process (instead of starting a new one with `Run'). Select `File | Attach to Process' to choose from a list of processes. Afterwards, press the `Attach' button to attach to the specified process.

The first thing DDD does after arranging to debug the specified process is to stop it. You can examine and modify an attached process with all the DDD commands that are ordinarily available when you start processes with `Run'. You can insert breakpoints; you can step and continue; you can modify storage. If you would rather the process continue running, you may use `Continue' after attaching DDD to the process.

When using `Attach to Process', you should first use `Open Program' to specify the program running in the process and load its symbol table.

When you have finished debugging the attached process, you can use the `File | Detach Process' to release it from DDD control. Detaching the process continues its execution. After `Detach Process', that process and DDD become completely independent once more, and you are ready to attach another process or start one with `Run'.

You can customize the list of processes shown. See the `psCommand' resource for details.

  Stopping the Program
The program stops as soon as a breakpoint is reached. The current execution position is highlighted by an arrow.

You can interrupt a running program any time by clicking the `Interrupt' button or typing Ctrl+C in a DDD window.

  Resuming Execution
To resume execution, at the address where your program last stopped, click on the `Continue` button. Any breakpoints set at that address are bypassed.

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 the `Temporary Breakpoints' section, above, for a discussion.

  Altering the Execution Position
To resume execution at a different location, press mouse button 1 on the arrow and drag it to a different location. The most common occasion to use this feature is to back up—perhaps with more breakpoints set-over a portion of a program that has already executed, in order to examine its execution in more detail.

Moving the execution position does not change the current stack frame, or the stack pointer, or the contents of any memory location or any register other than the program counter.

Some inferior debuggers (notably GDB) allow you to set the new execution position into a different function from the one currently executing. This may lead to bizarre results if the two functions expect different patterns of arguments or of local variables. For this reason, moving the execution position requests confirmation if the specified line is not in the function currently executing.

After moving the execution position, click on the `Continue' button to resume execution.

Note: Dragging the execution position is not possible when glyphs are disabled. Use `Set Execution Position' from the breakpoint popup menu instead to set the execution position to the current location. This item is also accessible by pressing and holding the `Break at ()/Clear at ()' button.

  Examining the Stack
When your program has stopped, the first thing you need to know is where it stopped and how it got there.

DDD provides a backtrace window showing a summary of how your program got where it is. To enable the backtrace window, select `Status | Backtrace'.

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 directly type the `up' and `down' commands at the debugger prompt. Typing Ctrl+Up and Ctrl+Down, respectively, will also move you through the stack.

  Examining Threads
Note: Thread support is available with GDB only.

In some operating systems, a single program may have more than one thread of execution. The precise semantics of threads differ from one operating system to another, but in general the threads of a single program are akin to multiple processes—except that they share one address space (that is, they can all examine and modify the same variables). On the other hand, each thread has its own registers and execution stack, and perhaps private memory.

For debugging purposes, DDD lets you display the list of threads currently active in your program and lets you select the current thread—the thread which is the focus of debugging. DDD shows all program information from the perspective of the current thread.

To view all currently active threads in your program, select `Status | Threads'. The current thread is highlighted. Select any thread to make it the current thread.

For more information on threads, see the section `Debugging programs with multiple threads' in the GDB documentation.

EXAMINING DATA

DDD provides three means to examine data.

Value Hints
    The quickest way to examine variables is to move the pointer on an occurrence in the source text. The value is displayed in the source line; after a second, a popup window shows the variable value. This is useful for quick examination of several simple variables.

Printing Values
    If you want to reuse variable values at a later time, you can print the value in the debugger console. This allows for displaying and examining larger data structures.

Displaying Values
    If you want to examine complex data structures, you can display them graphically in the data display. Displays remain effective until you delete them; they are updated each time the program stops. This is useful for large dynamic structures.

  Displaying Simple Values
To display the value of a simple variable, move the mouse pointer on its name. After a second, a small window (called value tip) pops up showing the value of the variable pointed at. The window disappears as soon as you move the mouse pointer away from the variable. The value is also shown in the status line.

The variable value can also be printed in the debugger console, making it available for further operations. To print a variable value, select the desired variable by clicking mouse button 1 on its name. The variable name is copied to the argument field. By clicking the `Print ()' button, a new display is created in the data window.

As a shorter alternative, you can simply press mouse button 3 on the variable name and select the `Print' item from the popup menu.

  Displaying Complex Values
To explore complex data structures, you can use the graphical data display in the data window. The data window holds displays showing names and the values of variables. The display is updated each time the program stops.

To create a new display, select the desired variable by clicking mouse button 1 on its name. The variable name is copied to the argument field. By clicking the `Display ()' button, a new display is created in the data window.

As a shorter alternative, you can simply press mouse button 3 on the variable name and select the `Display' item from the popup menu.

As another alternative, you may also enter the expression to be displayed in the argument field and press the `Display ()' button.

If the data window is visible, you may click on the `New Display' button. Enter the expression to be displayed in the resulting prompt dialog.

Finally, you may also enter

  graph display expr [at (x, y)] [dependent on display]

at the debugger prompt. If the suffix `at (x, y)' is specified, the new data display is created at the position (x, y); otherwise, a default position is assigned. If the suffix `dependent on display' is given, an edge from the display numbered or named display to the new display is created; otherwise, no edge is created.

  Selecting Displays
Each display in the data window has a title bar containing the display number and the displayed expression (the display name). Below the title, the display value is shown.

You can select individual displays by clicking on them with mouse button 1. The resulting expression is shown in the argument field, below.

You can extend an existing selection by pressing the Shift key while selecting. You can also toggle an existing selection by pressing the Shift key while selecting already selected displays.

Single displays may also be selected by using the arrow keys.

  Selecting Multiple Displays
Multiple displays are selected by pressing and holding mouse button 1 somewhere on the window background. By moving the pointer while holding the button, a selection rectangle is shown; all displays fitting in the rectangle are selected when mouse button 1 is released.

If the Shift key is pressed while selecting, the existing selection is extended.

By double-clicking on a display title, the display itself and all connected displays are automatically selected.

  Selecting Display Parts
If a display is composed from several values (that is, a C/C++ class, struct, union, or array; or a Pascal/Modula RECORD or ARRAY), you can select individual parts by clicking on their names or values. The resulting expression is shown in the argument field, below.

Selection of multiple display parts is not supported.

  Showing and Hiding Values
Aggregate Values can be shown expanded, that is, displaying all details, or hidden, that is, displayed as `{...}'.

To show details about an aggregate, select the aggregate by clicking mouse button 1 on its name or value and click on the `Show ()' button. Details are shown for the aggregate itself as well as for all contained sub-aggregates.

To hide details about an aggregate, select the aggregate by clicking mouse button 1 on its name or value and click on the `Hide ()' button.

When pressing and holding mouse button 1 on the `Show ()/Hide ()' button, a menu pops up with even more alternatives:

Show More ()
    Shows details of all aggregates currently hidden, but not of their sub-aggregates. You can invoke this item several times in a row to reveal more and more details of the selected aggregate.

Show Just ()
    Shows details of the selected aggregate, but hides all sub-aggregates.

Show All ()
    Shows all details of the selected aggregate and of its sub-aggregates. This item is equivalent to the `Show ()' button.

Hide ()
    Hide all details of the selected aggregate. This item is equivalent to the `Hide ()' button.

As a faster alternative, you can also press mouse button 3 on the aggregate and select the appropriate menu item.

As an even faster alternative, you can also double-click mouse button 1 on a value. If some part of the value is hidden, more details will be shown; if the entire value is shown, double-clicking will hide the value instead. This way, you can double-click on a value until you get the right amount of details.

If all details of a display are hidden, the display is considered disabled. Displays can be disabled or enabled via the DDD commands

  graph disable display displays...

and

  graph enable display displays...

at the debugger prompt. displays... is a space-separated list of display numbers to disable or enable.

  Rotating Arrays
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 mouse button 3 on the array and select the `Rotate' menu item.

  Displaying Dependent Values
Dependent displays are created from an existing display. The dependency is indicated by arrows leading from the originating display to the dependent display.

To create a dependent display, select the originating display or display part and click on the `New Display' button. A prompt dialog appears where you can enter a new expression expr in the argument field. By clicking on `Display', the new display showing expr is created.

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.

By default, DDD does not recognize shared data structures (i.e. a data object referenced by multiple other data objects). See `Examining Shared Data Structures', below, for details on how to examine such structures.

  Display Shortcuts
Each time you enter a new display via the prompt dialog, you can insert it in the `New Display' Menu by activating the `Include in `New Display' Menu' toggle. The `New Display' menu allows you to repeat the most recent display actions over and over again. It can be accessed in three ways:

•   by pressing and holding the `New Display' button, or

•   by pressing mouse button 3 on some display and selecting `New Display', or

•   by pressing Shift and mouse button 3 on some display.

As an example, assume you have selected a display named `foo' and used `New Display' to cast the display `foo' to a new display `(char *)foo'. If the `Include in `New Display' Menu' toggle was activated, you can now simply choose the `Display (char *)()' operation from the `New Display' menu to cast any selected display display to `(char *)display'. This shortcut can save you a lot of time when examinating complex data structures.

You can edit the contents of the `New Display' menu by selecting its `Edit Menu' item. This pops up the Shortcut Editor containing all shortcut expressions, which you can edit at leisure. Each line contains the expression for exactly one menu item. Clicking on `Apply' re-creates the `New Display' menu from the text. If the text is empty, the `New Display' menu will be empty, too.

DDD also allows you to specify individual labels for user-defined buttons. You can write such a label after the expression, separated by `//'. This feature is used in the default contents of the `New Display' menu, where each of the base conversions has a label:

    /d ()    // Convert to Dec
    /x ()    // Convert to Hex
    /o ()    // Convert to Oct

Feel free to add other conversions here. DDD supports up to 20 `New Display' menu items.

The item `Other' in the `New Display' menu is equivalent to pressing the `New Display' button—that is, you can enter a new expression to be displayed.

  Dereferencing Pointers
There are special shortcuts for creating dependent displays showing the value of a dereferenced pointer. This allows for rapid examination of pointer-based data structures.

To dereference a pointer, select the originating pointer value or name and click on the `Display *()' button. A new display showing the dereferenced pointer value is created.

As a faster alternative, you can also press mouse button 3 on the originating pointer value or name and select the `Display *' menu item.

As an even faster alternative, you can also double-click mouse button 1 on the originating pointer value or name.

The `Display *()' function is also accessible by pressing and holding the `Display ()' button.

  Displaying Local Variables
You can display all local variables at once by choosing `Data | Display Local Variables'. When you using DBX or XDB, this displays all local variables, including the arguments of the current function. When you are using GDB, function arguments are contained in a separate display, activated by `Display Arguments'.

The display showing the local variables can be manipulated just like any other data display. Individual variables can be selected and dereferenced.

  Displaying Program Status
Besides local variables, you can create a display from the output of an arbitrary debugger command. By entering

  graph display `command`

the output of command is turned into a status display updated each time the program stops. For instance, by entering

  graph display `where`

a status display named `Where' is created that shows the current backtrace.

If you are using GDB, DDD provides a panel from which you can choose useful status displays. Select `Data | Status Displays' and pick your choice from the list.

Note that status displays are quite time-consuming, so you should delete them as soon as you don't need them any more.

  Displaying Multiple Array Items
When debugging C or C++ programs, one often has to deal with pointers to arrays of dynamically determined size. Both DDD and GDB provide special support for such dynamic arrays.

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]'.

Using GDB as inferior debugger, you can use 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.

  Altering Variable Values
Using the `Set ()' button or the `Set Value' menu item in the data popup menu, you can alter the value of the selected variable, to resume execution with the changed value. In a dialog, you can modify the variable value at will; clicking the `OK' or `Apply' button commits your change.

Note that most inferior debuggers have no support for changing entire structures; you must change each primitive structure member separately.

  Deleting Displays
To delete a single display, select it and click on the `Delete ()' button. As an alternative, you can also press mouse button 3 on the display and select the `Delete Display' item.

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 via `Data | Edit Displays'). Select any number of display items in the usual way and delete them by pressing `Delete'.

As an alternative, you can also type

  graph undisplay displays...

at the debugger prompt, where displays... is a space-separated list of display numbers to delete.

  Examining Shared Data Structures
By default, DDD does not recognize shared data structures—that is, a data object referenced by multiple other data objects. For instance, if two pointers p1 and p2 point at the same data object d, the data displays d, *p1, and *p2 will be separate, although they denote the same object.

DDD provides a special mode which makes it detect these situations. DDD recognizes if two or more data displays are stored at the same physical address, and if this is so, merges all these aliases into one single data display, the original data display. This mode is called Alias Detection; it is enabled via the `Data | Detect Aliases'.

When alias detection is enabled, DDD inquires the memory location (the address) of each data display after each program step. If two displays have the same address, they are merged into one. More specifically, only the one which has least recently changed remains (the original data display); all other aliases are suppressed, i.e. completely hidden. The edges leading to the aliases are replaced by edges leading to the original data display.

An edge created by alias detection is somewhat special: rather than connecting two displays directly, it goes through an edge hint, describing an arc connecting the two displays and the edge hint.

Each edge hint is a placeholder for a suppressed alias; selecting an edge hint is equivalent to selecting the alias. This way, you can easily delete display aliases by simply selecting the edge hint and clicking on `Delete ()'.

To access suppressed display aliases, you can also use the Display Editor. Suppressed displays are listed in the Display Editor as aliases of the original data display. Via the Display Editor, you can select, change, and delete suppressed displays.

Suppressed displays become visible again as soon as

•   alias detection is disabled,

•   their address changes such that they are no more aliases, or

•   the original data display is deleted, such that the least recently changed alias becomes the new original data display.

Please note the following caveats with alias detection:

•   Alias detection requires that the current programming language provides a means to determine the address of an arbitrary data object. Currently, only C and C++ are supported.

•   Some inferior debuggers (for instance, SunOS DBX) produce incorrect output for address expressions. Given a pointer p, you may verify the correct function of your inferior debugger by comparing the values of p and &p (unless p actually points to itself). You can also examine the data display addresses, as shown in the Display Editor.

•   Alias detection slows down DDD considerably, which is why it is disabled by default. You may consider to enable it only at need—for instance, while examining some complex data structure—and disable it while examining control flow (i.e., stepping through your program). DDD will automatically restore edges and data displays when switching modes.

  Refreshing the Data Window
The data window refreshes itself automatically each time the program stops. Values that have changed are highlighted.

However, there are some situations where you should refresh the data window explicitly. The data window should be refreshed whenever:

•   you disabled, enabled or deleted displays items at the debugger prompt,

•   the display stays unchanged although all items should be deleted (e.g. because you chose another file to debug),

•   you think it could be useful.

You can refresh the data window by selecting `Data | Refresh Displays'.

As an alternative, you can press mouse button 3 on the background of the data window and select the `Refresh Display' item.

Typing

  graph refresh

at the debugger prompt has the same effect.

GRAPH EDITING
The DDD data window offers some basic functionality to manipulate the display graph.

  Moving Displays Around
From time to time, you may wish to move displays at another place in the data window. You can move a single display by pressing and holding mouse button 1 on the display title. Moving the pointer while holding the button causes all selected displays to move along with the pointer.

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.

Edge hints can be selected and moved around like other displays. If an arc goes through the edge hint, you can change the shape of the arc by moving the edge hint around.

  Aligning Displays
You can align all displays on the nearest grid position by selecting `Data | Align on Grid'. This is useful for keeping edges horizontal or vertical.

You can enforce alignment by selecting `Edit | Preferences | Data | Auto-align displays on nearest grid point'. If this feature is enabled, displays can be moved on grid positions only.

  Layouting the Display Graph
You can layout the entire graph as a tree by selecting `Data | Layout Graph'.

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. Edge hints can be moved around like arbitrary displays.

To enable a more compact layout, you can set the `Edit | Preferences | Data | Use 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.

You can enforce layout by setting `Edit | Preferences | Data | Re-layout graph automatically'. If automatic layout is enabled, the graph is layouted after each change.

  Rotating the Display Graph
You can rotate the entire graph clockwise by 90 degrees by selecting `Data | Rotate Graph'.

If the graph was previously layouted, you may need to layout it again. Subsequent layouts will respect the direction of the last rotation.

  Printing the Display Graph
DDD allows for printing the graph picture on PostScript printers or into files. This is useful for documenting program states.

To print the graph on a PostScript printer, select `File | Print Graph'. Enter the printing command in the `Print Command' field. Click on the `OK' or the `Apply' button to start printing.

To re-print the display graph using the previous settings, select the `File | Print Again'.

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:

•   PostScript - suitable for enclosing it in another document;

•   FIG - suitable for editing, using the XFIG graphic editor, or for conversion into other formats (among others IBMGL, LATEX, PIC), using the TRANSFIG or FIG2DEV package.

Note: Arcs cannot be printed (yet). Arcs joining two displays are printed using straight lines; arcs joining a display with itself are suppressed.

MACHINE-LEVEL DEBUGGING
Note: Machine-level support is available with GDB only.

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.

  Examining Machine Code
To enable machine-level support, select `Source | Display Machine Code'. With machine code enabled, an additional machine code window shows up, displaying the machine code of the current function. By moving the sash at the right of the separating line between source and machine code, you can resize the source and machine code windows.

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 at ()' or `Clear at ()' 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.

The `maxDisassemble' resource controls how much is to be disassembled. If `maxDisassemble' is set to 1024 (default) and the current function is larger than 1024 bytes, DDD only disassembles the first 1024 bytes below the current location. You can set the `maxDisassemble' resource to a larger value if you prefer to have a larger machine code view.

If source code is not available, only the machine code window is updated.

  Execution
All execution facilities available in the source code window are available in the machine code window as well. Two special facilities are convenient for machine-level debugging:

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.

  Registers
DDD provides a register window showing the machine register values after each program stop. To enable the register window, select `Status | Registers'.

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.

EDITING SOURCE CODE
In DDD itself, you cannot change the source file currently displayed. DDD allows you to invoke a text editor instead. To invoke a text editor for the current source file, select the `Edit' button or `Source | Edit Source'.

The editor command is specified in the `editCommand' resource. By default, DDD tries to invoke the first available editor from the following list:

•   The editor specified in the `XEDITOR' environment variable;

•   The `gnuclient' program, invoking a separate window from a running Emacs editor;

•   The `emacsclient' program, invoking a separate window from a running Emacs editor;

•   A `xterm' terminal emulator running the editor specified in the `EDITOR' environment variable;

•   A `xterm' terminal emulator running the `vi' editor.

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 via `Source | Reload Source'. 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.

PERSISTENT SESSIONS
Note: Session support is available with GDB running on the local machine only.

If you want to interrupt your current DDD session, you can save its entire DDD state in a file and restore it later.

  Saving Sessions
To save a session, select `File | Save Session As'. You will be asked for

•   a symbolic session name session and

•   whether to include a core dump of the debugged program. Including a core dump is necessary for restoring data displays.

After clicking on `Save', the session is saved in `$HOME/.ddd/sessions/session'.

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 `$HOME/.ddd/sessions/session/init' instead of `$HOME/.ddd/init'; see `Saving Options', below, for details.

•   The DDD command history will be saved in `$HOME/.ddd/sessions/session/history' instead of `$HOME/.ddd/history'; see `Entering Commands', above, for details.

To make the current session inactive, open the default session named `[None]'; see below for details on opening sessions.

If a core file is to be included in the session, DDD uses the `gcore' command specified in `Edit | Preferences | Helpers | Get Core File'. Since `gcore' automatically resumes debuggee execution, and since some time may elapse until DDD can stop the debuggee again, the current execution position may change after saving state. If you do not want this, leave the entry in `Edit | Preferences | Helpers | Get Core File' empty.

If no `gcore' command is specified, DDD must kill the debugged program in order to get a core file. This means that you cannot resume program execution after saving a session.

  Opening 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, open the default session and save options; see `Saving Options' below 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 environment (open files, resources, etc.) will be lost. However, you can restart the program, re-using the restored breakpoints and data displays.

  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 cannot be deleted.

  Starting DDD with a Session
To start-up DDD with a given session named session instead of the default session, use

  ddd --session session

There is also a shortcut that opens the session session and also 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.

QUITTING DDD
To exit DDD, select `File | Exit'. You may also type the `quit' command at the debugger prompt. GDB and XDB also accept the `q' command or an end-of-file character (usually Ctrl+D).

An interrupt (Ctrl+C 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 QUIT signal to the inferior debugger. Use this in emergencies only; the inferior debugger may be left inconsistent after a QUIT 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 pressing 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.

REMOTE DEBUGGING
It is possible to have the inferior debugger run on a remote UNIX host. This is useful when the remote host has a slow network connection or when DDD is available on the local host only.

Furthermore, the inferior debugger may support debugging a program on a remote host. This is useful when the inferior debugger is not available on the remote host—for instance, because the remote system does not have a general purpose operating system powerful enough to run a full-featured debugger.

  Using DDD with a Remote 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 don't 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-shell-commands' option. This prints the shell commands issued by DDD on standard error.

  Using DDD with 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.

The section `Remote debugging' in the GDB documentation contains all the 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 'file' command.

•   Attach to the remote `gdbserver' using the '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.

ROOT DEBUGGING
Sometimes, you may require to debug programs with root privileges, but without actually logging in as root. This is usually done by installing the debugger setuid root, that is, having the debugger run with root privileges. For security reasons, you cannot install DDD as a setuid program; DDD invokes shell commands and even shell scripts, such that all known problems of setuid shell scripts apply. Instead, you should invoke DDD such that a setuid copy of the inferior debugger is used.

Here is an example. Have a setuid root copy of GDB installed as `rootgdb'. Then invoke

  ddd --debugger rootgdb

to debug programs with root privileges.

Since a program like `rootgdb' grants root privileges to any invoking user, you should give it very limited access.

INTEGRATING DDD
You can run DDD as an inferior debugger in other debugger front-ends, combining their special abilities with those of DDD.

  General Information
To have DDD run as an inferior debugger in other front-ends, set up your debugger front-end such that `ddd --tty' is invoked instead of the inferior debugger. When DDD is invoked using the `--tty' option, it enables its TTY interface, taking additional debugger commands from standard input and forwarding debugger output to standard output, just as if the inferior debugger had been invoked directly. All remaining DDD functionality stays unchanged.

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 detects an EOF condition on its standard input. Also, do not try to run DDD with DDD as inferior debugger.

Using DDD in TTY mode automatically disables some DDD windows, because it is assumed that their facilities are provided by the remote program:

•   If DDD is invoked with the `--tty' option, the debugger console is initially disabled, as its facilities are supposed to be provided by the integrating front-end.

•   If DDD is invoked with the `-fullname' option, the debugger console and the source window are initially disabled, as their facilities are supposed to be provided by the integrating front-end.

In case of need, you can use the `View' menu to re-enable these windows.

  Using DDD with GNU Emacs
Use `M-x gdb' or `M-x dbx' to start a debugging session. At the prompt, enter `ddd --tty', followed by `--dbx' or `--gdb', if required, and the name of the program to be debugged. Proceed as usual.

  Using DDD with XEmacs
Set the variable gdb-command-name to "ddd", by inserting the following line in your $HOME/.emacs file or evaluating it by pressing ESC : (ESC ESC for XEmacs 19.13 and earlier):

  (setq gdb-command-name "ddd")

Use `M-x gdb' or `M-x gdbsrc' to start a debugging session. Proceed as usual.

  Using DDD with XXGDB
Invoke xxgdb as

  xxgdb -db_name ddd -db_prompt '(gdb) '

USER-DEFINED COMMANDS
If your debugger allows you to define own command sequences, you can also use these user-defined commands within DDD; just enter them at the debugger prompt. However, you may encounter some problems:

•   In contrast to the well-documented commands of the inferior debugger, DDD does not know what your specific command does. This may lead to inconsistencies between DDD and the inferior debugger. For instance, if your own command `bp' sets a breakpoint, DDD may not display it immediately, because DDD does not know that `bp' changes the breakpoint state.

•   You cannot use DDD graph commands within user-defined commands. This is only natural, because user-defined commands are interpreted by the inferior debugger, which does not know about DDD commands.

As a solution, DDD provides a simple facility called auto-commands. If DDD receives any output from the inferior debugger in the form `ddd: command', it will interpret command as if it had been entered at the debugger prompt.

Suppose you want to define a GDB command `dispfoo' that creates a data display containing the variable foo. All dispfoo has to do is to issue a string

  ddd: graph display foo

In GDB, this can be achieved using the echo command. In your $HOME/.gdbinit file, insert the lines

  define dispfoo
    echo ddd: graph display foo
  end

Entering dispfoo will now have the same effect as entering graph display foo at the debugger prompt.

Unfortunately, auto-commands also raise a security problem, since arbitrary commands can be executed. Just imagine some malicuous program issuing a string like `ddd: shell rm -fr $HOME' when being debugged! Consequently, auto-commands are disabled by default and must be enabled explicitly.

To enable auto-commands, write in your `$HOME/.ddd/init' file:

  Ddd*autoCommands: on

The default prefix of auto-commands is `ddd: '. You are encouraged to change this value in your `.ddd/init' file. To use a prefix of, say, `magic123: ', write:

  Ddd*autoCommandPrefix: magic123:\

Leave a space after the final `\'. Be sure to enable auto-commands only if you have defined own commands; be sure to set up an individual auto-command prefix to avoid security problems.

PREFERENCES
You can set up your personal DDD preferences by using the `Edit | Preferences' menu from the menu bar. These preferences affect your running DDD process only, unless you save these preferences for a later DDD invocation. Frequently used preferences can also be found in the individual menus.

  Frequently Used Preferences
If you want to run your debugged process in a separate terminal emulator window, set `Program | Run in 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.

By default, DDD finds only complete words. This is convenient for clicking on an identifier in the source text and search for exactly this identifier. If you want to find all occurrences, including word parts, unset `Source | Find Words Only'.

By default, DDD find is case-sensitive. This is convenient for case-sensitive programming languages. If you want to find all occurrences, regardless of case, unset `Source | Find Case Sensitive'.

If you wish to display machine code of selected funtions, set `Source | Display Machine Code'. This makes DDD run a little slower, so it is disabled by default.

Through `Edit | Preferences', you can set up more DDD preferences, which are dicussed here.

  General Preferences

By default, when you move the pointer over a button, DDD gives a hint on the button's meaning in a small window. Experienced users may find these button tips disturbing; this is why you can disable them by unsetting the `Automatic display of button hints as popup tips' option.

The button hints are also displayed in the status line. Disabling hints in status line (by unsetting the `Automatic display of button hints in the status line' option) and disabling button tips as well makes DDD run slightly faster.

By default, when you move the pointer over a variable in the source code, DDD displays the variable value in a small window. Users may find these value tips disturbing; this is why you can disable them by unsetting the `Automatic display of variable values as popup tips' option.

The variable values are also displayed in the status line. Disabling variable values in status line (by unsetting the `Automatic display of variable values in the status line' option) and disabling value tips as well will make DDD run slightly faster.

If you want to use TAB key completion in all text windows, set the `TAB key completes in all windows' option. This is useful if you have pointer-driven keyboard focus (see below) and no special usage for the TAB key. Otherwise, the TAB key completes in the debugger console only.

If you frequently switch between DDD and other multi-window applications, you may like to set the `Iconify all windows at once' option. This way, all DDD windows are iconified and deiconified as a group.

If you want to keep DDD off your desktop during a longer computation, you may like to set the `Uniconify when ready' option. This way, you can iconify DDD while it is busy on a command (e.g. running a program); DDD will automatically pop up again after becoming ready (e.g. after the debugged program has stopped at a breakpoint).

If you are bothered by X warnings, you can suppress them by setting the `Suppress X warnings' option.

When debugging a modal X application, DDD may interrupt it while it has grabbed the pointer, making further interaction impossible. If the `Ungrab mouse pointer when interrupting modal X application' option is set, DDD will check after each interaction whether the pointer is grabbed. If this is so, DDD will instruct the debugged program to ungrab the mouse pointer such that you can continue to use your display.

The `Reset' button restores the most recently saved preferences.

  Source Preferences

In the source text, the current execution position and breakpoints are indicated by symbols (“glyphs”). As an alternative, DDD can also indicate these positions using text characters. If you wish to disable glyphs, unset the `Use Glyphs' option. This also makes DDD run slightly faster, especially when scrolling.

In contrast to previous releases, DDD 2.2 and later do not display line numbers in the source code. If you want to see each source line prefixed with its respective number, set the `Display source line numbers' option.

By default, DDD finds only complete words. This is convenient for clicking on an identifier in the source text and search for exactly this identifier. If you want to find all occurrences, including word parts, unset `Find words only'.

By default, DDD find is case-sensitive. This is convenient for case-sensitive programming languages. If you want to find all occurrences, regardless of case, unset `Find case sensitive'.

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 source files' 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.

Some DBX and XDB variants do not properly handle paths in source file specifications. If you want the inferior debugger to refer to source locations by source base names only, unset the `Refer to sources by full path name' option.

If your source code uses a tab width different from 8 (the default), you can set an alternate width using the `Tab width' slider.

The `Reset' button restores the most recently saved preferences.

  Data Preferences

If you want DDD to detect aliases, set the `Detect Aliases' option. Note that alias detection makes DDD run slower. See `Examining Shared Data Structures', above, for details on alias detection.

By default, DDD displays two-dimensional arrays as tables, aligning the array elements in rows and columns. If you prefer viewing two-dimensional arrays as nested one-dimensional arrays, you can disable the `Display two-dimensional arrays as tables' option.

To facilitate alignment of data displays, you can set the `Auto-align displays' option. If auto-alignment 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 `Re-layout graph automatically' option. If automatic layout is enabled, the graph is layouted after each change.

In the `Grid Size' scale, you can change the spacing of grid points. A spacing of 0 disables the grid. Default is 16.

The `Reset' button restores the most recently saved preferences.

  Startup Preferences

By default, DDD uses one single window for commands, source, and data. To have separate windows for source, data, and debugger console, set the `Windows' option to `Separate Windows'. This change takes only effect after you have saved options and restarted DDD. See also the `--attach-windows' and `--separate-windows' options, below.

DDD can display the status line at the bottom (`at bottom') or at the top (`at top') of the source. This change takes only effect after you have saved options and restarted DDD. Pick your choice.

DDD can locate the tool buttons in the command tool (`in command tool') or in another line of buttons below the program source (`in source window'). Pick your choice.

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-editor' and `--scrolled-graph-editor' 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', `--dbx', and `--xdb' options, below.

If you want the DDD logo shown upon startup, you can select between different versions. The `color' version is the nicest, but requires several color cells. The `grey' version requires some grey color cells, which are also used by DDD. The `grey4' version needs no additional color cells. Selecting `none' disables the logo completely.

The `Reset' button restores the most recently saved preferences.

  Helpers
DDD relies on some external applications (called helpers) for specific tasks. Through the `Helpers' panel, you can choose and customize these applications.

In `Edit Sources', you can select an X editor to be invoked via the DDD `Edit' button. `@FILE@' is replaced by the current file name; `@LINE@' is replaced by the current line. Typical values include `xedit @FILE@' or `gnuclient +@LINE@ @FILE@'. See also the `editCommand' resource, below.

In `Get Core File', you can enter a command to get a core file from a running process. `@FILE@' is replaced by the name of the target core file; `@PID@' is replaced by the process ID. A typical value is `gcore -o @FILE@ @PID@'. If you don't have an appropriate command, leave this value empty: DDD will then kill the debuggee in order to get a core file. See also the `getCoreCommand' resource, below.

`List Processes' is a command to get a list of processes, like `ps'. The output of this command is shown in the `File | Attach to Process' dialog. See also the `psCommand' resource, below.

In `Execution Window', you can enter a command to start a terminal emulator. To this command, DDD appends bourne shell commands to be executed within the execution window. A simple value is `xterm -e /bin/sh -c'. See also the `termCommand' resource, below.

`Uncompress' is the uncompression command used by DDD to uncompress the DDD license and manual pages. The uncompression command should be invoked such that it reads from standard input and writes to standard output. A typical value is `gunzip -c'. See also the `uncompressCommand' resource, below.

Finally, `Web Browser' is the command to invoke a WWW browser for the DDD WWW page. `@URL@' is replaced by the URL to be shown. A simple value is `netscape @URL@'. See also the `wwwCommand' resource, below.

  Defining Buttons
To facilitate interaction, you can add own command buttons to DDD. These buttons can be added below the debugger console (`Console Buttons'), the source window (`Source Buttons'), or the data window (`Data Buttons').

To define individual buttons, use the Button Editor, invoked via `Commands | Edit Buttons'. The button editor displays a text, where each line contains the command for exactly one button. Clicking on `Apply' creates the appropriate buttons from the text. If the text is empty (the default), no button is created.

As a simple example, assume you want to create a `print i' button. Invoke `Commands | Edit Buttons' and enter a line saying `print i' in the button editor. Then click on `Apply'. A button named `Print i' will now appear below the debugger console—try it! To remove the button, clear the `print i' line and press `Apply' again.

By default, DDD disables buttons whose commands are not supported by the inferior debugger. To enable such buttons, unset the `Enable supported buttons only' toggle in the button editor.

DDD also allows you to specify control sequences and special labels for user-defined buttons. See the examples in `User-defined Buttons' in the `RESOURCES' section, below.

  Saving Options
You can save the current option settings by selecting `Edit | Save Options'. Options are saved in a file named `.ddd/init' in your home directory. If a session session is active, options will be saved in `$HOME/.ddd/sessions/session/init' instead.

  Other Customizations
Other personal DDD resources can also be set in your `.ddd/init' file. See the `RESOURCES' section, below.

The inferior debugger can be customized via `Edit | Settings'. See the `DEBUGGER SETTINGS' section, below.

DEBUGGER SETTINGS
If you use GDB (or some DBX flavor) as inferior debugger, you can change its settings using `Edit | Settings'. Using the settings editor, you can determine whether C++ names are to be demangled, how many array elements are to print, and so on.

The capabilities of the settings editor depend on the capabilities of your inferior debugger—that is, your GDB or DBX version. Clicking on `?' gives an an explanation on the specific item; the GDB documentation gives more details.

Clicking on `Reset' restores the most recently saved settings.

Some debugger settings are insensitive and cannot be changed, because doing so would endanger DDD operation. See the `gdbInitCommands' and `dbxInitCommands' resources for details.

All debugger settings (except source and object paths) are saved with DDD options.

USING DDD WITH LESSTIF
DDD 2.1.1 and later include a number of hacks that make DDD run with LessTif, a free Motif clone, without loss of functionality. Since a DDD binary may be dynamically bound and used with either an OSF/Motif or LessTif library, these hacks can be enabled and disabled at run time.

Whether the hacks are included at run-time depends on the setting of the `lessTifVersion' resource. `lessTifVersion' indicates the LessTif version against which DDD is linked. For LessTif version x.y, its value is x multiplied by 1000 plus y—for instance, the value 88 stands for LessTif 0.88 and the value 1000 stands for LessTif 1.0. To specify the version number of the LessTif library at DDD invocation, you can also use the option `--lesstif-version version'.

The default value of the `lessTifVersion' resource is derived from the LessTif library DDD was compiled against (or 1000 when compiled against OSF/Motif). Hence, you normally don't need to worry about the value of this resource. However, if you use a dynamically linked DDD binary with a library other than the one DDD was compiled against, you must specify the version number of the library using this resource. (Unfortunately, DDD cannot detect this at run-time.)

Here are a few scenarios to illustrate this scheme:

•   Your DDD binary was compiled against OSF/Motif, but you use a LessTif 0.81 dynamic library instead. Invoke DDD with `--lesstif-version 81'.

•   Your DDD binary was compiled against LessTif, but you use a OSF/Motif dynamic library instead. Invoke DDD with `--lesstif-version 1000'.

•   Your DDD binary was compiled against LessTif 0.81, and you have upgraded to LessTif 0.90. Invoke DDD with `--lesstif-version 90'.

To find out the LessTif or OSF/Motif version DDD was compiled against, invoke DDD with the `--configuration' option.

In the DDD source, LessTif-specific hacks are controlled by the string `lesstif_version'.

RESOURCES
DDD understands all of the core X Toolkit resource names and classes. The following resources are specific to DDD.

  Setting DDD Fonts
This is the default font setting in DDD:

  Ddd*fontList: \
  -*-helvetica-bold-r-*-*-12-*-*-*-*-*-*-*=charset,\
  -*-helvetica-bold-r-*-*-10-*-*-*-*-*-*-*=small,\
  -*-lucidatypewriter-medium-r-*-*-12-*-*-*-*-*-*-*=tt,\
  -*-helvetica-bold-r-*-*-12-*-*-*-*-*-*-*=key,\
  -*-helvetica-medium-r-*-*-12-*-*-*-*-*-*-*=rm,\
  -*-helvetica-medium-o-*-*-12-*-*-*-*-*-*-*=sl,\
  -*-helvetica-bold-r-*-*-12-*-*-*-*-*-*-*=bf,\
  -*-helvetica-bold-o-*-*-12-*-*-*-*-*-*-*=bs,\
  -*-helvetica-bold-r-*-*-14-*-*-*-*-*-*-*=Logo,\
  -*-helvetica-bold-r-*-*-12-*-*-*-*-*-*-*=logo,\
  -*-symbol-*-*-*-12-*-*-*-*-*-*-*=symbol

The font names are used as follows:

charset
    The default font in buttons, menus, etc.

small
    The default font in a slightly smaller size.

tt  The fixed-width font (teletype) used in texts.

key The font used for describing key caps.

rm  Roman font. In help texts.

sl  Slanted font. In help texts.

bf  Bold face. In help texts.

bs  Slanted bold face. In help texts.

Logo
    The DDD logo font (uppercase letters).

logo
    The DDD logo font (lowercase letters).

symbol
    The symbol font. In help texts.

Here is an alternative, resolution-independent setting, which you may copy into your `$HOME/.ddd/init' file:

  Ddd*fontList: \
  -*-helvetica-bold-r-*-*-*-90-*-*-*-*-*-*=charset,\
  -*-helvetica-bold-r-*-*-*-80-*-*-*-*-*-*=small,\
  -*-lucidatypewriter-medium-r-*-*-*-90-*-*-*-*-*-*=tt,\
  -*-helvetica-bold-r-*-*-*-90-*-*-*-*-*-*=key,\
  -*-helvetica-medium-r-*-*-*-90-*-*-*-*-*-*=rm,\
  -*-helvetica-medium-o-*-*-*-90-*-*-*-*-*-*=sl,\
  -*-helvetica-bold-r-*-*-*-90-*-*-*-*-*-*=bf,\
  -*-helvetica-bold-o-*-*-*-90-*-*-*-*-*-*=bs,\
  -*-helvetica-bold-r-*-*-*-120-*-*-*-*-*-*=Logo,\
  -*-helvetica-bold-r-*-*-*-90-*-*-*-*-*-*=logo,\
  -*-symbol-*-*-*-*-90-*-*-*-*-*-*=symbol

The fonts in text fields are specified as follows:

  Ddd*XmTextField.FontList: \
  -*-lucidatypewriter-medium-r-*-*-12-*-*-*-*-*-*-*=charset
  Ddd*XmText.FontList: \
  -*-lucidatypewriter-medium-r-*-*-12-*-*-*-*-*-*-*=charset

And here is another resolution-independent alternative:

  Ddd*XmTextField.FontList: \
  -*-lucidatypewriter-medium-r-*-*-*-90-*-*-*-*-*-*=charset
  Ddd*XmText.FontList: \
  -*-lucidatypewriter-medium-r-*-*-*-90-*-*-*-*-*-*=charset

These are the fonts in the command tool:

  Ddd*tool_buttons.run.fontList: \
  -*-helvetica-bold-r-*-*-12-*-*-*-*-*-*-*=charset
  Ddd*tool_buttons.break.fontList: \
  -*-helvetica-bold-r-*-*-12-*-*-*-*-*-*-*=charset
  Ddd*tool_buttons*fontList: \
  -*-helvetica-medium-r-*-*-10-*-*-*-*-*-*-*=charset

The resolution-independent alternative looks like this:

  Ddd*tool_buttons.run.fontList: \
  -*-helvetica-bold-r-*-*-*-90-*-*-*-*-*-*=charset
  Ddd*tool_buttons.break.fontList: \
  -*-helvetica-bold-r-*-*-*-90-*-*-*-*-*-*=charset
  Ddd*tool_buttons*fontList: \
  -*-helvetica-medium-r-*-*-*-80-*-*-*-*-*-*=charset

Pick your choice and copy and modify the appropriate resources to your `$HOME/.ddd/init' file. For fonts within the data display, see the `vslDefs' resource, below.

  Setting DDD Colors

These are the most important color resources used in DDD:

Ddd*foreground:
    black

Ddd*background:
    grey

Ddd*XmText.background:
    grey90

Ddd*XmTextField.background:
    grey90

Ddd*GraphEdit.background:
    grey90

Ddd*XmList.background:
    grey90

Ddd*graph_edit.nodeColor:
    black

Ddd*graph_edit.edgeColor:
    blue4

Ddd*graph_edit.selectColor:
    black

Ddd*graph_edit.gridColor:
    black

Ddd*graph_edit.frameColor:
    grey50

Ddd*graph_edit.outlineColor:
    grey50

Again, you can copy and modify the appropriate resources to your `$HOME/.ddd/init' file. For colors within the data display, see the `vslDefs' resource, below.

  General Preferences
The following resources determine DDD general behavior.

buttonTips (class Tips)
    Whether button tips are enabled (`true', default) or not (`false'). Button tips are helpful for novices, but may be distracting for experienced users.

buttonDocs (class Docs)
    Whether the display of button hints in the status line is enabled (`true', default) or not (`false').

globalTabCompletion (class GlobalTabCompletion)
    If this is `true' (default), the TAB key completes arguments in all windows. If this is `false', the TAB key completes arguments in the debugger console only.

groupIconify (class GroupIconify)
    If this is `true', (un)iconifying any DDD window causes all other DDD windows to (un)iconify as well. Default is `false', meaning that each DDD window can be iconified on its own.

uniconifyWhenReady (class UniconifyWhenReady)
    If this is `true' (default), the DDD windows are uniconified automatically whenever GDB becomes ready. This way, you can iconify DDD during some longer operation and have it uniconify itself as soon as the program stops. Setting this to `false' leaves the DDD windows iconified.

saveHistoryOnExit (class SaveHistoryOnExit)
    If `true' (default), the command history is automatically saved when DDD exits.

showStartupLogo (class ShowStartupLogo)
    If non-empty, show a DDD logo upon start-up. Possible values include: `c' for a color visual, `g' for a multi-level greyscale visual, `g4' for a 4-level greyscale visual, `m' for a dithered monochrome visual, and `' (the empty string) for no logo at all. The value `best' chooses the best visual available for your display. Default is `g4'.
    Note: if DDD runs on a monochrome display, or if DDD was compiled without the XPM library, only the monochrome version (`m') can be shown.

suppressWarnings (class SuppressWarnings)
    If `true', X warnings are suppressed. This is sometimes useful for executables that were built on a machine with a different X or Motif configuration. By default, this is `false'.

ungrabMousePointer (class UngrabMousePointer)
    When debugging a modal X application, DDD may interrupt it while it has grabbed the pointer, making further interaction impossible. If this is `true', DDD will check after each interaction whether the pointer is grabbed. If this is so, DDD will instruct the debugged program to ungrab the mouse pointer. The default setting is `false', since this feature is known to interfere with some Motif versions (popup menus won't work).

valueTips (class Tips)
    Whether value tips are enabled (`true', default) or not (`false'). Value tips affect DDD performance and may be distracting for some experienced users.

valueDocs (class Docs)
    Whether the display of variable values in the status line is enabled (`true', default) or not (`false').

  Source Window
The following resources determine the DDD source window.

cacheMachineCode (class CacheMachineCode)
    Whether to cache disassembled machine code (`true', default) or not (`false'). Caching machine code requires more memory, but makes DDD run faster.

cacheSourceFiles (class CacheSourceFiles)
    Whether to cache source files (`true', default) or not (`false'). Caching source files requires more memory, but makes DDD run faster.

disassemble (class Disassemble)
    If this is `true', the source code is automatically disassembled. The default is `false'. See also the `--disassemble' and `--no-disassemble' options, below.

displayGlyphs (class DisplayGlyphs)
    If this is `true', the current execution position and breakpoints are displayed as glyphs; otherwise, they are shown through characters in the text. The default is `true'. See also the `--glyphs' and `--no-glyphs' options, below.

displayLineNumbers (class DisplayLineNumbers)
    If this is `true', lines in the source text are prefixed with their respective line number. The default is `false'.

findCaseSensitive (class FindCaseSensitive)
    If this is `true' (default), the `Find' commands are case-sensitive. Otherwise, occurrences are found regardless of case.

findWordsOnly (class FindWordsOnly)
    If this is `true' (default), the `Find' commands find complete words only. Otherwise, arbitrary occurrences are found.

indentCode (class Indent)
    The number of columns to indent the machine code, such that there is enough place to display breakpoint locations. Default: 4.

indentSource (class Indent)
    The number of columns to indent the source code, such that there is enough place to display breakpoint locations. Default: 4.

lineNumberWidth (class LineNumberWidth)
    The number of columns to use for line numbers (if displaying line numbers is enabled). Line numbers wider than this value extend into the breakpoint space. Default: 4.

linesAboveCursor (class LinesAboveCursor)
    The minimum number of lines to show before the current location. Default is 2.

linesBelowCursor (class LinesBelowCursor)
    The minimum number of lines to show after the current location. Default is 3.

maxDisassemble (class MaxDisassemble)
    Maximum number of bytes to disassemble (default: 1024). If this is zero, the entire current function is disassembled.

tabWidth (class TabWidth)
    The tab width used in the source window (default: 8)

useSourcePath (class UseSourcePath)
    If this is `false' (default), the inferior debugger refers to source code locations only by their base names. If this is `true' (default), DDD uses the full source code paths.

  Window Creation and Layout
The following resources determine DDD window creation and layout as well as the interaction with the X window manager.

autoRaiseTool (class AutoRaiseTool)
    If `true' (default), DDD will always keep the command tool on top of other DDD windows. If this setting interferes with your window manager, or if your window manager keeps the command tool on top anyway, set this resource to `false'.

autoRaiseMenu (class AutoRaiseMenu)
    If `true' (default), DDD will always keep the pulldown menu on top of the DDD main window. If this setting interferes with your window manager, or if your window manager does not auto-raise windows, set this resource to `false':

      Ddd*autoRaiseMenu: false

colorIcons (class ColorIcons)
    If `true' (default), DDD uses multi-color icons. If your window manager has trouble with multi-color icons, set this resource to `false' and DDD will use black-and-white icons instead.

dataWindow (class Window)
    If `false', no data window is created upon start-up.

decorateTool (class DecorateTool)
    This resource controls the decoration of the command tool.

    •   If this is `false', the command tool is created as a transient window. Several window managers keep transient windows automatically on top of their parents, which is appropriate for the command tool. However, your window manager may be configured not to decorate transient windows, which means that you cannot easily move the command tool around.

    •   If this is `true', DDD realizes the command tool as a top-level window. Such windows are always decorated by the window manager. However, top-level windows are not automatically kept on top of other windows, such that you may wish to set the `autoRaiseTool' resource, too.

    •   If this is `auto' (default), DDD checks whether the window manager decorates transients. If yes, the command tool is realized as a transient window (as in the false setting); if no, the command tool is realized as a top-level window (as in the true setting). Hence, the command tool is always decorated using the “best” method, but the extra check takes some time.

debuggerConsole (class Window)
    If `false', no debugger console is created upon start-up.

separateDataWindow (class Separate)
    If `true', the data window and the debugger console are realized in different top-level windows. If `false' (default), the data window is attached to the debugger console. See also the `--attach-windows' and `--attach-data-window' options, below.

separateExecWindow (class Separate)
    If `true', the debugged program is executed in a separate execution window. If `false' (default), the debugged program is executed in the console window. See also the `--exec-window' and `--no-exec-window' options, below.

separateSourceWindow (class Separate)
    If `true', the source window and the debugger console are realized in different top-level windows. If `false' (default), the source window is attached to the debugger console. See also the `--attach-windows' and `--attach-source-window' options, below.

sourceWindow (class Window)
    If `false', no source window is created upon start-up.

statusAtBottom (class StatusAtBottom)
    If `true' (default), the status line is placed at the bottom of the DDD source window. If `false', the status line is placed at the top of the DDD source window. See also the `--status-at-bottom' and `--status-at-top' options, below.

stickyTool (class StickyTool)
    If `true' (default), the command tool automatically follows every movement of the source window. Whenever the source window is moved, the command tool is moved by the same offset such that its position relative to the source window remains unchanged. If `false', the command tool does not follow source window movements.

  Debugger Settings
The following resources determine the inferior debugger.

autoCommands (class AutoCommands)
    If this is `true', each line output by the inferior debugger beginning with the value of the `autoCommandPrefix' resource (see below) will be taken as DDD command and executed. Useful for user-defined commands; see `USER-DEFINED COMMANDS', above. By default, `false'.

autoCommandPrefix (class AutoCommandPrefix)
    The prefix for auto-commands. By default, `ddd: '.

blockTTYInput (class BlockTTYInput)
    Whether DDD should block when reading data from the inferior debugger via the pseudo-tty interface. Some systems require this, such as Linux with libc 5.4.33 and earlier; set it to `true'. Some other systems prohibit this, such as Linux with GNU libc 6 and later; set it to `false'. The value `auto' (default) will always select the “best” choice (that is, the best choice known to the DDD developers).

dbxInitCommands (class InitCommands)
    This string contains a list of newline-separated commands that are initially sent to DBX. By default, it is empty.
    Do not use this resource to customize DBX; instead, use a personal `$HOME/.dbxinit' or `$HOME/.dbxrc' file. See your DBX documentation for details.

dbxSettings (class Settings)
    This string contains a list of newline-separated commands that are also initially sent to DBX. By default, it is empty.

debugger (class Debugger)
    The type of the inferior debugger (`gdb', `dbx', or `xdb'). Default value is `gdb'. This resource is usually set through the `--gdb', `--dbx', and `--xdb' options; see below for details.

debuggerCommand (class DebuggerCommand)
    The name under which the inferior debugger is to be invoked. If this string is empty, the debugger type (`debugger' resource) is used. This resource is usually set through the `--debugger' option; see below for details.

debuggerHost (class DebuggerHost)
    The host where the inferior debugger is to be executed; an empty string (default) means the local host. See the `--host' option, below, and `REMOTE DEBUGGING', above.

debuggerHostLogin (class DebuggerHostLogin)
    The login user name on the remote host; an empty string (default) means using the local user name. See the `--login' option, below, and `REMOTE DEBUGGING', above.

debuggerRHost (class DebuggerRHost)
    The host where the inferior debugger is to be executed; an empty string (default) means to use the `debuggerHost' resource. In contrast to `debuggerHost', using this resource causes DDD to login interactively to the remote host and invoke the inferior debugger from the remote shell. See also the `--rhost' option, below, and `REMOTE DEBUGGING', above.

fullNameMode (class TTYMode)
    If this is `true', DDD reports the current source position on standard output in GDB `-fullname' format. As a side effect, the source window is disabled by default. See also the `--fullname' option, below.

gdbInitCommands (class InitCommands)
    This string contains a list of newline-separated commands that are initially sent to GDB. As a side-effect, all settings specified in this resource are considered fixed and cannot be changed through the GDB settings panel, unless preceded by white space. By default, the `gdbInitCommands' resource contains some settings vital to DDD:

      Ddd*gdbInitCommands: \
      set height 0\n\
      set width 0\n\
       set verbose off\n\
      set prompt (gdb) \n

    While the `set height', `set width', and `set prompt' settings are fixed, the `set verbose' settings can be changed through the GDB settings panel (although being reset upon each new DDD invocation).
    Do not use this resource to customize GDB; instead, use a personal `$HOME/.gdbinit' file. See your GDB documentation for details.

gdbSettings (class Settings)
    This string contains a list of newline-separated commands that are also initially sent to GDB. Its default value is

      Ddd*gdbSettings: \
      set print asm-demangle on\n

    This resource is used to save and restore the debugger settings.

questionTimeout (class QuestionTimeout)
    The time (in seconds) to wait for the inferior debugger to reply. Default is 10.

rHostInitCommands (class RHostInitCommands)
    These commands are initially executed in a remote interactive session, using the `--rhost' option. By default, it sets up the remote terminal such that it suits DDD:

      Ddd*rHostInitCommands: stty -echo -onlcr

    You may add other commands here—for instance, to set the executable path or to invoke a suitable shell.

synchronousDebugger (class SynchronousDebugger)
    If `true', X events are not processed while the debugger is busy. This may result in slightly better performance on single-processor systems. See also the `--sync-debugger' option, below.

ttyMode (class TTYMode)
    If `true', enable TTY interface, taking additional debugger commands from standard input and forwarding debugger output on standard output. As a side effect, the debugger console is disabled by default. See also the `--tty' and `--fullname' options, below.

useTTYCommand (class UseTTYCommand)
    If `true', use the GDB `tty' command for redirecting input/output to the separate execution window. If `false', use explicit redirection through shell redirection operators `<' and `>'. The default is `false' (explicit redirection), since on some systems, the `tty' command does not work properly.

xdbInitCommands (class InitCommands)
    This string contains a list of newline-separated commands that are initially sent to XDB. By default, it is empty.
    Do not use this resource to customize DBX; instead, use a personal `$HOME/.xdbrc' file. See your XDB documentation for details.

xdbSettings (class Settings)
    This string contains a list of newline-separated commands that are also initially sent to XDB. By default, it is empty.

  User-defined Buttons
The following resources can be used to create user-defined buttons.

consoleButtons (class Buttons)
    A newline-separated list of buttons to be added under the debugger console. Each button issues the command given by its name.

    The following characters have special meanings:

    •   Commands ending with '...' insert their name, followed by a space, in the debugger console.

    •   Commands ending with a control character (that is, `^' followed by a letter or `?') insert the given control character.

    •   The string `()' is replaced by the current contents of the argument field `()'.

    •   The string specified in the `labelDelimiter' resource (usually `//') separates the command name from the button label. If no button label is specified, the capitalized command will be used as button label.

    The following button names are reserved:

    Clear
        Clear current command

    Prev
        Show previous command

    Next
        Show next command

    Apply
        Send the given command to the debugger.

    Back
        Lookup previously selected source position.

    Forward
        Lookup next selected source position.

    Edit
        Edit current source file.

    Reload
        Reload source file.

    Complete
        Complete current command.

    Yes Answer current debugger prompt with `yes'. This button is visible only if the debugger asks a yes/no question.

    No  Answer current debugger prompt with `no'. This button is visible only if the debugger asks a yes/no question.

    The default resource value is empty—no console buttons are created.

    Here are some examples to insert into your `$HOME/.ddd/init' file. These are the settings of DDD 1.x:

      Ddd*consoleButtons: Yes\nNo\nbreak^C

    This setting creates some more buttons:

      Ddd*consoleButtons: \
      Yes\nNo\nrun\nClear\nPrev\nNext\nApply\nbreak^C

    See also the `dataButtons', `sourceButtons' and `toolButtons' resources, below.

dataButtons (class Buttons)
    A newline-separated list of buttons to be added under the data display. Each button issues the command given by its name. See the `consoleButtons' resource, above, for details on button syntax.

    The default resource value is empty—no source buttons are created.

sourceButtons (class Buttons)
    A newline-separated list of buttons to be added under the debugger console. Each button issues the command given by its name. See the `consoleButtons' resource, above, for details on button syntax.

    The default resource value is empty—no source buttons are created.

    Here are some example to insert into your `$HOME/.ddd/init' file. These are the settings of DDD 1.x:

      Ddd*sourceButtons: \
      run\nstep\nnext\nstepi\nnexti\ncont\n\
      finish\nkill\nup\ndown\n\
      Back\nForward\nEdit\ninterrupt^C

    This setting creates some buttons which are not found on the command tool:

      Ddd*sourceButtons: \
      print *()\ngraph display *()\nprint /x ()\n\
      whatis ()\nptype ()\nwatch ()\nuntil\nshell

    An even more professional setting uses customized button labels.

      Ddd*sourceButtons: \
      print *(()) // Print *()\n\
      graph display *(()) // Display *()\n\
      print /x ()\n\
      whatis () // What is ()\n\
      ptype ()\n\
      watch ()\n\
      until\n\
      shell

    See also the `consoleButtons' and `dataButtons' resources, above, and the `toolButtons' resource, below.

toolBar (class ToolBar)
    Whether the tool buttons (see the `toolButtons' resource, below) should be shown in a tool bar below the source window (true) or within the command tool (false, default). Enabling the tool bar disables the command tool and vice versa.

toolButtons (class Buttons)
    A newline-separated list of buttons to be included in the command tool or the tool bar (see the `toolBar' resource, above). Each button issues the command given by its name. See the `consoleButtons' resource, above, for details on button syntax.

    The default resource value is

      Ddd*toolButtons: \
      run\ninterrupt^C\nstep\nstepi\n\
      next\nnexti\ncont\nfinish\n\
      up\ndown\nBack\nForward\nEdit\nkill

    For each button, its location in the command tool must be specified using XmForm constraint resources. Each side of a button is attached to a row or column position. Rows are numbered from 0 (top side) to 8 (bottom side); columns likewise are numbered from 0 (left side) to 8 (right side). The position of the break button, for instance, is specified as:

      Ddd*tool_buttons.break.topPosition: 1
      Ddd*tool_buttons.break.bottomPosition: 2
      Ddd*tool_buttons.break.leftPosition: 0
      Ddd*tool_buttons.break.rightPosition: 8

    while the Back button position is specified as

      Ddd*tool_buttons.Back.topPosition: 6
      Ddd*tool_buttons.Back.bottomPosition: 7
      Ddd*tool_buttons.Back.leftPosition: 0
      Ddd*tool_buttons.Back.rightPosition: 4

    The number of rows and columns (default: 8) can be changed by setting the `fractionBase' resource to a different value:

      Ddd*tool_buttons.fractionBase: 10

    If you change the `fractionBase' resource, you must provide new positions for all buttons in the command tool. See the `Ddd' app-defaults file for more details.

    If the `toolButtons' resource value is empty, the command tool is not created.

toolRightOffset (class Offset)
    The distance between the right border of the command tool and the right border of the source text (in pixels). Default is 8 pixels.

toolTopOffset (class Offset)
    The distance between the upper border of the command tool and the upper border of the source text (in pixels). Default is 8 pixels.

verifyButtons (class VerifyButtons)
    If true (default), verify for each button whether its command is actually supported by the inferior debugger. If the command is unknown, the button is disabled. If this resource is false, no checking is done: all commands are accepted “as is”.

  Data Display
The following resources control the data display.

align2dArrays (class Align2dArrays)
    If true (default), DDD lays out two-dimensional arrays as tables, such that all array elements are aligned with each other. If false, DDD treats a two-dimensional array as an array of one-dimensional arrays, each aligned on its own.

bumpDisplays (class BumpDisplays)
    If some display D changes size and this resource is true (default), DDD assigns new positions to displays below and on the right of D such that the distance between displays remains constant. If this is false, other displays are not rearranged.

detectAliases (class DetectAliases)
    If true, DDD attempts to recognize shared data structures. See `Examining shared data structures', above, for a discussion. The default is false, meaning that shared data structures are not recognized.

displayShortcuts (class DisplayShortcuts)
    A newline-separated list of display expressions to be included in the `New Display' menu. If a line contains a label delimiter (the string `//'; can be changed via the `labelDelimiter' resource), the string before the delimiter is used as expression, and the string after the delimiter is used as label. Otherwise, the label is `Display expression'. Upon activation, the string `()' in expression is replaced by the name of the currently selected display.

hideInactiveDisplays (class HideInactiveDisplays)
    If some display gets out of scope and this resource is true (default), DDD removes it from the data display. If this is false, it is simply disabled.

labelDelimiter (class LabelDelimiter)
    The string used to separate labels from commands and shortcuts. Default is `//'.

pannedGraphEditor (class PannedGraphEditor)
    What shall DDD use if the graph gets too large to be displayed? If this is `true', an Athena panner is used (a kind of two-directional scrollbar). If this is `false' (default), two Motif scrollbars are used. See also the `--scrolled-graph-editor' and `--panned-graph-editor' options, below.

paperSize (class PaperSize)
    The paper size used for printing, in format width x height. The default is A4 format, or `210mm x 297mm'.

vslDefs (class VSLDefs)
    A string with additional VSL definitions that are appended to the builtin VSL library. This resource can be used to override specific VSL definitions that affect the data display.

    The general pattern to replace a function definition function with a new definition new_def is:

    #pragma replace function
    function(args...) = new_def;

    The following VSL functions are frequently used:

    color(box, foreground [, background])
        Set the foreground and background colors of box.

    display_color(box)
        The color used in data displays. Default: color(box, "black", "white")

    title_color(box)
        The color used in the title bar. Default: color(box, "black")

    disabled_color(box)
        The color used for disabled boxes. Default: color(box, "white", "grey50")

    simple_color(box)
        The color used for simple values. Default: color(box, "black")

    pointer_color(box)
        The color used for pointers. Default: color(box, "blue4")

    struct_color(box)
        The color used for structures. Default: color(box, "black")

    array_color(box)
        The color used for arrays. Default: color(box, "blue4")

    reference_color(box)
        The color used for references. Default: color(box, "blue4")

    changed_color(box)
        The color used for changed values. Default: color(box, "black", "#ffffcc")

    stdfontfamily()
        The font family used. One of family_times(), family_courier(), family_helvetica(), family_new_century(), or family_typewriter() (default).

    stdfontsize()
        The font size used (in pixels). 0 means to use stdfontpoints() instead. Default value: 12.

    stdfontpoints()
        The font size used (in 1/10 points). 0 (default) means to use stdfontsize() instead.

    stdfontweight()
        The font weight used. Either weight_medium() (default) or weight_bold().

    To set the pointer color to "red4", use

      Ddd*vslDefs: \
      #pragma replace pointer_color\n\
      pointer_color(box) = color(box, "red4");\n

    To set the default font size to resolution-independent 10.0 points, use

      Ddd*vslDefs: \
      #pragma replace stdfontsize\n\
      #pragma replace stdfontpoints\n\
      stdfontsize() = 0;\n
      stdfontpoints() = 100;\n

    To set the default font to 12-pixel courier, use

      Ddd*vslDefs: \
      #pragma replace stdfontsize\n\
      #pragma replace stdfontfamily\n\
      stdfontsize() = 12;\n\
      stdfontfamily() = family_courier();\n

    See the file `ddd.vsl' for further definitions to override using the `vslDefs' resource.

vslLibrary (class VSLLibrary)
    The VSL library to use. `builtin' (default) means to use the built-in library, any other value is used as file name.

vslPath (class VSLPath)
    A colon-separated list of directories to search for VSL include files. Default is `.', the current directory.

    If your DDD source distribution is installed in `/opt/src', you can use the following settings to read the VSL library from `/home/joe/ddd.vsl':

      Ddd*vslLibrary: /home/joe/ddd.vsl
      Ddd*vslPath: \
      .:/opt/src/ddd/ddd:/opt/src/ddd/vsllib

    VSL include files referenced by `/home/joe/ddd.vsl' are searched first in the current directory `.', then in `/opt/src/ddd/ddd/', and then in `/opt/src/ddd/vsllib/'.

    Instead of supplying another VSL library, it is often easier to specify some minor changes to the built-in library. See the `vslDefs' resource, above, for details.

  Debugger Console
The following resources control the debugger console.

lineBufferedConsole (class LineBuffered)
    If this is `true' (default), each line from the inferior is output on each own, such that the final line is placed at the bottom of the debugger console. If this is `false', all lines are output as a whole. This is faster, but results in a random position of the last line.

  Customizing Helpers
The following resources determine external programs invoked by DDD.

editCommand (class EditCommand)
    A command string to invoke an editor on the specific file. `@LINE@' is replaced by the current line number, `@FILE@' by the file name. The default is to invoke $XEDITOR first, then $EDITOR, then vi:

      Ddd*editCommand: \
      ${XEDITOR-false} +@LINE@ @FILE@ \
      || xterm -e ${EDITOR-vi} +@LINE@ @FILE@

    This `.ddd/init' setting invokes an editing session for an XEmacs editor running gnuserv:

      Ddd*editCommand: gnuclient +@LINE@ @FILE@

    This `.ddd/init' setting invokes an editing session for an Emacs editor running emacsserver:

      Ddd*editCommand: emacsclient +@LINE@ @FILE@

getCoreCommand (class GetCoreCommand)
    A command to get a core dump of a running process (typically, `gcore') `@FILE@' is replaced by the base name of the file to create; `@PID@' is replaced by the process id. The output must be written to `@FILE@.@PID@'.
    Leave this entry empty if you have no `gcore' or similar command.

lessTifVersion (class LessTifVersion)
    Indicates the LessTif version DDD is running against. For LessTif version x.y, the value is x multiplied by 1000 plus y—for instance, the value 79 stands for LessTif 0.79 and the value 1005 stands for LessTif 1.5.
    If the value of this resource is less than 1000, indicating LessTif 0.99 or earlier, DDD enables version-specific hacks to make DDD work around LessTif bugs and deficiencies.
    If DDD was compiled against LessTif, the default value is the value of the `LessTifVersion' macro in <Xm/Xm.h>. If DDD was compiled against OSF/Motif, the default value is 1000, disabling all LessTif-specific hacks.

listCoreCommand (class listCoreCommand)
    The commmand to list all core files on the remote host. The string `@MASK@' is replaced by a file filter. The default setting is:

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

listDirCommand (class listDirCommand)
    The commmand to list all directories on the remote host. The string `@MASK@' is replaced by a file filter. The default setting is:

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

listExecCommand (class listExecCommand)
    The commmand to list all executable files on the remote host. The string `@MASK@' is replaced by a file filter. The default setting is:

      Ddd*listExecCommand: \
      file @MASK@ | grep '.*:.*exec.*' \
      | grep -v '.*:.*script.*' \
      | cut -d: -f1 | grep -v '.*\.o$'

listSourceCommand (class listSourceCommand)
    The commmand to list all source files on the remote host. The string `@MASK@' is replaced by a file filter. The default setting is:

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

printCommand (class PrintCommand)
    The command to print a postscript file. Usually `lp' or `lpr'.

psCommand (class PsCommand)
    The command to get a list of processes. Usually `ps'. Depending on your system, useful alternate values include `ps -ef' and `ps -ux'. The first line of the output must either contain a `PID' title, or each line must begin with a process ID.
    Note that the output of this command is filtered by DDD; a process is only shown if it can be attached to. The DDD process itself as well as the process of the inferior debugger are suppressed, too.

rshCommand (class RshCommand)
    The remote shell command to invoke tty-based commands on remote hosts. Usually, `remsh', `rsh', or `on'.

termCommand (class TermCommand)
    The command to invoke a separate tty for showing the input/output of the debugged program. A bourne shell command to run in the separate tty is appended this string. A simple value is

      Ddd*termCommand: xterm -e /bin/sh -c

uncompressCommand (class UncompressCommand)
    The command to uncompress the built-in DDD manual, the DDD license, and the DDD news. Takes a compressed text from standard input and writes the uncompressed text to standard output. The default value is `gzip -d -c'; typical values include `zcat' and `gunzip -c'.

termType (class TermType)
    The terminal type provided by the `termCommand' resource—that is, the value of the TERM environment variable to be passed to the debugged program. Default: `xterm'.

wwwCommand (class WWWCommand)
    The command to invoke a WWW browser. The string `@URL@' is replaced by the URL to open. Default is to try a running Netscape first, then to invoke a new Netscape process, then to let a running Emacs do the job, then to invoke Mosaic, then to invoke Lynx.

    To specify `netscape-4.0' as browser, use the setting:

      Ddd*wwwCommand: \
      netscape-4.0 -remote 'openURL(@URL@)' \
      || netscape-4.0 '@URL@'

    This command first tries to connect to a running netscape-4.0 browser; if this fails, it starts a new netscape-4.0 process.

wwwPage (class WWWPage)
    The DDD WWW page. Value:

      Ddd*wwwPage: http://www.cs.tu-bs.de/softech/ddd/

  Obtaining Diagnostics
The following resources are used for debugging DDD and to obtain specific DDD information.

appDefaultsVersion (class Version)
    The version of the DDD app-defaults file. If this string does not match the version of the current DDD executable, DDD issues a warning.

checkConfiguration (class CheckConfiguration)
    If true, check the DDD environment (in particular, the X configuration), report any possible problem causes and exit. See also the `--check-configuration' option, below.

dddinitVersion (class Version)
    The version of the DDD executable that last wrote the `$HOME/.ddd/init' file. If this string does not match the version of the current DDD executable, DDD issues a warning.

showConfiguration (class ShowConfiguration)
    If `true', show the DDD configuration on standard output and exit. See also the `--configuration' option, below.

showInvocation (class ShowInvocation)
    If `true', show the DDD invocation options on standard output and exit. See also the `--help' option, below.

showLicense (class ShowLicense)
    If `true', show the DDD license on standard output and exit. See also the `--license' option, below.

showManual (class ShowManual)
    If `true', show this DDD manual page on standard output and exit. If the standard output is a terminal, the manual page is shown in a pager ($PAGER, `less' or `more'). See also the `--manual' option, below.

showNews (class ShowNews)
    If `true', show the DDD news on standard output and exit. See also the `--news' option, below.

showVersion (class ShowVersion)
    If `true', show the DDD version on standard output and exit. See also the `--version' option, below.

traceDialog (class Trace)
    If `true', show the dialog between DDD and the inferior debugger on standard output. Default is `false'.

traceShellCommands (class Trace)
    If `true', show the programs invoked by DDD on standard output. Default is `false'.

  More Resources
The `Ddd' application defaults file contains even more information about setting DDD resources. The `Ddd' file comes with the DDD distribution.

ACTIONS
The following DDD actions may be used in translation tables.

  General Actions
These actions are used to assign the keyboard focus.

ddd-next-tab-group ()
    Assign focus to the next tab group.

ddd-prev-tab-group ()
    Assign focus to the previous tab group.

ddd-previous-tab-group ()
    Assign focus to the previous tab group.

ddd-get-focus ()
    Assign focus to the element that just received input.

  Data Display Actions
These actions are used in the DDD graph editor.

end ()
    End the action initiated by select. Bound to a button up event.

extend ()
    Extend the current selection. Bound to a button down event.

extend-or-move ()
    Extend the current selection. Bound to a button down event. If the pointer is dragged, move the selection.

follow ()
    Continue the action initiated by select. Bound to a pointer motion event.

graph-select ()
    Equivalent to select, but also updates the current argument.

graph-select-or-move ()
    Equivalent to select-or-move, but also updates the current argument.

graph-extend ()
    Equivalent to extend, but also updates the current argument.

graph-extend-or-move ()
    Equivalent to extend-or-move, but also updates the current argument.

graph-toggle ()
    Equivalent to toggle, but also updates the current argument.

graph-toggle-or-move ()
    Equivalent to toggle-or-move, but also updates the current argument.

graph-popup-menu ([graph|node|shortcut])
    Pops up a menu. graph pops up a menu with global graph operations, node pops up a menu with node operations, and shortcut pops up a menu with display shortcuts. If no argument is given, pops up a menu depending on the context: when pointing on a node with the Shift key pressed, behaves like shortcut; when pointing on a without the Shift key pressed, behaves like node; otherwise, behaves as if graph was given.

graph-dereference ()
    Dereference the selected display.

graph-detail ()
    Show or hide detail of the selected display.

graph-rotate ()
    Rotate the selected display.

graph-dependent ()
    Pop up a dialog to create a dependent display.

hide-edges ([any|both|from|to])
    Hide some edges. any means to process all edges where either source or target node are selected. both means to process all edges where both nodes are selected. from means to process all edges where at least the source node is selected. to means to process all edges where at least the target node is selected. Default is any.

layout ([regular|compact], [[+|-]degrees]])
    Layout the graph. regular means to use the regular layout algorithm; compact uses an alternate layout algorithm, where successors are placed next to their parents. Default is regular. degrees indicates in which direction the graph should be layouted. Default is the current graph direction.

move-selected (x-offset, y-offset)
    Move all selected nodes in the direction given by x-offset and y-offset. x-offset and y-offset is either given as a numeric pixel value, or as `+grid', or `-grid', meaning the current grid size.

normalize ()
    Place all nodes on their positions and redraw the graph.

rotate ([[+|-]degrees])
    Rotate the graph around degrees degrees. degrees must be a multiple of 90. Default is +90.

select ()
    Select the node pointed at. Clear all other selections. Bound to a button down event.

select-all ()
    Select all nodes in the graph.

select-first ()
    Select the first node in the graph.

select-next ()
    Select the next node in the graph.

select-or-move ()
    Select the node pointed at. Clear all other selections. Bound to a button down event. If the pointer is dragged, move the selected node.

select-prev ()
    Select the previous node in the graph.

show-edges ([any|both|from|to])
    Show some edges. any means to process all edges where either source or target node are selected. both means to process all edges where both nodes are selected. from means to process all edges where at least the source node is selected. to means to process all edges where at least the target node is selected. Default is any.

snap-to-grid ()
    Place all nodes on the nearest grid position.

toggle ()
    Toggle the current selection—if the node pointed at is selected, it will be unselected, and vice versa. Bound to a button down event.

toggle-or-move ()
    Toggle the current selection—if the node pointed at is selected, it will be unselected, and vice versa. Bound to a button down event. If the pointer is dragged, move the selection.

unselect-all ()
    Clear the selection.

  Debugger Console Actions
These actions are used in the debugger console and other text fields.

gdb-backward-character ()
    Move one character to the left. Bound to Ctrl+B and Left.

gdb-beginning-of-line ()
    Move cursor to the beginning of the current line, after the prompt. Bound to Ctrl+A and Home.

gdb-control (control-character)
    Send the given control-character to the inferior debugger. The control-character must be specified in the form `^X', where X is an upper-case letter or `?'. Bound to Ctrl+C and Ctrl+\.

gdb-command (command)
    Execute command in the debugger console.

gdb-complete-arg (command)
    Complete current argument as if command was prepended. Bound to Ctrl+T.

gdb-complete-command ()
    Complete current command line in the debugger console. Bound to TAB and Ctrl+T.

gdb-complete-tab (command)
    If global TAB completion is enabled, complete current argument as if command was prepended. Otherwise, proceed as if the TAB key was hit. Bound to TAB.

gdb-delete-or-control (control-character)
    Like gdb-control, but effective only if the cursor is at the end of a line. Otherwise, control-character is ignored and the character following the cursor is deleted. Bound to Ctrl+D.

gdb-end-of-line ()
    Move cursor to the end of the current line. Bound to Ctrl+E and End.

gdb-next-history ()
    Recall next command from history. Bound to Ctrl+N and Down.

gdb-prev-history ()
    Recall previous command from history. Bound to Ctrl+P and Up.

gdb-previous-history ()
    Recall previous command from history. Bound to Ctrl+P and Up.

gdb-process ()
    Process the given event in the debugger console. Bound to key events in the source and data window.

gdb-forward-character ()
    Move one character to the right. Bound to Ctrl+F and Right.

gdb-insert-graph-arg ()
    Insert the contents of the data display argument field `()'.

gdb-insert-source-arg ()
    Insert the contents of the source argument field `()'.

gdb-isearch-prev ()
    Enter reverse incremental search mode. Bound to Ctrl+R.

gdb-isearch-next ()
    Enter incremental search mode. Bound to Ctrl+S.

gdb-isearch-exit ()
    Exit incremental search mode. Bound to ESC.

gdb-set-line (value)
    Set the current line to value. Bound to Ctrl+U.

  Source Window Actions
These actions are used in the source and code windows.

source-popup-menu ()
    Pop up a menu, depending on the location.

source-start-select-word ()
    Start selecting a word.

source-end-select-word ()
    End selecting a word.

source-update-glyphs ()
    Update all visible glyphs. Usually invoked after a scrolling operation.

source-drag-glyph ()
    Initiate a drag on the glyph at cursor position.

source-follow-glyph ()
    Continue a drag on the glyph at cursor position. Usually bound to some motion event.

source-drop-glyph ()
    Drop the dragged glyph at cursor position.

OPTIONS
You can use the following options when starting DDD. All options may be abbreviated, as long as they are unambiguous; single dashes may also be used. DDD also understands the usual X options such as `-display' or `-geometry'; see X(1) for details.

All other arguments and options are passed to the inferior debugger. 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, below.

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

--attach-source-window
    Attaches only the source window to the debugger console.

--attach-data-window
    Attaches only the source window to the debugger console.

--button-tips
    Enable button tips.

--configuration
    Show the DDD configuration settings and exit.

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

--dbx
    Run the DBX debugger as inferior debugger.

--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 as `gdb', `dbx', or `xdb', respectively. This option can also be used to pass options to the inferior debugger that would otherwise conflict with DDD options. For instance, to pass a `-d directory' option 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', or `--xdb'—unless the default setting works fine.

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

--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.

--fullname
    Enable 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.

--gdb
    Run the GDB debugger as inferior debugger.

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

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

--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 DEBUGGING', above.

--lesstif-hacks
    Equivalent to `--lesstif-version version', where version is the version of the most recent LessTif release. Deprecated.

--lesstif-version version
    Enable some hacks to make DDD run properly with LessTif. See the `lessTifVersion' resource and `USING DDD WITH LESSTIF', above, for a discussion.

--license
    Show the DDD license and exit.

--login username
    Use username as remote user name. See `REMOTE DEBUGGING', above.

--manual
    Show this manual page and exit.

--news
    Show the DDD news and exit.

--no-button-tips
    Disable button tips.

--no-data-window
    Do not create the data window upon start-up.

--no-debugger-console
    Do not create the debugger console upon start-up.

--no-disassemble
    Do not disassemble the source code.

--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.

--no-glyphs
    Display the current execution position and breakpoints as text characters. Do not use glyphs.

--no-lesstif-hacks
    Equivalent to `--lesstif-version 1000'. Deprecated.

--no-source-window
    Do not create the source window upon start-up.

--no-value-tips
    Disable value tips.

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

--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 Motif implementations do not work well with Athena widgets. See also --scrolled-graph-editor, below.

--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 DEBUGGING', above.

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

--scrolled-graph-editor
    Use Motif scroll bars to scroll the data window. This is the default in most DDD configurations. See also --panned-graph-editor, above.

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

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

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

--trace-dialog
    Show the interaction between DDD and the inferior debugger on standard error. This is useful for debugging DDD.

--trace-shell-commands
    Show the shell commands issued by DDD on standard error. This is useful for debugging DDD.

--trace
    Show both interaction and shell commands.

--tty
    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.

--value-tips
    Enable value tips.

--version
    Show the DDD version and exit.

--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.

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

--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.

--xdb
    Run XDB as inferior debugger.

ENVIRONMENT
DDD is controlled by the following environment variables:
DDD_NO_SIGNAL_HANDLERS
    If set, DDD does not catch fatal errors. This is sometimes useful when debugging DDD.
DDD_STATE
    Root of DDD state directory. Default is `$HOME/.ddd/'.
DDD_SESSION
    If set, indicates a session to start, overriding all options. This is used by DDD when restarting itself.
DDD_SESSIONS
    DDD session directory. Default is `$DDD_STATE/sessions/'.
VSL_INCLUDE
    Where to search for VSL include files. Default is the current directory. The following environment variables are set by DDD:
DDD_NAME
    Set to a string indicating the DDD version. By testing whether DDD_NAME is set, a debuggee (or inferior debugger) can determine whether it was invoked by DDD.
TERM
    Set to `dumb', the DDD terminal type. This is set for the inferior debugger only. If the debuggee runs in a separate execution window, the debuggee's TERM value is set according to the `termType' ressource (see `RESOURCES', above).
TERMCAP
    Set to `' (none), the DDD terminal capabilities.
PAGER
    Set to `cat', the preferred DDD pager.

FILES
$HOME/.ddd/
    DDD state directory.
$HOME/.ddd/init
    Individual DDD resource file. DDD options are saved here.
$HOME/.ddd/history
    Default DDD command history file.
$HOME/.ddd/lock
    DDD lock file; indicates that a DDD is running.
$HOME/.ddd/log
    Trace of the current interaction between DDD and the inferior debugger.
$HOME/.ddd/sessions/
    DDD session directory. One subdirectory per session.
$HOME/.ddd/sessions/session/dddcore
    DDD core file for session.
$HOME/.ddd/sessions/session/init
    DDD resource file for session.
$HOME/.ddd/sessions/session/history
    DDD command history for session.
$HOME/.ddd/sessions/.ddd/
    The DDD `restart' session.
$HOME/.gdbinit
    GDB initialization file.
$HOME/.dbxinit
    DBX initialization file.
$HOME/.dbxrc
    Alternate DBX initialization file.
$HOME/.xdbrc
    XDB initialization file.
$HOME/.dddinit
    Old-style DDD initialization file; used only if $HOME/.ddd/init does not exist.

SEE ALSO
X(1), gdb(1), dbx(1), xdb(1), remsh(1), rsh(1)

`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 Lütkehaus, Computer Science Report 95-07, Technische Universität Braunschweig, 1995.

DDD – ein Debugger mit graphischer Datendarstellung, by Dorothea Lütkehaus, Diploma Thesis, Technische Universität Braunschweig, 1994.

The DDD FTP site,

  ftp://ftp.ips.cs.tu-bs.de/pub/local/softech/ddd/

The DDD WWW page,

  http://www.cs.tu-bs.de/softech/ddd/

The DDD Mailing List,

   ddd-users@ips.cs.tu-bs.de

For more information on this list, send a mail to

   ddd-users-request@ips.cs.tu-bs.de .

LIMITATIONS

  Limitations using GDB
Some GDB settings are essential for DDD to work correctly. These settings with their correct values are:

  set height 0
  set width 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.

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.

  Limitations using DBX
When used for debugging Modula-2 or Pascal programs, DDD always numerates array elements starting with zero, instead of using correct array subscripts.

With some DBX versions (notably Solaris DBX), DDD strips C-style and C++-style comments from the DBX output in order to interpret it properly. This also affects the output of the debugged program when sent to the debugger console. Using the separate execution window avoids these problems.

In some DBX versions (notably DEC DBX and AIX DBX), there is no automatic data display. As an alternative, DDD uses the `print' command to access data values. This means that variable names are interpreted according to the current frame; variables outside the current frame cannot be displayed.

  Limitations using XDB
There is no automatic data display in XDB. As a workaround, DDD uses the `p' command to access data values. This means that variable names are interpreted according to the current frame; variables outside the current frame cannot be displayed.

  General Limitations
If command output is sent to the debugger console, it is impossible for DDD to distinguish between the output of the debugged program and the output of the inferior debugger. This problem can be avoided by running the program in the separate execution window.

Output that confuses DDD includes:

•   Primary debugger prompts (e.g. `(gdb) ' or `(dbx) ')

•   Secondary debugger prompts (e.g. `>')

•   Confirmation prompts (e.g. `(y or n) ')

•   Prompts for more output (e.g. `Press RETURN to continue')

•   Display output (e.g. `$pc = 0x1234')

If your program outputs any of these strings, you should run it in the separate execution window.

If the inferior debugger changes the default TTY settings, for instance through a `stty' command in its initialization file, DDD will likely become confused. The same applies to debugged programs which change the default TTY settings.

FREQUENTLY ASKED QUESTIONS (FAQ)

  Which debuggers does DDD support?
DDD has been tested with the following debuggers:

•   GDB (GNU debugger) from the Free Software Foundation

•   DBX as found on SunOS 4.x (aka Solaris 1.x)

•   DBX as found on Solaris 2.x (aka SunOS 5.x)

•   DBX as found on DEC systems (some variants only)

•   DBX as found on AIX systems (some variants only)

•   DBX as found on SGI systems (some variants only)

•   XDB as found on HP-UX systems

DDD functionality largely depends on the capabilities of the underlying debugger; best results are obtained with GDB.

To cope with the large variety of DBX flavors, DDD determines the DBX capabilities dynamically at run-rime; DDD should thus adapt automatically to other DBX variants. Please let us know your experiences; use `ddd --trace' to see the DDD/DBX interaction.

  Can I use DDD with Ada?
Matthew Majka <mmajka@cs5.dasd.honeywell.com> says: It works very well. You just need an Ada-aware version of GDB. You can get the patches from `ftp://cs.nyu.edu/pub/gnat/gdb/'.

  Is there an Athena Widgets port of DDD?
No. If you want DDD running with a free widget set, you should support the Hungry Programmer's Team - they develop LessTif, a free Motif-compliant widget set. Check out their WWW page at `http://www.lesstif.org/'.

  Will DDD work with LessTif?
As of LessTif 0.81, the resulting DDD executable is quite usable; there are several DDD users who use a DDD built with LessTif. See the file `PROBLEMS' for a recent list of problems and fixes.

  Should I compile DDD myself or should I use an executable?
Compiling DDD on your machine is the preferred way, because the resulting DDD executable will be perfectly adapted to your system. However, if your production environment is buggy, or if you lack the resources for compiling DDD, a thoroughly tested precompiled DDD executable may be a better choice.

  How can I display a variable-length array?
The problem is that GDB does not know the actual length of the array; you have to supply it by hand (i.e. using the keyboard). You can use the DDD “display successive array elements” or the GDB “artificial array” mechanism. If you have a pointer, say:

  int *pi;

pointing to an array of 10 ints, you can see the integers by entering

  graph display pi[0..9]

at the debugger prompt (or entering `pi[0..9]` in the `New Display' dialog).

As an alternative, you can use the GDB “artificial array” mechanism by entering

  graph display pi[0]@10

This will create an array starting with pi showing the first 10 elements.

  My window manager crashes when running DDD!
This is due to a bug in the window manager. You may try the following resources in your `$HOME/.ddd/init' file to minimize interference with the window manager; the first ones listed are the ones that are most likely to cause interferences.

  Ddd*colorIcons: false
  Ddd*autoRaiseMenu: false
  Ddd*groupIconify: false
  Ddd*uniconifyWhenReady: false
  Ddd*showStartupLogo:
  Ddd*autoRaiseTool: false
  Ddd*stickyTool: false
  Ddd*decoratedTool: false

See `RESOURCES', above, for a discussion of these resources.

  My X display freezes when running DDD!
This is due to a bug in Motif. You may try the following resources in your `$HOME/.ddd/init' file to minimize interference with Motif:

  Ddd*autoRaiseMenu: false
  Ddd*ungrabMousePointer: false

See `RESOURCES', above, for a discussion of these resources.

  How do I pass ^C to the debugged program?
Assuming you use GDB as inferior debugger, typing `signal 2' at the `(gdb)' prompt will resume program execution with a SIGINT signal.

If it's the character rather than the signal you're interested in, run your program in the separate execution window (via `View | Execution Window') and type Ctrl+C there.

  In C++, how do I see the actual type of an object?
When using a generic pointer, you may wish to see the actual type of an object rather than the declared type. In the GDB settings (`Edit | GDB Settings'), enable `Set printing of object's derived type based on vtable info' or enter `set print object on' at the `(gdb)' prompt.

  I want to use DDD interprocess communication in my own application!
There is a demonstration program named `ttytest' in the DDD package. Just type `make ttytest'. It should be relatively easy to customize this application.

Here are some pointers: If you want to talk with a separate process, use the `TTYAgent' class, as defined in `TTYAgent.C'. Using the `write' method, you can send arbitrary data to the process; you can define an `Input' handler that will be called each time the process sends data to you. The header files of `TTYAgent' and its superclasses should contain sufficient information. As all communication is handled asynchronously, you can realize a usual Xt-based interface using Athena widgets, Motif widgets, or another Xt-based toolkit.

  I want to use the DDD graph editor in my own application!
There is a demonstration program named `test-graph' in the DDD source distribution. Just type `make test-graph'. It should be relatively easy to customize this application.

Here are some pointers: The `GraphEdit' widget, as defined in `GraphEdit.h' contains the DDD graph editor. Variants with Athena panners and Motif scrollbars are found in `PannedGE.h' and `ScrolledGE.h', respectively. The `GraphEdit' widget works on a `Graph' structure, which is defined in `Graph.h'; a graph is composed of nodes and edges, both forming class hierarchies whose top classes are defined in `GraphNode.h' and `GraphEdge.h', respectively. The graph nodes in DDD are Box graph nodes, defined in `BoxGraphN.h'; a box is a (possibly structured) rectangular entity holding strings, lines, or figures. See also the DDD paper `doc/ddd-paper.ps' for details on boxes and how they are composed.

  How can I speed up DDD?
To get the maximum DDD performance,

•   Use the latest DDD version, compiled with optimization enabled.

•   Enable caching of source code and machine code.

•   Disable glyphs.

•   Disable machine code.

•   Disable alias detection.

•   Disable all status displays.

•   Delete all displays you do not need.

•   Do not use remote debugging.

  How can I reduce DDD memory size?
To get a minimal DDD memory usage,

•   Use DDD 2.2 or later (30% memory savings)

•   Hack DDD such that this manual and the resource files are stored externally. (Make it configurable and send us your changes)

REPORTING BUGS
If you find a bug in DDD, please send us a bug report. We will either attempt to fix the bug—or include the bug description in the DDD `BUGS' file, such that others can attempt to fix it. (Instead of sending bug reports, you may also send fixes; DDD is an excellent tool for debugging itself :-)

  Where to Send Bug Reports
We recommend that you send bug reports for DDD via electronic mail to

  ddd-bugs@ips.cs.tu-bs.de

As a last resort, send bug reports on paper to:

  Technische Universität Braunschweig
  Institut für Programmiersprachen
  und Informationssysteme
  Abteilung Softwaretechnologie
  DDD-Bugs
  Bültenweg 88
  D-38092 Braunschweig
  GERMANY

  Is it a DDD Bug?
Before sending in a bug report, try to find out whether the problem cause really lies within DDD. A common cause of problems are incomplete or missing X or Motif installations, for instance, or bugs in the X server or Motif itself. Running DDD as

  ddd --check-configuration

checks for common problems and gives hints on how to repair them.

Another potential cause of problems is the inferior debugger; occasionally, they show bugs, too. To find out whether a bug was caused by the inferior debugger, run DDD as

  ddd --trace

This shows the interaction between DDD and the inferior debugger on standard error while DDD is running. (This interaction is also logged in `$HOME/.ddd/log'.) Compare the debugger output to the output of DDD and determine which one is wrong.

  How to Report Bugs
Here are some guidelines for bug reports:

•   The fundamental principle of reporting bugs usefully is this: report all the facts. If you are not sure whether to state a fact or leave it out, state it!

•   Keep in mind that the purpose of a bug report is to enable someone to fix the bug if it is not known. It is not very important what happens if the bug is already known. Therefore, always write your bug reports on the assumption that the bug is not known.

•   Your bug report should be self-contained. Do not refer to information sent in previous mails; your previous mail may have been forwarded to somebody else.

•   Please report each bug in a separate message. This makes it easier for us to track which bugs have been fixed and to forward your bugs reports to the appropriate maintainer.

•   Please report bugs in English; this increases the chances of finding someone who can fix the bug. Do not assume one particular person will receive your bug report.

  What to Include in a Bug Report
To enable us to fix a DDD bug, you must include the following information:

•   Your DDD configuration. Invoke DDD as

      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.

•   The debugger you are using and its version (e.g., `gdb-4.16' or `dbx as shipped with Solaris 2.5').

•   The compiler you used to compile DDD and its version (e.g., `gcc-2.8.0').

•   A description of what behavior you observe that you believe is incorrect. For example, “DDD gets a fatal signal” or “DDD exits immediately after attempting to create the data window“.

•   A log file showing the interaction between DDD and the inferior debugger. This interaction is logged by default in `$HOME/.ddd/log'. Include all trace output from the DDD invocation up to the first bug occurrence.

•   If you wish to suggest changes to the DDD source, send us context diffs. If you even discuss something in the DDD source, refer to it by context, never by line number.

Be sure to include this information in every single bug report.

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

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

The original DDD had no source window; this was added by Dorothea during the winter of 1994/1995. In the first quarter of 1995, finally, Andreas completed DDD by adding command and execution windows, extensions for DBX and remote debugging as well as configuration support for several architectures. Since then, many people have contributed to the success of DDD; see 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: Persistent sessions, display shortcuts.

EXTENDING DDD
If you have any contributions to be incorporated into DDD, please send them to `ddd@ips.cs.tu-bs.de'. For suggestions on what might be done, see the file `TODO' in the DDD distribution.

DDD NEEDS YOUR SUPPORT!
DDD needs your support! If you have any success stories related to DDD, please write them down on a picture postcard and send them to us:

  Technische Universität Braunschweig
  Institut für Programmiersprachen
  und Informationssysteme
  Abteilung Softwaretechnologie
  Bültenweg 88
  D-38092 Braunschweig
  GERMANY

You may also leave a message in the DDD Guestbook. It is accessible via our DDD WWW page,

  http://www.cs.tu-bs.de/softech/ddd/ .

PRINTING THIS MANUAL
Invoke DDD with the `--manual' option to show this manual page on standard output. This text output is suitable for installation as formatted manual page (as `/usr/local/man/cat1/ddd.1' or similar) on UNIX systems.

A PostScript copy of this manual page, including several DDD screen shots and diagrams, is included in the DDD source distribution and available separately as `ddd.man.ps.gz' in

  ftp://ftp.ips.cs.tu-bs.de/pub/local/softech/ddd/doc/

This directory also contains other documentation related to DDD.

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.

COPYRIGHT
DDD is Copyright © 1995, 1996, 1997, 1998 Technische Universität Braunschweig, Germany.

DDD is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

DDD is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. See the License for more details.

You should have received a copy of the License along with DDD. If not, invoke DDD with the `--license' option; this will print a copy on standard output. To read the License from within DDD, use `Help | DDD License'.

This DDD manual page is Copyright © 1995, 1996, 1997, 1998 Technische Universität Braunschweig, Germany.

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.