\def\postscript{}\input texinfo @c -*- texinfo -*-
@c $Id$
@c DDD Manual

@c Copyright (C) 1999-2001 Universitaet Passau, Germany.
@c Copyright (C) 2001-2004 Universitaet des Saarlandes, Germany.
@c Copyright (C) 2006 Free Software Foundation, Inc.
@c
@c Sections on GNU Make, Bash, and Python
@c Copyright (C) 2005, 2006 Rocky Bernstein <rocky@gnu.org>
@c
@c Written by Andreas Zeller <zeller@gnu.org>.
@c 
@c This file is part of DDD.
@c 
@c DDD is free software; you can redistribute it and/or modify it under
@c the terms of the GNU General Public License as published by the Free
@c Software Foundation; either version 3 of the License, or (at your
@c option) any later version.
@c
@c This document is free documentation; you can redistribute it and/or 
@c modify it under the terms of the GNU Free Documentation License 
@c as published by the Free Software Foundation; either version 1.1 
@c of the License, or (at your option) any later version.
@c 
@c DDD is distributed in the hope that it will be useful, but WITHOUT ANY
@c WARRANTY; without even the implied warranty of MERCHANTABILITY or
@c FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
@c for more details. 
@c 
@c You should have received a copy of the GNU General Public License
@c along with DDD -- see the file COPYING.  If not, see
@c <http://www.gnu.org/licenses/>.
@c 
@c DDD is the data display debugger.
@c For details, see the DDD World-Wide-Web page, 
@c `http://www.gnu.org/software/ddd/',
@c or send a mail to the DDD developers <ddd@gnu.org>.

@c Note: This file contains 8-bit characters (ISO-8859-1 encoding).
@c Note: This file requires Texinfo 4.0 or later.

@c %**start of header

@setfilename ddd.info
@documentencoding ISO-8859-1

@c Configuration
@include config.texi

@c Macros
@include macros.texi

@settitle Debugging with @value{DDD}

@c !!set DDD manual's edition---not the same as DDD version!
@set EDITION First

@c !!set DDD manual's revision date
@set DATE 15 July, 2006

@c Index stuff
@c Labels
@defcodeindex lb
@c Commands
@defcodeindex cm
@c Authors
@defindex au
@c Files
@defcodeindex fl
@c Environment variables
@defcodeindex en

@c Combine authors and concepts
@synindex au cp

@c Combine environment variables and resources
@syncodeindex en vr

@c Combine programs and files
@syncodeindex pg fl


@c PDF settings
@iftex
@pdfcompresslevel=9
@pdfinfo{
    /Title (Debugging with DDD)
    /Author (Andreas Zeller et. al.)
    /Subject (DDD - the Data Display Debugger)
    /Keywords (Bash Debugging Debugger DDD GNU GDB DBX JDB Ladebug GNU Make 
               Perl Python WDB XDB)
}
@end iftex

@c Formatting
@setchapternewpage odd
@finalout

@c Info Dir settings
@dircategory Programming & development tools.
@direntry
* DDD: (ddd).                     The Data Display Debugger.
@end direntry
@c %**end of header


@ifinfo
@c This section is prepended to every info file.

@noindent

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

@noindent
This is the @value{EDITION} Edition, @value{DATE}, of @cite{Debugging
with @DDD{}} for @DDD{} Version @value{VERSION}.

@noindent
@group
Copyright @copyright{} 2004 Universität des Saarlandes @*
Lehrstuhl Softwaretechnik @*
Postfach 15 11 50 @*
66041 Saarbrücken @*
GERMANY

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

@noindent
@DDD{} and this manual are available via
@uref{http://www.gnu.org/software/ddd/, the @DDD{} @WWW{} page}.
@end group

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

Send questions, comments, suggestions, etc. to @email{ddd@@gnu.org}. @*
Send bug reports to @email{bug-ddd@@gnu.org}. @*
@end ifinfo


@c The title page.
@ifnothtml
@titlepage
@sp -7
@ifnottex
@title Debugging with @value{DDD}
@subtitle User's Guide and Reference Manual
@subtitle @value{EDITION} Edition, for @value{DDD} Version @value{VERSION}
@subtitle Last updated @value{DATE}
@author Andreas Zeller
@end ifnottex
@tex
\setfont\bigtitlesf\sfbshape{10}{\magstep4}
\title \bigtitlesf{Debugging with \value{DDD}}
\subtitle \textsf{User's Guide and Reference Manual}
\subtitle \textsf{\value{EDITION} Edition, for \value{DDD} Version \value{VERSION}}
\subtitle \textsf{Last updated \value{DATE}}
\sp 2
\author \titlesf{Andreas Zeller}
@end tex
@page
@tex
{\parskip=0pt
\hfill \textsf{Debugging with @value{DDD}}\par
\hfill \textsf{User's Guide and Reference Manual}\par
}
@end tex

@vskip 0pt plus 1filll
Copyright @copyright{} 2004 Universität des Saarlandes @*
Lehrstuhl Softwaretechnik @*
Postfach 15 11 50 @*
66041 Saarbrücken @*
GERMANY
@sp 1

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

@DDD{} and this manual are available via @*
@uref{http://www.gnu.org/software/ddd/, the @DDD{} @WWW{} page}.

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

Send questions, comments, suggestions, etc. to
@email{ddd@@gnu.org}. @*
Send bug reports to @email{bug-ddd@@gnu.org}. @*

@end titlepage
@end ifnothtml

@ifnottex
@c Main Info and HTML page.

@node Top
@top Debugging with @value{DDD}

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

This is the @value{EDITION} Edition of @cite{Debugging with
@DDD{}}, @value{DATE}, for @DDD{} Version @value{VERSION}.
@end ifnottex

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

@menu
* Summary::                     Summary of @DDD{}.

* Sample Session::              A sample @DDD{} session.
* Invocation::                  Getting in and out of @DDD{}.
* Windows::                     The @DDD{} windows, menus, and buttons.
* Navigating::                  Moving through the source code.
* Stopping::                    Making your program stop at specific locations.
* Running::                     Running programs under @DDD{}.
* Examining Data::              Examining variable values and data structures.
* Machine-Level Debugging::     Examining machine code and registers.
* Changing the Program::        Changing source and object code.
* Commands::                    Entering and editing @DDD{} commands.

* Application Defaults::        Resources used in @DDD{}.
* Bugs::                        How, when, and why to report @DDD{} bugs.
* Configuration Notes::         Configuration-specific notes.
* Dirty Tricks::                Room for your contributions.
* Extending::                   Extending @DDD{}.
* FAQ::                         Frequently Answered Questions.
* License::                     The @DDD{} license.
* Help and Assistance::         Mailing Lists and other resources.
* Documentation License::       The license of this document.

* Label Index::                 All labels shown on the @DDD{} @acronym{GUI}.
* Key Index::                   Keys used to control @DDD{}.
* Command Index::               Commands that can be typed within @DDD{}.
* Resource Index::              All resources and environment variables.
* File Index::                  All programs and files referenced by @DDD{}.
* Concept Index::               All concepts as mentioned in this manual.

@ifinfo

@detailmenu
 --- The Detailed Node Listing ---

Summary of @value{DDD}

* About this Manual::           Getting copies in various formats.
* Free Software::               How to copy and redistribute @DDD{}.
* Getting @DDD{}::              How to obtain copies of @DDD{}.
* Contributors::                Who has done all this?
* History::                     Old @DDD{} versions.

A Sample @value{DDD} Session

* Sample Program::              Source @file{sample.c}

Getting In and Out of @value{DDD}

* Invoking::                    How to invoke @DDD{}.
* Quitting::                    How to quit @DDD{}.
* Sessions::                    Saving work across invocations.
* Remote Debugging::            Running @DDD{} on a different host.
* Customizing Debugger Interaction::  How @DDD{} and @GDB{} communicate.

Invoking @value{DDD}

* Choosing an Inferior Debugger::  Which debugger to use?
* Options::                     How to invoke @DDD{}
* X Options::                   Setting X properties
* Inferior Debugger Options::   Customizing @GDB{}, @DBX{}, and so on
* Multiple Instances::          Running multiple @DDD{} instances
* X Warnings::                  Turning off obnoxious warnings

Inferior Debugger Options

* GDB Options::                 
* DBX and Ladebug Options::     
* XDB Options::                 
* JDB Options::                 
* PYDB Options::                
* Perl Options::                
* Bash Options::                
* GNU Make Options::                

Persistent Sessions

* Saving Sessions::             
* Resuming Sessions::           
* Deleting Sessions::           
* Customizing Sessions::        

Remote Debugging

* Remote Host::                 Running @DDD{} on a Remote Host
* Remote Debugger::             Using a Remote Inferior Debugger
* Remote Program::              Debugging a Remote Program

Using @value{DDD} with a Remote Inferior Debugger

* Customizing Remote Debugging::  

Customizing Interaction with the Inferior Debugger

* Debugger Invocation::         
* Debugger Initialization::     
* Debugger Communication::      

Initializing the Inferior Debugger

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

The @value{DDD} Windows

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

The Menu Bar

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

Customizing the Menu Bar

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

The Tool Bar

* Customizing the Tool Bar::    

The Command Tool

* Customizing the Command Tool::  
* Customizing Tool Position::   

Customizing the Command Tool

* Disabling the Command Tool::  

Command Tool Position

* Customizing Tool Decoration::  

Customizing @value{DDD}

* How Customizing Works::       
* Customizing Help::            
* Customizing Undo::            
* Customizing Windows::         
* Debugger Settings::           

How Customizing @value{DDD} Works

* Resources::                   
* Changing Resources::          
* Saving Options::              

Customizing @value{DDD} Help

* Button tips::                 Turning off tips.
* Tip of the day::              Turning off the tip of the day.
* Help Helpers::                Helper programs invoked by Help.

Customizing the @value{DDD} Windows

* Splash Screen::               Turning off the splash screen.
* Window Layout::               Re-arranging windows.
* Customizing Fonts::           Using alternate fonts.
* Toggling Windows::            Turning off windows.
* Text Fields::                 Popdown histories.
* Icons::                       Iconifying @DDD{} windows.
* Adding Buttons::              Create your own button set.
* More Customizations::         

Navigating through the Code

* Compiling for Debugging::     Always use `-g' to compile.
* Opening Files::               How to open a program for debugging.
* Looking up Items::            Searching files and functions.
* Customizing Source::          Arranging the source window.

Opening Files

* Opening Programs::            How to open a program for debugging.
* Opening Core Dumps::          Analyze a previous crash.
* Opening Source Files::        Open a source file of the program.
* Filtering Files::             @DDD{} only lists matching files.

Looking up Items

* Looking up Definitions::      Jump towards a specific item.
* Textual Search::              Search within the current source.
* Looking up Previous Locations::  Navigate back and forth.
* Source Path::                 Make @DDD{} know where to search.

Customizing the Source Window

* Customizing Glyphs::          
* Customizing Searching::       
* Customizing Source Appearance::  
* Customizing Source Scrolling::  
* Customizing Source Lookup::   
* Customizing File Filtering::  

Stopping the Program

* Breakpoints::                 Stop at a certain point.
* Watchpoints::                 Stop at a certain condition.
* Interrupting::                Stop manually.
* Stopping X Programs::         Take care of grabbed pointers!

Breakpoints

* Setting Breakpoints::         
* Deleting Breakpoints::        
* Disabling Breakpoints::       
* Temporary Breakpoints::       
* Editing Breakpoint Properties::  
* Breakpoint Conditions::       
* Breakpoint Ignore Counts::    
* Breakpoint Commands::         
* Moving and Copying Breakpoints::  
* Looking up Breakpoints::      
* Editing all Breakpoints::     
* Hardware-Assisted Breakpoints::  

Watchpoints

* Setting Watchpoints::         
* Editing Watchpoint Properties::  
* Editing all Watchpoints::     
* Deleting Watchpoints::        

Stopping X Programs

* Customizing Grab Checking::   

Running the Program

* Starting Program Execution::  
* Using the Execution Window::  
* Attaching to a Process::      
* Program Stop::                
* Resuming Execution::          
* Continuing Somewhere Else::   
* Stack::                       
* Undoing Program Execution::   
* Threads::                     
* Signals::                     
* Killing the Program::         

Starting Program Execution

* Arguments::                   Your program's arguments.
* Environment::                 Your program's environment.
* Working Directory::           Your program's directory.
* Input/Output::                Your program's I/O.

Using the Execution Window

* Customizing the Execution Window::  

Attaching to a Running Process

* Customizing Attaching to Processes::  

Examining the Stack

* Frames::                      Callers and callees.
* Backtraces::                  And you may ask yourself, `how did I get here?'
* Selecting a frame::           Moving up and down.

Examining Data

* Value Tips::                  Just move the pointer on a variable.
* Printing Values::             Printing a value in the debugger console.
* Displaying Values::           Displaying structures as graphs.
* Plotting Values::             Displaying values as plots.
* Examining Memory::            Low-level memory examination.

Displaying Complex Values in the Data Window

* Display Basics::              How to create, manipulate, and delete displays.
* Arrays::                      Special functions for arrays.
* Assignment::                  Setting variable values.
* Examining Structures::        Dereferencing pointers and other references.
* Customizing Displays::        Data Themes.
* Layouting the Graph::         Automatic layout.
* Printing the Graph::          Printing on paper.

Display Basics

* Creating Single Displays::    
* Selecting Displays::          
* Showing and Hiding Details::  
* Rotating Displays::           
* Displaying Local Variables::  
* Displaying Program Status::   
* Refreshing the Data Window::  
* Placement::                   
* Clustering::                  
* Creating Multiple Displays::  
* Editing all Displays::        
* Deleting Displays::           

Arrays

* Array Slices::                Displaying @var{from}..@var{to} parts of an array
* Repeated Values::             How repeated values are handled.
* Arrays as Tables::            Displaying two-dimensional arrays.

Examining Structures

* Dependent Values::            Edges from values to values.
* Dereferencing Pointers::      Examining pointer-based data structures.
* Shared Structures::           Multiple pointers to one display.
* Display Shortcuts::           Customize your own menus.

Customizing Displays

* Using Data Themes::           
* Applying Data Themes to Several Values::  
* Editing Themes::              
* Writing Data Themes::         
* Display Resources::           
* VSL Resources::               

Layouting the Graph

* Moving Displays::             
* Scrolling Data::              
* Aligning Displays::           
* Automatic Layout::            
* Rotating the Graph::          

Plotting Values

* Plotting Arrays::             Plotting 1-D and 2-D arrays.
* Plot Appearance::             Controlling the appearance.
* Scalars and Composites::      Plotting simple values.
* Plotting Histories::          Plotting the history of a variable.
* Printing Plots::              Printing on paper.
* Entering Plotting Commands::  Raw Gnuplot commands.
* Exporting Plot Data::         Processing data outside of @DDD{}
* Animating Plots::             Visualizing dynamic behaviour.
* Customizing Plots::           All at your leisure.

Customizing Plots

* Gnuplot Invocation::          
* Gnuplot Settings::            

Machine-Level Debugging

* Machine Code::                Examining machine code.
* Machine Code Execution::      Stepping across instructions.
* Registers::                   Examining registers.
* Customizing Machine Code::    Settings.

Changing the Program

* Editing Source Code::         You can invoke a source editor from @DDD{}.
* Recompiling::                 Invoking @code{make} from within @DDD{}.
* Patching::                    Changing source and object code.

Editing Source Code

* Customizing Editing::         
* In-Place Editing::            

The Command-Line Interface

* Entering Commands::           Direct interaction with the inferior debugger.
* TTY mode::                    Controlling @DDD{} from a terminal.
* Integrating @DDD{}::          @DDD{} and your programming environment.
* Defining Buttons::            Add your own @DDD{} buttons.
* Defining Commands::           Add your own @DDD{} commands.

Entering Commands

* Command Completion::          Using the @key{TAB} key.
* Command History::             Repeating previous commands.
* Typing in the Source Window::  

Defining Buttons

* Customizing Buttons::         Adding your own command buttons.

Defining Commands

* GDB Simple Commands::         
* GDB Argument Commands::       
* Commands with Other Debuggers::  

Application Defaults

* Actions::                     All actions used in translation tables.
* Images::                      All images used in resources,

Actions

* General Actions::             
* Data Display Actions::        
* Debugger Console Actions::    
* Source Window Actions::       

Bugs and How To Report Them

* Where to Send Bug Reports::   Our e-mail address.
* Is it a @DDD{} Bug?::         @DDD{} may not be at fault.
* How to Report Bugs::          Report all the facts.
* Bug Reports::                 Include all configuration information.
* Diagnostics::                 Maintaining @DDD{}

Getting Diagnostics

* Logging::                     @DDD{} logs all interactions.
* Debugging @DDD{}::            Facilities to debug @DDD{}.
* Customizing Diagnostics::     All diagnostics resources.

Logging

* Disabling Logging::           

Configuration Notes

* GDB::                         Using @DDD{} with @GDB{}
* DBX::                         Using @DDD{} with @DBX{}
* Ladebug::                     Using @DDD{} with Ladebug
* XDB::                         Using @DDD{} with @XDB{}
* JDB::                         Using @DDD{} with @JDB{}
* Perl::                        Using @DDD{} with Perl
* Bash::                        Using @DDD{} with Bash
* Make::                        Using @DDD{} with GNU Make
* LessTif::                     Using @DDD{} with LessTif

Using @value{DDD} with GDB

* WDB::                         Using @value{DDD} with WDB
* WindRiver GDB::               Using @value{DDD} with WindRiver GDB (Tornado)

@end detailmenu
@end ifinfo
@end menu

@ifnothtml
@shortcontents
@end ifnothtml
@contents

@ifhtml
@c This section comes below the summary in the HTML file.

@noindent
@group
Copyright @copyright{} 2004 Universität des Saarlandes @*
Lehrstuhl Softwaretechnik @*
Postfach 15 11 50 @*
66041 Saarbrücken @*
GERMANY

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

@noindent
@DDD{} and this manual are available via
@uref{http://www.gnu.org/software/ddd/, the @DDD{} @WWW{} page}.
@end group

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

Send questions, comments, suggestions, etc. to @email{ddd@@gnu.org}. @*
Send bug reports to @email{bug-ddd@@gnu.org}. @*
@end ifhtml


@c The actual content starts here.

@c No idea why this `@node' requires all links.
@node Summary, Sample Session, Top, Top
@unnumbered Summary of @value{DDD}

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

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

@itemize @bullet
@item
Start your program, specifying anything that might affect its behavior.
@item
Make your program stop on specified conditions.
@item
Examine what has happened, when your program has stopped.
@item
Change things in your program, so you can experiment with correcting the
effects of one bug and go on to learn about another.
@end itemize

@cindex Inferior debugger
@cindex Command-line debugger
Technically speaking, @DDD{} is a front-end to a command-line
debugger (called @dfn{inferior debugger}, because it lies at the layer
beneath @DDD{}).  @DDD{} supports the following inferior
debuggers:

@itemize @bullet
@item
To debug @emph{executable binaries}, you can use @DDD{} with @dfn{@GDB{}}, 
@dfn{@DBX{}}, @dfn{Ladebug}, or @dfn{@XDB{}}.

@itemize @minus{}
@item
@cindex @acronym{GDB}
@cindex C
@cindex C++
@cindex Modula-2
@cindex Modula-3
@cindex Pascal
@cindex Chill
@cindex Ada
@cindex FORTRAN
@dfn{@GDB{}}, the @GNU{} debugger, is the recommended inferior debugger
for @DDD{}.  @GDB{} supports native executables binaries originally
written in C, C++, Java, Modula-2, Modula-3, Pascal, Chill, Ada, and
FORTRAN.  (@pxref{Languages, Using @GDB{} with Different Languages,
Using @GDB{} with Different Languages, gdb, Debugging with @GDB{}}, for
information on language support in @GDB{}.)

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

@item
@cindex Ladebug
As an alternative to @GDB{} and @DBX{}, you can use @DDD{} with
@dfn{Ladebug}, as found on Compaq and DEC systems.  Ladebug offers fewer
features than @GDB{}, and some of the more advanced Ladebug features may
not be supported by @DDD{}.  However, using Ladebug may be useful if
@GDB{} or @DBX{} do not understand or fully support the debugging
information as generated by your compiler.@footnote{Within @DDD{} (and
this manual), Ladebug is considered a @DBX{} variant.  Hence, everything
said for @DBX{} also applies to Ladebug, unless stated otherwise.}

@item
@cindex @acronym{XDB}
As another alternative to @GDB{}, you can use @DDD{} with the
@dfn{@XDB{}} debugger, as found on @acronym{HP-UX}
systems.@footnote{@XDB{} will no longer be maintained in future @DDD{}
releases.  Use a recent @GDB{} version instead.}.
@end itemize

@item
@cindex @acronym{JDB}
@cindex Java
To debug @emph{Java byte code programs}, you can use @DDD{} with
@dfn{@JDB{}}, the Java debugger, as of @JDK{} 1.1 and later.
(@DDD{} has been tested with @JDK{} 1.1 and @JDK{} 1.2.)

@item
@item
@cindex Bash
To debug @emph{Bash programs}, you need a version Bash that supports
extended debugging support; see
@uref{http://bashdb.sourceforge.net}. It important to make sure you
get the right version of the debugger that matches your version of
Bash. For bash version 2.05b, you need a patched version of bash as
well as the debugger for bash.

@item
@cindex GNU Make
To debug @emph{GNU Make Makefiles}, you need a version GNU Make that supports
extended debugging support. To get this enhanced version see
@uref{http://bashdb.sourceforge.net/remake}.

@item
@cindex Perl
To debug @emph{Perl programs}, you can use @DDD{} with the @dfn{Perl
debugger,} as of Perl 5.003 and later.

@item
@cindex Python
@cindex pydb

To debug @emph{Python programs}, you need an extended version of the
python debugger called @dfn{@PYDB{}}. To get this, see
@uref{http://bashdb.sourceforge.net/pydb}.
@end itemize

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

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


@node About this Manual
@unnumberedsec About this Manual

This manual comes in several formats:

@itemize @bullet
@item
@cindex Info manual
The @emph{Info} format is used for browsing on character devices; it
comes without pictures.  You should have a local copy installed, which
you can browse via Emacs, the stand-alone @command{info} program, or from
@DDD{} via @samp{Help @result{} @DDD{} Reference}.

@flindex ddd-@value{VERSION}.tar.gz
The @DDD{} source distribution
@file{@value{ddd}-@value{VERSION}.tar.gz} contains this manual as
pre-formatted info files; you can also download them from @*
@uref{http://www.gnu.org/software/ddd/, the @DDD{} @WWW{} page}.

@item
@cindex PostScript manual
The @emph{PostScript} format is used for printing on paper; it comes
with pictures as well.  

The @DDD{} source distribution
@file{@value{ddd}-@value{VERSION}.tar.gz} contains this manual as
pre-formatted PostScript file; you can also download it from @*
@uref{http://www.gnu.org/software/ddd/, the @DDD{} @WWW{} page}.

@item
@cindex PDF manual
The @emph{PDF} format is used for printing on paper as well as for
online browsing; it comes with pictures as well.

The @DDD{} source distribution
@file{@value{ddd}-@value{VERSION}.tar.gz} contains this manual as
pre-formatted PDF file; you can also download it from @*
@uref{http://www.gnu.org/software/ddd/, the @DDD{} @WWW{} page}.

@item
@cindex HTML manual
The @emph{HTML} format is used for browsing on bitmap devices; it
includes several pictures.  You can view it using a HTML browser,
typically from a local copy.  

@flindex ddd-@value{VERSION}-html-manual.tar.gz
A pre-formatted HTML version of this manual comes
in a separate @DDD{} package @*
@file{@value{ddd}-@value{VERSION}-html-manual.tar.gz}; you can browse
and download it via @*
the @uref{http://www.gnu.org/software/ddd/, @DDD{} @WWW{} page}.
@end itemize

@cindex @TeX{}info manual
The manual itself is written in @TeX{}info format; its source code 
@file{ddd.texi} is contained in the @DDD{} source distribution
@file{@value{ddd}-@value{VERSION}.tar.gz}.

@flindex ddd-@value{VERSION}-pics.tar.gz
The picture sources come in a separate package
@file{@value{ddd}-@value{VERSION}-pics.tar.gz}; you need this package
only if you want to re-create the PostScript, HTML, or PDF versions.



@node Typographic Conventions
@unnumberedsec Typographic conventions

@table @asis
@item @key{Ctrl+A}
The name for a key on the keyboard (or multiple keys pressed simultaneously)

@item @kbd{run}
A sequence of characters to be typed on the keyboard.

@item @file{~/.@value{ddd}/init}
A file.

@item @samp{Help}
A graphical control element, such as a button or menu item.

@item @samp{File @result{} Open Program}
A sequence of menu items, starting at the top-level menu bar.

@item @code{argc - 1}
Program code or debugger command.

@item @option{-g}
A command-line option.

@item @code{$}
System prompt.

@item @code{(gdb) }
Debugger prompt.

@item @code{_}
Cursor position.

@item @var{version}
A metasyntactic variable; something that stands for another piece of
text.

@item @dfn{definition}
A definition.

@item @emph{caution}
Emphasis.

@item @strong{A warning}
Strong emphasis.

@item @acronym{DDD}
An acronym.
@end table

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

@example
(gdb) @kbd{break @var{location}}
Breakpoint @var{number} at @var{location}
(gdb) _
@end example



@node Free Software
@unnumberedsec Free software

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

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


@node Getting @DDD{}
@unnumberedsec Getting @value{DDD}

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

@table @file
@item @file{@value{ddd}-@var{version}.tar.gz}
@flindex ddd-@var{version}.tar.gz
The @DDD{} source distribution.  This should be all you need.

@item @file{@value{ddd}-@var{version}-html-manual.tar.gz}
@flindex ddd-@var{version}-html-manual.tar.gz
The @DDD{} manual in HTML format.  You need this only if you want to 
install a local copy of the @DDD{} manual in HTML format.

@item @file{@value{ddd}-@var{version}-pics.tar.gz}
@flindex ddd-@var{version}-pics.tar.gz
Sources of images included in the @DDD{} manual.  You need this
only if you want to recreate the @DDD{} manual.
@end table

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


@node Contributors
@unnumberedsec Contributors to @value{DDD}
@cindex Contributors

@auindex Zeller, Andreas
@auindex Lütkehaus, Dorothea
@flindex ChangeLog
@flindex TODO
Dorothea Lütkehaus and Andreas Zeller were the original authors of
@DDD{}.  Many others have contributed to its development.  The
files @file{ChangeLog} and @file{THANKS} in the @DDD{} distribution
approximates a blow-by-blow account.



@node History
@unnumberedsec History of @value{DDD}
@cindex History

@auindex Zeller, Andreas
@cindex PSG
The history of @DDD{} is a story of code recycling.  The oldest parts of
@DDD{} were written in 1990, when @emph{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 @acronym{PSG}.

@auindex Lütkehaus, Dorothea
@cindex NORA
@cindex Box library
@cindex VSL
In 1992, the @VSL{} and Box libraries were recycled for the
@acronym{NORA} project.  For @acronym{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,
@emph{Dorothea Lütkehaus} (now @emph{Dorothea Krabiell}) realized @DDD{}
as her Diploma Thesis, 1994.

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

Major @DDD{} events:

@table @asis
@item April, 1995
@DDD{} 0.9: First @DDD{} beta release.

@item May, 1995
@DDD{} 1.0: First public @DDD{} release.

@item December, 1995
@DDD{} 1.4: Machine-level debugging, glyphs, Emacs integration.

@item October, 1996
@DDD{} 2.0: Color displays, @XDB{} support, generic @DBX{} support,
command tool.

@item May, 1997
@DDD{} 2.1: Alias detection, button tips, status displays.

@item November, 1997
@DDD{} 2.2: Sessions, display shortcuts.

@item June, 1998
@DDD{} 3.0: Icon tool bar, Java support, @JDB{} support.

@item December, 1998
@DDD{} 3.1: Data plotting, Perl support, Python support, Undo/Redo.

@item January, 2000
@DDD{} 3.2: New manual, Readline support, Ladebug support.

@item January, 2001
@DDD{} 3.3: Data themes, JDB 1.2 support, VxWorks support.

@item November, 2002
@DDD{} 3.3.2: Bash support.

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

@item Dec, 2005
@DDD{} 3.3.12-test: GNU Make support added.

@item Feb, 2006
@DDD{} 3.3.12-test3: Modernize Python debugging 
@end table


@node Sample Session
@chapter A Sample @value{DDD} Session

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

@pindex sample
@flindex sample.c
The sample program @file{sample.c} (@pxref{Sample Program}) exhibits the
following bug.  Normally, @command{sample} should sort and print its
arguments numerically, as in the following example:

@example
$ @kbd{./sample 8 7 5 4 1 3}
1 3 4 5 7 8
$ _
@end example

However, with certain arguments, this goes wrong:

@example
$ @kbd{./sample 8000 7000 5000 1000 4000}
1000 1913 4000 5000 7000
$ _
@end example

Although the output is sorted and contains the right number of
arguments, some arguments are missing and replaced by bogus numbers;
here, @code{8000} is missing and replaced by
@code{1913}.@footnote{Actual numbers and behavior on your system may
vary.}

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

@example
$ @kbd{gcc -g -o sample sample.c}
$ _
@end example

@menu
* Sample Program::              Source @file{sample.c}
@end menu

Now, you can invoke @DDD{} (@pxref{Invocation}) on the
@command{sample} executable:

@example
$ @kbd{ddd sample}
@end example

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

@ifnotinfo
@sp 1
@center @image{PICS/tut-invoke, 16cm}
@sp 1
@end ifnotinfo

The @dfn{Debugger Console} (at the bottom) contains @DDD{} version
information as well as a @GDB{} prompt.@footnote{Re-invoke @DDD{} with
@option{--gdb}, if you do not see a @samp{(gdb)} prompt here
(@pxref{Choosing an Inferior Debugger})}

@example
GNU @value{DDD} Version @value{VERSION}, by Dorothea Lütkehaus and Andreas Zeller.
Copyright @copyright{} 1995-1999 Technische Universität Braunschweig, Germany.
Copyright @copyright{} 1999-2001 Universität Passau, Germany.
Copyright @copyright{} 2001-2004 Universität des Saarlandes, Germany.
Reading symbols from sample@dots{}done.
(gdb) _
@end example

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

@page
The next thing to do is to actually @dfn{execute} the program, such that
you can examine its behavior (@pxref{Running}).  Select @samp{Program
@result{} Run} to execute the program; the @samp{Run Program} dialog
appears.

@ifnotinfo
@sp 1
@center @image{PICS/tut-run, 16cm}
@sp 1
@end ifnotinfo

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

@GDB{} now starts @command{sample}.  Execution stops after a few moments as
the breakpoint is reached.  This is reported in the debugger console.

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

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

The current execution line is indicated by a green arrow.

@example
@result{} a = (int *)malloc((argc - 1) * sizeof(int));
@end example

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

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

@ifnotinfo
@sp 1
@center @image{PICS/tut-value, 16cm}
@sp 1
@end ifnotinfo

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

@example
(gdb) print a[0]
$1 = 0
(gdb) _
@end example

@noindent
or some other value (note that @samp{a} has only been allocated, but the 
contents have not yet been initialized).

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

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

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

@ifnotinfo
@sp 1
@center @image{PICS/tut-display, 16cm}
@sp 1
@end ifnotinfo

Now comes the assignment of @samp{a}'s members:

@example
@result{}  for (i = 0; i < argc - 1; i++)
        a[i] = atoi(argv[i + 1]);
@end example

You can now click on @samp{Next} and @samp{Next} again to see how the
individual members of @samp{a} are being assigned.  Changed members are
highlighted.

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

@example
@result{}  shell_sort(a, argc);
@end example

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

@example
@result{}  for (i = 0; i < argc - 1; i++)
        printf("%d ", a[i]);
@end example

@noindent
and you see that after @samp{shell_sort} has finished, the contents of
@samp{a} are @samp{1000, 1913, 4000, 5000, 7000}---that is,
@samp{shell_sort} has somehow garbled the contents of @samp{a}.

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

Once more, @DDD{} ends up before the call to @samp{shell_sort}:
@example
@result{}  shell_sort(a, argc);
@end example

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

@example
@result{} int h = 1;
@end example

while the debugger console tells us the function just entered:

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

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

@ifnotinfo
@sp 1
@center @image{PICS/tut-backtrace, 16cm}
@sp 1
@end ifnotinfo

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

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

Surprise!  Where does this additional value @code{1913} come from?  The
answer is simple: The array size as passed in @samp{size} to
@samp{shell_sort} is @emph{too large by one}---@code{1913} is a bogus
value which happens to reside in memory after @samp{a}.  And this last
value is being sorted in as well.

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

@ifnotinfo
@sp 1
@center @image{PICS/tut-set, 16cm}
@sp 1
@end ifnotinfo

Change the value of @samp{size} to @code{5} and click on @samp{OK}.
Then, click on @samp{Finish} to resume execution of the
@samp{shell_sort} function:

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

@page
Success!  The @samp{a} display now contains the correct values
@samp{1000, 4000, 5000, 7000, 8000}.  

@ifnotinfo
@sp 1
@center @image{PICS/tut-finish, 16cm}
@sp 1
@end ifnotinfo

You can verify that these values are actually printed to standard output
by further executing the program.  Click on @samp{Cont} to continue
execution.

@example
(gdb) cont
1000 4000 5000 7000 8000 

Program exited normally.
(gdb) _
@end example

The message @samp{Program exited normally.} is from @GDB{}; it indicates
that the @command{sample} program has finished executing.

Having found the problem cause, you can now fix the source code.  Click
on @samp{Edit} to edit @file{sample.c}, and change the line

@example
shell_sort(a, argc);
@end example

@noindent
to the correct invocation

@example
shell_sort(a, argc - 1);
@end example

You can now recompile @command{sample}

@example
$ @kbd{gcc -g -o sample sample.c}
$ _
@end example

@noindent
and verify (via @samp{Program @result{} Run Again}) that @command{sample}
works fine now.

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

Program exited normally.
(gdb) _
@end example

All is done; the program works fine now.  You can end this @DDD{}
session with @samp{Program @result{} Exit} or @kbd{Ctrl+Q}.


@page
@node Sample Program
@section Sample Program

@flindex sample.c
Here's the source @file{sample.c} of the sample program.

@noindent
@smallexample
@cartouche
/* sample.c -- Sample C program to be debugged with @DDD{} */

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

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

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

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

    shell_sort(a, argc);

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

    free(a);
    return 0;
@}
@end cartouche
@end smallexample


@node Invocation
@chapter Getting In and Out of @value{DDD}

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

@itemize @bullet
@item 
Type @samp{@value{ddd}} to start @DDD{} (@pxref{Invoking}).
@item 
@kindex Ctrl+Q
Use @samp{File @result{} Exit} or @kbd{Ctrl+Q} to exit (@pxref{Quitting}).
@end itemize

@menu
* Invoking::                    How to invoke @DDD{}.
* Quitting::                    How to quit @DDD{}.
* Sessions::                    Saving work across invocations.
* Remote Debugging::            Running @DDD{} on a different host.
* Customizing Debugger Interaction::  How @DDD{} and @GDB{} communicate.
@end menu

@node Invoking
@section Invoking @value{DDD}
@cindex Invoking

Normally, you can run @DDD{} by invoking the program
@command{@value{ddd}}.

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

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

@example
@value{ddd} @var{program}
@end example

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

@example
@value{ddd} @var{program} @var{core}
@end example

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

@example
@value{ddd} @var{program} 1234
@end example

@noindent
would attach @DDD{} to process @code{1234} (unless you also have a file
named @file{1234}; @DDD{} does check for a core file first).

@cindex Option
You can further control @DDD{} by invoking it with specific
@dfn{options}.  To get a list of @DDD{} options, invoke @DDD{}
as

@example
@value{ddd} --help
@end example

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

@DDD{} also understands the usual X options such as @option{-display}
or @option{-geometry}.  @xref{X Options}, for details.

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

@menu
* Choosing an Inferior Debugger::  Which debugger to use?
* Options::                     How to invoke @DDD{}
* X Options::                   Setting X properties
* Inferior Debugger Options::   Customizing @GDB{}, @DBX{}, and so on
* Multiple Instances::          Running multiple @DDD{} instances
* X Warnings::                  Turning off obnoxious warnings
@end menu


@node Choosing an Inferior Debugger
@subsection Choosing an Inferior Debugger

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

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

@itemize @bullet
@item 
If the program requires a specific interpreter, such as Bash, Java,
GNU Make, Perl, or Python, then you should use a Bash, @JDB{}, GNU
Make, Perl, @PYDB{}, Bash, or inferior debugger.

Use

@cindex Bash, invoking @DDD{} with
@example
@value{ddd} --bash @var{program}
@value{ddd} --interpreter='@emph{path-to-debugger-bash} --debugger' @var{program}
@end example

@cindex @acronym{JDB}, invoking @DDD{} with
@example
@value{ddd} --jdb @var{program}
@end example

@cindex GNU Make, invoking @DDD{} with
@example
@value{ddd} --make @var{program}
@value{ddd} --interpreter='@emph{path-to-debugger-make} --debugger' @var{program}
@end example

@cindex Perl, invoking @DDD{} with
@example
@value{ddd} --perl @var{program}
@end example

@cindex @acronym{PYDB}, invoking @DDD{} with
@example
@value{ddd} --pydb @var{program}
@end example

@noindent
to run @DDD{} with @JDB{}, @PYDB{}, Perl, Bash, or GNU Make as an inferior
debugger.

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

Use

@cindex @acronym{DBX}, invoking @DDD{} with
@example
@value{ddd} --dbx @var{program}
@end example

@cindex @acronym{GDB}, invoking @DDD{} with
@example
@value{ddd} --gdb @var{program}
@end example

@cindex Ladebug, invoking @DDD{} with
@example
@value{ddd} --ladebug @var{program}
@end example

@cindex @acronym{WDB}, invoking @DDD{} with
@example
@value{ddd} --wdb @var{program}
@end example

@cindex @acronym{XDB}, invoking @DDD{} with
@example
@value{ddd} --xdb @var{program}
@end example

@noindent
to run @DDD{} with @GDB{}, @WDB{}, @DBX{}, Ladebug, or @XDB{} as
inferior debugger.
@end itemize


If you invoke @DDD{} without any of these options, but give a
@var{program} to analyze, then @DDD{} will automatically determine
the inferior debugger:

@itemize @bullet
@item
If @var{program} is a Python program, a Perl script, or a Java class,
@DDD{} will invoke the appropriate debugger.

@item
If @var{program} is an executable binary, @DDD{} will invoke its
default debugger for executables (usually @GDB{}).
@end itemize

@xref{Customizing Debugger Interaction}, for more details on determining
the inferior debugger.


@node Options
@subsection @value{DDD} Options

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

@table @option
@item --attach-windows
Attach the source and data windows to the debugger console, creating
one single big @DDD{} window.  This is the default setting.

Giving this option is equivalent to setting the @DDD{}
@samp{Separate} resource class to @samp{off}.  @xref{Window Layout}, for
details.

@item --attach-source-window
Attach only the source window to the debugger console.

Giving this option is equivalent to setting the @DDD{}
@samp{separateSourceWindow} resource to @samp{off}.  
@xref{Window Layout}, for details.

@item --attach-data-window
Attach only the source window to the debugger console.

Giving this option is equivalent to setting the @DDD{}
@samp{separateDataWindow} resource to @samp{off}.  @xref{Window Layout},
for details.

@item --automatic-debugger
Determine the inferior debugger automatically from the given arguments.

Giving this option is equivalent to setting the @DDD{}
@samp{autoDebugger} resource to @samp{on}.  
@xref{Customizing Debugger Interaction}, for details.

@item --button-tips
Enable button tips.

Giving this option is equivalent to setting the @DDD{}
@samp{buttonTips} resource to @samp{on}.  @xref{Customizing Help}, for
details.


@item --configuration
Print the @DDD{} configuration settings on standard output and
exit.

Giving this option is equivalent to setting the @DDD{}
@samp{showConfiguration} resource to @samp{on}.  @xref{Diagnostics}, for
details.



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

Giving this option is equivalent to setting the @DDD{}
@samp{checkConfiguration} resource to @samp{on}.  @xref{Diagnostics},
for details.


@item --data-window
Open the data window upon start-up.

Giving this option is equivalent to setting the @DDD{}
@samp{openDataWindow} resource to @samp{on}.  @xref{Toggling Windows},
for details.



@item --dbx
Run @DBX{} as inferior debugger.

Giving this option is equivalent to setting the @DDD{}
@samp{debugger} resource to @samp{dbx}.  
@xref{Customizing Debugger Interaction}, for details.


@item --debugger @var{name}
@pindex dbx
@pindex gdb
@pindex ladebug
@pindex jdb
@pindex mdb
@pindex perl
@pindex pydb
@pindex wdb
@pindex xdb
Invoke the inferior debugger @var{name}.  This is useful if you have
several debugger versions around, or if the inferior debugger cannot be
invoked under its usual name (i.e. @command{gdb}, @command{wdb},
@command{dbx}, @command{xdb}, @command{jdb}, @command{pydb}, or
@command{perl}).

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

@example
@value{ddd} --debugger "xdb -d @var{directory}"
@end example

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

Giving this option is equivalent to setting the @DDD{}
@samp{debuggerCommand} resource to @var{name}.  @xref{Customizing
Debugger Interaction}, for details.


@item --debugger-console
Open the debugger console upon start-up.

Giving this option is equivalent to setting the @DDD{}
@samp{openDebuggerConsole} resource to @samp{on}.  @xref{Toggling
Windows}, for details.


@item --disassemble
Disassemble the source code.  See also the @option{--no-disassemble}
option, below.

Giving this option is equivalent to setting the @DDD{}
@samp{disassemble} resource to @samp{on}.  @xref{Customizing Source},
for details.


@item --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.  @xref{Using the Execution Window}, for details.

Giving this option is equivalent to setting the @DDD{}
@samp{separateExecWindow} resource to @samp{on}.  @xref{Customizing
the Execution Window}, for details.


@item --font @var{fontname}
@itemx -fn @var{fontname}
Use @var{fontname} as default font.

Giving this option is equivalent to setting the @DDD{}
@samp{defaultFont} resource to @samp{fontname}.  @xref{Customizing
Fonts}, for details.


@item --fonts
Show the font definitions used by @DDD{} on standard output.

Giving this option is equivalent to setting the @DDD{}
@samp{showFonts} resource to @samp{on}.  @xref{Diagnostics}, for
details.


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

Giving this option is equivalent to setting the @DDD{}
@samp{FontSize} resource class to @samp{size}.  @xref{Customizing
Fonts}, for details.


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

Giving this option is equivalent to setting the @DDD{}
@samp{TTYMode} resource class to @samp{on}.  @xref{TTY mode}, for
details.


@item --gdb
Run @GDB{} as inferior debugger.

Giving this option is equivalent to setting the @DDD{}
@samp{debugger} resource to @samp{gdb}.  @xref{Customizing Debugger Interaction},
for details.


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

Giving this option is equivalent to setting the @DDD{}
@samp{displayGlyphs} resource to @samp{on}.  @xref{Customizing Source},
for details.



@item --help
@itemx -h
@itemx -?
Give a list of frequently used options.  Show options of the inferior
debugger as well.

Giving this option is equivalent to setting the @DDD{}
@samp{showInvocation} resource to @samp{on}.  @xref{Diagnostics}, for
details.


@item --host @var{hostname}
@itemx --host @var{username}@@@var{hostname}
Invoke the inferior debugger directly on the remote host @var{hostname}.
If @var{username} is given and the @option{--login} option is not used,
use @var{username} as remote user name.  @xref{Remote Debugger}, for
details.

Giving this option is equivalent to setting the @DDD{}
@samp{debuggerHost} resource to @var{hostname}.  @xref{Remote Debugger},
for details.

@item --jdb
Run @JDB{} as inferior debugger.

Giving this option is equivalent to setting the @DDD{}
@samp{debugger} resource to @samp{jdb}.  @xref{Customizing Debugger Interaction},
for details.


@item --ladebug
Run Ladebug as inferior debugger.

Giving this option is equivalent to setting the @DDD{}
@samp{debugger} resource to @samp{ladebug}.  @xref{Customizing Debugger
Interaction}, for details.



@item --lesstif-hacks
Equivalent to @option{--lesstif-version 999}.  Deprecated.

Giving this option is equivalent to setting the @DDD{}
@samp{lessTifVersion} resource to @code{999}.  @xref{LessTif}, for
details.



@item --lesstif-version @var{version}
Enable some hacks to make @DDD{} run properly with LessTif.
@xref{LessTif}, for a discussion.

Giving this option is equivalent to setting the @DDD{}
@samp{lessTifVersion} resource to @var{version}.  @xref{LessTif}, for
details.


@item --license
@cindex License, showing on standard output
Print the @DDD{} license on standard output and exit.

Giving this option is equivalent to setting the @DDD{}
@samp{showLicense} resource to @var{on}.  @xref{Diagnostics}, for
details.



@item --login @var{username}
@itemx -l @var{username}
Use @var{username} as remote user name.  @xref{Remote Debugger}, for details.

Giving this option is equivalent to setting the @DDD{}
@samp{debuggerHostLogin} resource to @var{username}.  @xref{Remote
Debugger}, for details.


@item --maintenance
Enable the top-level @samp{Maintenance} menu with options for debugging
@DDD{}.  @xref{Maintenance Menu}, for details.

Giving this option is equivalent to setting the @DDD{}
@samp{maintenance} resource to @var{on}.  @xref{Maintenance Menu}, for
details.


@item --manual
@cindex Manual, showing on standard output
Print the @DDD{} manual on standard output and exit.

Giving this option is equivalent to setting the @DDD{}
@samp{showManual} resource to @var{on}.  @xref{Diagnostics}, for
details.



@item --news
@cindex News, showing on standard output
Print the @DDD{} news on standard output and exit.

Giving this option is equivalent to setting the @DDD{}
@samp{showNews} resource to @var{on}.  @xref{Diagnostics}, for details.



@item --no-button-tips
Disable button tips.

Giving this option is equivalent to setting the @DDD{}
@samp{buttonTips} resource to @samp{off}.  @xref{Customizing Help}, for
details.

@item --no-data-window
Do not open the data window upon start-up.

Giving this option is equivalent to setting the @DDD{}
@samp{openDataWindow} resource to @samp{off}.  @xref{Toggling Windows},
for details.


@item --no-debugger-console
Do not open the debugger console upon start-up.

Giving this option is equivalent to setting the @DDD{}
@samp{openDebuggerConsole} resource to @samp{off}.  @xref{Toggling
Windows}, for details.



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

Giving this option is equivalent to setting the @DDD{}
@samp{disassemble} resource to @samp{off}.  @xref{Customizing Source},
for details.


@item --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.  @xref{Using the
Execution Window}, for details.

Giving this option is equivalent to setting the @DDD{}
@samp{separateExecWindow} resource to @samp{off}.  @xref{Customizing the
Execution Window}, for details.


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

Giving this option is equivalent to setting the @DDD{}
@samp{displayGlyphs} resource to @samp{off}.  @xref{Customizing Source},
for details.


@item --no-lesstif-hacks
Equivalent to @option{--lesstif-version 1000}.  Deprecated.

Giving this option is equivalent to setting the @DDD{}
@samp{lessTifVersion} resource to @code{1000}.  @xref{LessTif}, for
details.


@item --no-maintenance
Do not enable the top-level @samp{Maintenance} menu with options for
debugging @DDD{}.  This is the default.  @xref{Maintenance Menu},
for details.

Giving this option is equivalent to setting the @DDD{}
@samp{maintenance} resource to @var{off}.  @xref{Maintenance Menu}, for
details.




@item --no-source-window
Do not open the source window upon start-up.

Giving this option is equivalent to setting the @DDD{}
@samp{openSourceWindow} resource to @samp{off}.  @xref{Toggling
Windows}, for details.



@item --no-value-tips
Disable value tips.

Giving this option is equivalent to setting the @DDD{}
@samp{valueTips} resource to @samp{off}.  @xref{Value Tips}, for
details.



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


@item --perl
Run Perl as inferior debugger.

Giving this option is equivalent to setting the @DDD{}
@samp{debugger} resource to @samp{perl}.  @xref{Customizing Debugger Interaction},
for details.

@item --pydb
Run @PYDB{} as inferior debugger.

Giving this option is equivalent to setting the @DDD{}
@samp{debugger} resource to @samp{pydb}.  @xref{Customizing Debugger Interaction},
for details.


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

Giving this option is equivalent to setting the @DDD{}
@samp{pannedGraphEditor} resource to @samp{on}.  @xref{Display
Resources}, for details.



@item --play-log @var{log-file}
Recapitulate a previous @DDD{} session.

@example
@value{ddd} --play-log @var{log-file}
@end example

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

Giving this option is equivalent to setting the @DDD{}
@samp{playLog} resource to @samp{on}.  @xref{Customizing Debugger Interaction}, for
details.


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


@item --rhost @var{hostname}
@itemx --rhost @var{username}@@@var{hostname}
Run the inferior debugger interactively on the remote host
@var{hostname}.  If @var{username} is given and the @option{--login}
option is not used, use @var{username} as remote user name.
@xref{Remote Debugger}, for details.

Giving this option is equivalent to setting the @DDD{}
@samp{debuggerRHost} resource to @var{hostname}.  @xref{Remote
Debugger}, for details.


@item --scrolled-graph-editor
Use M*tif scroll bars to scroll the data window.  This is the default in
most @DDD{} configurations.  @xref{Display Resources}, for details;
see also @option{--panned-graph-editor}, above.

Giving this option is equivalent to setting the @DDD{}
@samp{pannedGraphEditor} resource to @samp{off}.  @xref{Display
Resources}, for details.


@item --separate-windows
@itemx --separate
Separate the console, source and data windows.  See also the
@option{--attach} options, above.

Giving this option is equivalent to setting the @DDD{}
@samp{Separate} resource class to @samp{off}.  @xref{Window Layout}, for
details.



@item --session @var{session}
@cindex Session, setting when invoking @DDD{}
Load @var{session} upon start-up.  @xref{Resuming Sessions}, for
details.

Giving this option is equivalent to setting the @DDD{}
@samp{session} resource to @var{session}.  @xref{Resuming Sessions}, for
details.


@item --source-window
Open the source window upon start-up.

Giving this option is equivalent to setting the @DDD{}
@samp{openSourceWindow} resource to @samp{on}.  @xref{Toggling Windows},
for details.


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

Giving this option is equivalent to setting the @DDD{}
@samp{statusAtBottom} resource to @samp{on}.  @xref{Window Layout}, for
details.


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

Giving this option is equivalent to setting the @DDD{}
@samp{statusAtBottom} resource to @samp{off}.  @xref{Window Layout}, for
details.


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

Giving this option is equivalent to setting the @DDD{}
@samp{synchronousDebugger} resource to @samp{on}.  @xref{Customizing
Debugger Interaction}, for details.


@item --toolbars-at-bottom
Place the toolbars at the bottom of the respective window.

Giving this option is equivalent to setting the @DDD{}
@samp{toolbarsAtBottom} resource to @samp{on}.  @xref{Window Layout},
for details.



@item --toolbars-at-top
Place the toolbars at the top of the respective window.

Giving this option is equivalent to setting the @DDD{}
@samp{toolbarsAtBottom} resource to @samp{off}.  @xref{Window Layout},
for details.


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

Giving this option is equivalent to setting the @DDD{} @samp{trace}
resource to @var{on}.  @xref{Diagnostics}, for details.



@item --tty
@itemx -t
@cindex @acronym{TTY} mode, setting when invoking @DDD{}
Enable @TTY{} interface, taking additional debugger commands from
standard input and forwarding debugger output on standard output.
Current positions are issued in a format readable for humans.  By
default, the debugger console is disabled.

Giving this option is equivalent to setting the @DDD{}
@samp{ttyMode} resource to @samp{on}.  @xref{TTY mode}, for details.


@item --value-tips
Enable value tips.

Giving this option is equivalent to setting the @DDD{}
@samp{valueTips} resource to @samp{on}.  @xref{Value Tips}, for details.


@item --version
@itemx -v
Print the @DDD{} version on standard output and exit.

Giving this option is equivalent to setting the @DDD{}
@samp{showVersion} resource to @samp{on}.  @xref{Diagnostics}, for
details.


@item --vsl-library @var{library}
Load the @VSL{} library @var{library} instead of using the
@DDD{} built-in library.  This is useful for customizing
display shapes and fonts.

Giving this option is equivalent to setting the @DDD{} @samp{vslLibrary}
resource to @var{library}.  @xref{VSL Resources}, for details.


@item --vsl-path @var{path}
Search @VSL{} libraries in @var{path} (a colon-separated directory list).

Giving this option is equivalent to setting the @DDD{} @samp{vslPath}
resource to @var{path}.  @xref{VSL Resources}, for details.


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


@item --wdb
Run @WDB{} as inferior debugger.

Giving this option is equivalent to setting the @DDD{}
@samp{debugger} resource to @samp{wdb}.  @xref{Customizing Debugger
Interaction}, for details.


@item --xdb
Run @XDB{} as inferior debugger.

Giving this option is equivalent to setting the @DDD{}
@samp{debugger} resource to @samp{xdb}.  @xref{Customizing Debugger
Interaction}, for details.
@end table


@node X Options
@subsection X Options

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

@table @option
@item -display @var{display}
@cindex Display, setting when invoking @DDD{}
@enindex DISPLAY
Use the X server @var{display}.  By default, @var{display} is taken from 
the @env{DISPLAY} environment variable.

@item -geometry @var{geometry}
Specify the initial size and location of the debugger console.

@item -iconic
@cindex Icon, invoking @DDD{} as
Start @DDD{} iconified.

@item -name @var{name}
Give @DDD{} the name @var{name}.

@item -selectionTimeout @var{timeout}
Specify the timeout in milliseconds within which two communicating
applications must respond to one another for a selection request.

@item -title @var{name}
Give the @DDD{} window the title @var{name}.

@item -xrm @var{resourcestring}
Specify a resource name and value to override any defaults.
@cindex Resource, setting when invoking @DDD{}
@end table


@node Inferior Debugger Options
@subsection Inferior Debugger Options

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

@menu
* GDB Options::                 
* DBX and Ladebug Options::     
* XDB Options::                 
* JDB Options::                 
* Bash Options::                
* GNU Make Options::                
* Perl Options::                
* PYDB Options::                
@end menu

@node GDB Options
@subsubsection GDB Options

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

@table @option
@item -b @var{baudrate}
Set serial port baud rate used for remote debugging.

@item --cd @var{dir}
Change current directory to @var{dir}.

@item --command @var{file}
Execute @GDB{} commands from @var{file}.

@item --core @var{corefile}
Analyze the core dump @var{corefile}.

@item --directory @var{dir}
@itemx -d @var{dir}
Add @var{directory} to the path to search for source files.

@item --exec @var{execfile}
Use @var{execfile} as the executable.

@item --mapped
Use mapped symbol files if supported on this system.

@item --nx
@item -n
@flindex .gdbinit
Do not read @file{.gdbinit} file.

@item --readnow
Fully read symbol files on first access.

@item --se @var{file}
Use @var{file} as symbol file and executable file.

@item --symbols @var{symfile}
Read symbols from @var{symfile}.
@end table

@xref{Invoking GDB, Invoking GDB, Invoking GDB, gdb, Debugging with
GDB}, for further options that can be used with @GDB{}.


@node DBX and Ladebug Options
@subsubsection DBX and Ladebug Options

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


@node XDB Options
@subsubsection XDB Options

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

@table @option
@item -d @var{dir}
Specify @var{dir} as an alternate directory where source files are
located.

@item -P @var{process-id}
Specify the process ID of an existing process the user wants to debug.

@item -l @var{library}
Pre-load information about the shared library @var{library}.  @option{-l
ALL} means always pre-load shared library information.

@item -S @var{num}
Set the size of the string cache to @var{num} bytes (default is 1024,
which is also the minimum).

@item -s
Enable debugging of shared libraries.
@end table

Further options can be found in the @cite{xdb(1)} manual page.



@node JDB Options
@subsubsection JDB Options

@subsubheading JDB as of JDK 1.2

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

@table @option
@item -attach @var{address}
@cindex VM
@cindex virtual machine
attach to a running virtual machine (VM)
at @var{address} using standard connector

@item -listen @var{address}
wait for a running VM to connect at @var{address} using standard connector

@item -listenany
wait for a running VM to connect at any available address using 
standard connector

@item -launch
launch VM immediately instead of waiting for @samp{run} command
@end table

These @JDB{} options are forwarded to the debuggee:

@table @option
@item -verbose[:class|gc|jni]
@itemx -v
Turn on verbose mode.

@item -D@var{name}=@var{value}
Set the system property @var{name} to @var{value}.

@item -classpath @var{path}
List directories in which to look for classes.  @var{path} is a list of 
directories separated by colons.

@item -X @var{option}
Non-standard target VM option
@end table



@subsubheading JDB as of JDK 1.1

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

@table @option
@item -host @var{hostname}
host machine of interpreter to attach to

@item -password @var{psswd}
password of interpreter to attach to (from @option{-debug})
@end table

These @JDB{} options are forwarded to the debuggee:

@table @option
@item -verbose
@itemx -v
Turn on verbose mode.

@item -debug
Enable remote Java debugging,

@item -noasyncgc
Don't allow asynchronous garbage collection.

@item -verbosegc
Print a message when garbage collection occurs.

@item -noclassgc
Disable class garbage collection.

@item -checksource
@itemx -cs
Check if source is newer when loading classes.

@item -ss @var{number}
Set the maximum native stack size for any thread.

@item -oss @var{number}
Set the maximum Java stack size for any thread.

@item -ms @var{number}
Set the initial Java heap size.

@item -mx @var{number}
Set the maximum Java heap size.

@item -D@var{name}=@var{value}
Set the system property @var{name} to @var{value}.

@item -classpath @var{path}
List directories in which to look for classes.  @var{path} is a list of 
directories separated by colons.

@item -prof
@itemx -prof:@var{file}
@flindex java.prof
Output profiling data to @file{./java.prof}.  If @var{file} is given,
write the data to @file{./@var{file}}.

@item -verify
Verify all classes when read in.

@item -verifyremote
Verify classes read in over the network (default).

@item -noverify
Do not verify any class.

@item -dbgtrace
Print info for debugging @JDB{}.
@end table

Further options can be found in the @JDB{} documentation.

@node Bash Options
@subsubsection Bash Options

If you have the proper bash installed, the option needed to specify
debugging support is @option{--debugger}. If your bash doesn't
understand this option you need to pick up a version of bash that does
from @uref{http://bashdb.sourceforge.net}.  Other options can be found
from the on-line documentation at
@uref{http://bashdb.sourceforge.net/bashdb.html}

@node GNU Make Options
@subsubsection GNU Make Options

If you have the proper @code{make} installed (for now it is probably
called @code{remake}), the option needed to specify debugging support
is @option{--debugger}. You can pick up a debugger-enabled version
from @uref{http://bashdb.sourceforge.net/remake}. Other options can be
found from the on-line documentation at
@uref{http://bashdb.sourceforge.net/remake/mdb.html}

@node Perl Options
@subsubsection Perl Options

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

@node PYDB Options
@subsubsection PYDB Options

An older version of @PYDB{} used to come with @DDD{}. That is no
longer the case. Pick up the newer version of @PYDB{} from
@uref{http://bashdb.sourceforge.net/pydb}. For a list of useful
@PYDB{} options, check out the @PYDB{} documentation,
@uref{http://bashdb.sourceforge.net/pydb/pydb/lib/index.html}.

@node Multiple Instances
@subsection Multiple @value{DDD} Instances

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

@defvr Resource checkOptions (class CheckOptions)
Every @var{n} seconds, where @var{n} is the value of this resource,
@DDD{} checks whether the options file has changed.  Default is
@code{30}, which means that every 30 seconds, @DDD{} checks for the
options file.  Setting this resource to @code{0} disables checking for
changed option files.
@end defvr

@lbindex Warn if Multiple @value{DDD} Instances are Running

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

This setting is tied to the following resource (@pxref{Customizing}):

@defvr Resource warnIfLocked (class WarnIfLocked)
Whether to warn if multiple @DDD{} instances are running
(@samp{on}) or not (@samp{off}, default).
@end defvr

@node X Warnings
@subsection X warnings

@cindex X Warnings, suppressing
@lbindex Suppress X warnings
If you are bothered by X warnings, you can suppress them by setting
@samp{Edit @result{} Preferences @result{} General @result{} Suppress X
warnings}.

This setting is tied to the following resource (@pxref{Customizing}):

@defvr Resource suppressWarnings (class SuppressWarnings)
If @samp{on}, X warnings are suppressed.  This is
sometimes useful for executables that were built on a machine with a
different X or M*tif configuration.  By default, this is
@samp{off}.
@end defvr


@node Quitting
@section Quitting @value{DDD}

@kindex Ctrl+D
@kindex Ctrl+Q
@lbindex Exit
@cindex Exiting
@cindex Quitting
@cmindex quit
To exit @DDD{}, select @samp{File @result{} Exit}.  You may also
type the @command{quit} command at the debugger prompt or press
@key{Ctrl+Q}.  @GDB{} and @XDB{} also accept the @command{q} command or an
end-of-file character (usually @key{Ctrl+D}).  Closing the last
@DDD{} window will also exit @DDD{}.

@kindex ESC
@cindex Interrupting execution
@cindex Execution, interrupting
An interrupt (@key{ESC} or @samp{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.

@kindex Ctrl+\
@lbindex Abort
@cindex Aborting execution
@cindex Execution, aborting
@cindex SIGABRT signal
In case an ordinary interrupt does not succeed, you can also use an
abort (@key{Ctrl+\} or @samp{Abort}), which sends a @code{SIGABRT}
signal to the inferior debugger.  Use this in emergencies only; the
inferior debugger may be left inconsistent or even exit after a
@code{SIGABRT} signal.

@kindex Ctrl+C
@cindex Interrupting @DDD{}
@cindex Signal, sending to @DDD{}
@cindex Killing @DDD{}
As a last resort (if @DDD{} hangs, for example), you may also
interrupt @DDD{} itself using an interrupt signal (@code{SIGINT}).
This can be done by typing the interrupt character (usually
@key{Ctrl+C}) in the shell @DDD{} was started from, or by using the
@UNIX{} @samp{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{}.


@node Sessions
@section Persistent Sessions
@cindex Session

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

@menu
* Saving Sessions::             
* Resuming Sessions::           
* Deleting Sessions::           
* Customizing Sessions::        
@end menu

@node Saving Sessions
@subsection Saving Sessions
@cindex Session, saving
@lbindex Save Session As
To save a session, select @samp{File @result{} Save Session As}.  You will 
be asked for a symbolic session name @var{session}.

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

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

@ifnotinfo
@sp 1
@center @image{PICS/ddd-save-session, 16cm}
@sp 1
@end ifnotinfo

After clicking on @samp{Save}, the session is saved in
@file{~/.@value{ddd}/sessions/@var{session}}.

Here's a list of the items whose state is saved in a session:
@itemize @bullet
@item
The state of the debugged program, as a core file.@footnote{Only if a
core file is included.}

@item 
All breakpoints and watchpoints (@pxref{Stopping}).

@item 
All signal settings (@pxref{Signals}).

@item
@cindex Deferred display, in sessions
All displays (@pxref{Displaying Values}).@footnote{If a core file is
@emph{not} to be included in the session, @DDD{} data displays are
saved as @emph{deferred}; that is, they will be restored as soon as
program execution reaches the scope in which they were created.
@xref{Creating Single Displays}, for details.}

@item
All @DDD{} options (@pxref{Saving Options}).

@item
All debugger settings (@pxref{Debugger Settings}).

@item
All user-defined buttons (@pxref{Defining Buttons}).

@item
All user-defined commands (@pxref{Defining Commands}).

@item
The positions and sizes of @DDD{} windows.

@item
The command history (@pxref{Command History}).
@end itemize


@cindex Session, active
After saving the current state as a session, the session becomes
@dfn{active}.  This means that @DDD{} state will be saved as
session defaults:

@itemize @bullet
@item
User options will be saved in
@file{~/.@value{ddd}/sessions/@var{session}/init} instead of
@file{~/.@value{ddd}/init}.  @xref{Saving Options}, for details.

@item
The @DDD{} command history will be saved in
@file{~/.@value{ddd}/sessions/@var{session}/history} instead of
@file{~/.@value{ddd}/history}.  @xref{Command History}, for details.
@end itemize

To make the current session inactive, open the @emph{default session}
named @samp{[None]}.  @xref{Resuming Sessions}, for details on opening
sessions.


@node Resuming Sessions
@subsection Resuming Sessions
@cindex Session, opening
@cindex Session, resuming

@lbindex Open Session
To resume a previously saved session, select @samp{File @result{} Open
Session} and choose a session name from the list.  After clicking on
@samp{Open}, the entire @DDD{} state will be restored from the
given session.

@cindex Default session
@cindex Session, default
The session named @samp{[None]} is the @dfn{default session} which is
active when starting @DDD{}.  To save options for default sessions,
choose the default session before exiting @DDD{}.  @xref{Saving
Options}, for details.

@ifnotinfo
@sp 1
@center @image{PICS/ddd-open-session, 16cm}
@sp 1
@end ifnotinfo

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

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

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

@example
@value{ddd} --session @var{session}
@end example

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

@example
@value{ddd} =@var{session}
@end example

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.

@pindex xsm
@cindex X session
You can also use an X session manager such as @command{xsm} to save and
restore @DDD{} sessions.@footnote{Requires X11R6 or later.} When
being shut down by a session manager, @DDD{} saves its state under
the name specified by the session manager; resuming the X session makes
@DDD{} reload its saved state.


@node Deleting Sessions
@subsection Deleting Sessions
@cindex Session, deleting

@lbindex Delete
To delete sessions that are no longer needed, select @samp{File
@result{} Open Session} or @samp{File @result{} Save Session}.  Select
the sessions you want to delete and click on @samp{Delete}.

The default session @samp{[None]} cannot be deleted.


@node Customizing Sessions
@subsection Customizing Sessions

@enindex DDD_SESSIONS
@flindex sessions
You can change the place where @DDD{} saves its sessions by setting
the environment variable @env{DDD_SESSIONS} to the name of a directory.
Default is @file{~/.@value{ddd}/sessions/}.

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

This setting is tied to the following resource (@pxref{Customizing}):

@defvr Resource getCoreCommand (class GetCoreCommand)
A command to get a core dump of a running process (typically,
@command{gcore}) @samp{@@FILE@@} is replaced by the base name of the file
to create; @samp{@@PID@@} is replaced by the process id.  The output
must be written to @samp{@@FILE@@.@@PID@@}.

Leave the value empty if you have no @command{gcore} or similar command.
@end defvr



@node Remote Debugging
@section Remote Debugging

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

@menu
* Remote Host::                 Running @DDD{} on a Remote Host
* Remote Debugger::             Using a Remote Inferior Debugger
* Remote Program::              Debugging a Remote Program
@end menu

@node Remote Host
@subsection Running @value{DDD} on a Remote Host
@cindex Remote host
@cindex Host, remote
@cindex Display, setting

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

@example
ddd -display @var{display}
@end example

@noindent
where @var{display} is the name of the X server to connect to (for
instance, @samp{@var{hostname}:0.0}, where @var{hostname} is your host).

@enindex DISPLAY
Instead of specifying @option{-display @var{display}}, you can also set
the @env{DISPLAY} environment variable to @var{display}.


@node Remote Debugger
@subsection Using @value{DDD} with a Remote Inferior Debugger
@cindex Remote debugger
@cindex Debugger, on remote host

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

To run the debugger on a remote host @var{hostname}, invoke @DDD{} as
@example
ddd --host @var{hostname} @var{remote-program}
@end example

If your remote @var{username} differs from the local username, use

@example
ddd --host @var{hostname} --login @var{username} @var{remote-program}
@end example

@noindent
or

@example
ddd --host @var{username}@@@var{hostname} @var{remote-program}
@end example

@noindent
instead.

There are a few @emph{caveats} in remote mode:

@itemize @bullet
@item
The remote debugger is started in your remote home directory.  Hence,
you must specify an absolute path name for @var{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.

@item
The remote debugger is started non-interactively.  Some @DBX{} versions
have trouble with this.  If you do not get a prompt from the remote
debugger, use the @option{--rhost} option instead of @option{--host}.  This
will invoke the remote debugger via an interactive shell on the remote
host, which may lead to better results.

Note: using @option{--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 @samp{>} and not followed by a newline is
assumed to be a shell prompt.  If necessary, adjust your shell prompt on
the remote host.

@item
To run the remote program, @DDD{} invokes an @samp{xterm} terminal
emulator on the remote host, giving your current @samp{DISPLAY}
environment variable as address.  If the remote host cannot invoke
@samp{xterm}, or does not have access to your X display, start
@DDD{} with the @option{--no-exec-window} option.  The program
input/output will then go through the @DDD{} debugger console.

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

@item
To help you find problems due to remote execution, run @DDD{} with
the @option{--trace} option.  This prints the shell commands issued by
@DDD{} on standard error.
@end itemize

@xref{Customizing Remote Debugging}, for customizing remote mode.



@menu
* Customizing Remote Debugging::  
@end menu

@node Customizing Remote Debugging
@subsubsection Customizing Remote Debugging

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

@defvr Resource rshCommand (class RshCommand)
The remote shell command to invoke @TTY{}-based commands on
remote hosts.  Usually, @command{remsh}, @command{rsh}, @command{ssh},
or @command{on}.
@pindex remsh
@pindex rsh
@pindex ssh
@pindex on
@end defvr

@defvr Resource listCoreCommand (class listCoreCommand)
The command to list all core files on the remote host.  The string
@samp{@@MASK@@} is replaced by a file filter.  The default setting is:

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

@defvr Resource listDirCommand (class listDirCommand)
The command to list all directories on the remote host.  The string
@samp{@@MASK@@} is replaced by a file filter.  The default setting is:

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

@defvr Resource listExecCommand (class listExecCommand)
The command to list all executable files on the remote host.  The string
@samp{@@MASK@@} is replaced by a file filter.  The default setting is:

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

@defvr Resource listSourceCommand (class listSourceCommand)
The command to list all source files on the remote host.  The string
@samp{@@MASK@@} is replaced by a file filter.  The default setting is:

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



@node Remote Program
@subsection Debugging a Remote Program
@cindex Remote program
@cindex Program, on remote host

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

@xref{Remote, Remote Debugging, Remote Debugging, gdb, Debugging with
@GDB{}}, for details.  Basically, the following steps are required:

@itemize @bullet
@item
Transfer the executable to the remote target.

@item
@pindex gdbserver
Start @command{gdbserver} on the remote target.

@item
@cmindex file
Start @DDD{} using @GDB{} on the local machine, and load the same
executable using the @GDB{} @command{file} command.

@item
Attach to the remote @samp{gdbserver} using the @GDB{} @command{target remote}
command.
@cmindex target remote
@end itemize

@flindex .gdbinit
The local @file{.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.





@node Customizing Debugger Interaction
@section Customizing Interaction with the Inferior Debugger

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

@menu
* Debugger Invocation::         
* Debugger Initialization::     
* Debugger Communication::      
@end menu

@node Debugger Invocation
@subsection Invoking an Inferior Debugger

@lbindex Debugger Type
To choose the default inferior debugger, select @samp{Edit @result{}
Preferences @result{} Startup @result{} Debugger Type}.  You can

@itemize @bullet{}
@item
@lbindex Determine Automatically from Arguments
have @DDD{} determine the appropriate inferior debugger
automatically from its command-line arguments.  Set @samp{Determine
Automatically from Arguments} to enable.
@item
have @DDD{} start the debugger of your choice, as specified in
@samp{Debugger Type}.
@end itemize

The following @DDD{} resources control the invocation of the
inferior debugger (@pxref{Customizing}).

@defvr Resource autoDebugger (class AutoDebugger)
If this is @samp{on} (default), @DDD{} will attempt to determine
the debugger type from its arguments, possibly overriding the
@samp{debugger} resource (see below).  If this is @samp{off},
@DDD{} will invoke the debugger specified by the @samp{debugger}
resource regardless of @DDD{} arguments.
@end defvr

@defvr Resource debugger (class Debugger)
The type of the inferior debugger to invoke 
(@samp{bash}
@samp{dbx},
@samp{gdb}, 
@samp{jdb}, 
@samp{ladebug}, 
@samp{make}, 
@samp{perl},
@samp{pydb}, or 
@samp{xdb}).

This resource is usually set through the 
@option{--bash}, 
@option{--dbx},
@option{--gdb}, 
@option{--jdb}, 
@option{--ladebug}, 
@option{--make}, 
@option{--perl},
@option{--pydb}, and
@option{--xdb}, 
options; @xref{Options}, for details.
@end defvr

@defvr Resource debuggerCommand (class DebuggerCommand)
The name under which the inferior debugger is to be invoked.  If this
string is empty (default), the debugger type (@samp{debugger} resource)
is used.

This resource is usually set through the @option{--debugger} option;
@xref{Options}, for details.
@end defvr




@node Debugger Initialization
@subsection Initializing the Inferior Debugger

@DDD{} uses a number of resources to initialize the
inferior debugger (@pxref{Customizing}).

@menu
* Bash Initialization::         
* DBX Initialization::          
* GDB Initialization::          
* JDB Initialization::          
* GNU Make Initialization::         
* Perl Initialization::         
* PYDB Initialization::         
* XDB Initialization::          
* Finding a Place to Start::    
* Opening the Selection::       
@end menu

@node Bash Initialization
@subsubsection Bash Initialization

@defvr Resource bashInitCommands (class InitCommands)
This string contains a list of newline-separated commands that are
initially sent to the Bash debugger.  By default, it is empty.

This resource may be used to customize the Bash debugger.
@end defvr

@defvr Resource bash (class Settings)
This string contains a list of newline-separated commands that are
also initially sent to the Bash debugger.  By default, it is empty.

This resource is used by @DDD{} to save and restore Bash
debugger settings.
@end defvr

@node DBX Initialization
@subsubsection DBX Initialization

@defvr Resource 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 @file{~/.dbxinit} or @file{~/.dbxrc} file.  See
your @DBX{} documentation for details.
@end defvr

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

@node GDB Initialization
@subsubsection GDB Initialization

@defvr Resource 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 @samp{gdbInitCommands} resource contains some
settings vital to @DDD{}:

@example
  @value{Ddd}*gdbInitCommands: \
  set height 0\n\
  set width 0\n\
   set verbose off\n\
  set prompt (gdb) \n
@end example

While the @samp{set height}, @samp{set width}, and @samp{set
prompt} settings are fixed, the @samp{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 @file{~/.gdbinit} file.  See your @GDB{}
documentation for details.
@end defvr

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

@example
  @value{Ddd}*gdbSettings: \
  set print asm-demangle on\n
@end example

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

@defvr Resource sourceInitCommands (class SourceInitCommands)
If @samp{on} (default), @DDD{} writes all @GDB{} initialization
commands into a temporary file and makes @GDB{} read this file, rather than
sending each initialization command separately.  This results in faster
startup (especially if you have several user-defined commands).  If
@samp{off}, @DDD{} makes @GDB{} process each command separately.
@end defvr



@node JDB Initialization
@subsubsection JDB Initialization

@defvr Resource jdbInitCommands (class InitCommands)
This string contains a list of newline-separated commands that are
initially sent to @JDB{}.  This resource may be used to customize
@JDB{}.  By default, it is empty.
@end defvr

@defvr Resource jdbSettings (class Settings)
This string contains a list of newline-separated commands that are
also initially sent to @JDB{}.  By default, it is empty.

This resource is used by @DDD{} to save and restore @JDB{}
settings.
@end defvr

@node GNU Make Initialization
@subsubsection GNU Make Initialization

@defvr Resource makeInitCommands (class InitCommands)
This string contains a list of newline-separated commands that are
initially sent to the Bash debugger.  By default, it is empty.

This resource may be used to customize GNU Make debugging.
@end defvr

@defvr Resource bash (class Settings)
This string contains a list of newline-separated commands that are
also initially sent to the GNU Make debugger.  By default, it is empty.

This resource is used by @DDD{} to save and restore GNU Make
debugger settings.
@end defvr


@node Perl Initialization
@subsubsection Perl Initialization

@defvr Resource perlInitCommands (class InitCommands)
This string contains a list of newline-separated commands that are
initially sent to the Perl debugger.  By default, it is empty.

This resource may be used to customize the Perl debugger.
@end defvr

@defvr Resource perlSettings (class Settings)
This string contains a list of newline-separated commands that are
also initially sent to the Perl debugger.  By default, it is empty.

This resource is used by @DDD{} to save and restore Perl
debugger settings.
@end defvr



@node PYDB Initialization
@subsubsection PYDB Initialization

@defvr Resource pydbInitCommands (class InitCommands)
This string contains a list of newline-separated commands that are
initially sent to @PYDB{}.  By default, it is empty.

This resource may be used to customize @PYDB{}.
@end defvr

@defvr Resource pydbSettings (class Settings)
This string contains a list of newline-separated commands that are
also initially sent to @PYDB{}.  By default, it is empty.

This resource is used by @DDD{} to save and restore @PYDB{}
settings.
@end defvr

@node XDB Initialization
@subsubsection XDB Initialization

@defvr Resource 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 @file{~/.xdbrc} file.  See your @XDB{}
documentation for details.
@end defvr

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




@node Finding a Place to Start
@subsubsection Finding a Place to Start

@defvr Resource initSymbols (class InitSymbols)
When loading an executable, @DDD{} queries the inferior debugger for the
initial source location---typically the @code{main} function.  If this
location is not found, @DDD{} tries other symbols from this
newline-separated list.  The default value makes @DDD{} look for a
variety of main functions (especially FORTRAN main functions):
@example
main\n\
MAIN\n\
main_\n\
MAIN_\n\
main__\n\
MAIN__\n\
_main\n\
_MAIN\n\
__main\n\
__MAIN
@end example
@end defvr



@node Opening the Selection
@subsubsection Opening the Selection

@defvr Resource openSelection (class OpenSelection)
If this is @samp{on}, @DDD{} invoked without argument checks
whether the current selection or clipboard contains the file name or
URL of an executable program.  If this is so, @DDD{}
will automatically open this program for debugging.  If this resource
is @samp{off} (default), @DDD{} invoked without arguments will
always start without a debugged program.
@end defvr



@node Debugger Communication
@subsection Communication with the Inferior Debugger

The following resources control the communication with the inferior
debugger.

@defvr Resource blockTTYInput (class BlockTTYInput)
Whether @DDD{} should block when reading data from the inferior debugger
via the pseudo-tty interface.  Most @UNIX{} systems except @GNU{}/Linux
@emph{require} this; set it to @samp{on}.  On @GNU{}/Linux, set it to
@samp{off}.  The value @samp{auto} (default) will always select the
``best'' choice (that is, the best choice known to the @DDD{}
developers).
@end defvr

@defvr Resource bufferGDBOutput (class BufferGDBOutput)
If this is @samp{on}, all output from the inferior debugger is buffered
until a debugger prompt appears.  This makes it easier for @DDD{} to
parse the output, but has the drawback that interaction with a running
debuggee in the debugger console is not possible.  If @samp{off}, output
is shown as soon as it arrives, enabling interaction, but making it
harder for @DDD{} to parse the output.  If @samp{auto} (default), output
is buffered if and only if the execution window is open, which redirects
debuggee output and thus enables interaction.  @xref{Using the Execution
Window}, for details.
@end defvr

@defvr Resource contInterruptDelay (class InterruptDelay)
The time (in ms) to wait before automatically interrupting a @samp{cont}
command.  @DDD{} cannot interrupt a @samp{cont} command immediately,
because this may disturb the status change of the process.  Default is
@code{200}.
@end defvr

@defvr Resource displayTimeout (class DisplayTimeout)
The time (in ms) to wait for the inferior debugger to finish a partial
display information.  Default is @code{2000}.
@end defvr

@defvr Resource positionTimeout (class PositionTimeout)
The time (in ms) to wait for the inferior debugger to finish a partial
position information.  Default is @code{500}.
@end defvr

@defvr Resource questionTimeout (class QuestionTimeout)
The time (in seconds) to wait for the inferior debugger to reply.
Default is @code{10}.
@end defvr

@defvr Resource runInterruptDelay (class InterruptDelay)
The time (in ms) to wait before automatically interrupting a @samp{run}
command.  @DDD{} cannot interrupt a @samp{cont} command immediately,
because this may disturb process creation.  Default is @code{2000}.
@end defvr

@defvr Resource stopAndContinue (class StopAndContinue)
@cindex Interrupting execution, automatically
@cindex Execution, interrupting automatically
If @samp{on} (default), debugger commands interrupt program execution,
resuming execution after the command has completed.  This only happens
if the last debugger command was either a @samp{run} or a
@samp{continue} command.  If @samp{off}, debugger commands do not
interrupt program execution.
@end defvr

@defvr Resource synchronousDebugger (class SynchronousDebugger)
If @samp{on}, X events are not processed while the debugger is busy.
This may result in slightly better performance on single-processor
systems.  @xref{Options}, for the @option{--sync-debugger} option.
@end defvr

@defvr Resource terminateOnEOF (class TerminateOnEOF)
If @samp{on}, @DDD{} terminates the inferior debugger when
@DDD{} detects an EOF condition (that is, as soon as the inferior
debugger closes its output channel).  This was the default behavior in
@DDD{} 2.x and earlier.  If @samp{off} (default), @DDD{} takes
no special action.
@end defvr

@defvr Resource useTTYCommand (class UseTTYCommand)
@cindex Redirection, to execution window
@cmindex tty
If @samp{on}, use the @GDB{} @command{tty} command for redirecting
input/output to the separate execution window.  If @samp{off}, use
explicit redirection through shell redirection operators @samp{<} and
@samp{>}.  The default is @samp{off} (explicit redirection), since on
some systems, the @command{tty} command does not work properly on some
@GDB{} versions.
@end defvr




@node Windows
@chapter The @value{DDD} Windows

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

@itemize @bullet
@item
The @dfn{Data Window} shows the current data of the debugged program.
@xref{Displaying Values}, for details.
@cindex Data window
@item
The @dfn{Source Window} shows the current source code of the debugged
program.  @xref{Navigating}, for details.
@cindex Source window
@item
The @dfn{Debugger Console} accepts debugger commands and shows debugger
messages.  @xref{Commands}, for details.
@cindex Debugger console
@end itemize

@ifnotinfo
@sp 1
@center @image{PICS/ddd-all, 16cm}
@sp 1
@end ifnotinfo


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

@itemize @bullet
@item
The @dfn{Command Tool} offers buttons for frequently used commands.
It is usually placed on the source window.  
@xref{Command Tool}, for details.
@cindex Command tool
@item
The @dfn{Machine Code Window} shows the current machine code.  It is
usually placed beneath the current source.  @xref{Machine Code}, for
details.
@cindex Machine code window
@item
The @dfn{Execution Window} shows the input and output of the debugged
program.  @xref{Using the Execution Window}, for details.
@cindex Execution window
@end itemize

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

@node Menu Bar
@section The Menu Bar

The @DDD{} Menu Bar gives you access to all @DDD{} functions.

@table @code
@item File
@lbindex File
Perform file-related operations such as selecting programs, processes,
and sessions, printing graphs, recompiling, as well as exiting
@DDD{}.

@item Edit
@lbindex Edit
Perform standard editing operations, such as cutting, copying, pasting,
and killing selected text.  Also allows editing @DDD{} options and
preferences.

@item View
@lbindex View
Allows accessing the individual @DDD{} windows.

@item Program
@lbindex Program
Perform operations related to the program being debugged, such as
starting and stopping the program.

@item Commands
@lbindex Commands
Perform operations related to @DDD{} commands, such as accessing
the command history or defining new commands.

@item Status
@lbindex Status
Examine the program status, such as the stack traces, registers, or
threads.

@item Source
@lbindex Source
Perform source-related operations such as looking up items or editing
breakpoints.

@item Data
@lbindex Data
Perform data-related operations such as editing displays or layouting
the display graph.

@item Maintenance
@lbindex Maintenance
Perform operations that are useful for debugging @DDD{}.  By
default, this menu is disabled.

@item Help
@lbindex Help
Give help on @DDD{} usage.
@end table


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

@itemize @bullet
@item Select an item in the menu bar by moving the cursor over it and
click @emph{mouse button 1}.  Then move the cursor over the menu item
you want to choose and click left again.

@item Select an item in the menu bar by moving the cursor over it and
click and hold @emph{mouse button 1}.  With the mouse button depressed,
move the cursor over the menu item you want, then release it to make
your selection.
@end itemize

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

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

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

@node File Menu
@subsection The File Menu
@lbindex File

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

@table @code
@item Open Program
@itemx Open Class
@kindex Ctrl+O
@lbindex Open Program
@lbindex Open Class
Open a program or class to be debugged (@key{Ctrl+O}).  @xref{Opening
Programs}, for details.

@item Open Recent
@lbindex Open Recent
Re-open a recently opened program to be debugged.  @xref{Opening
Programs}, for details.

@item Open Core Dump
@lbindex Open Core Dump
Open a core dump for the currently debugged program.  @xref{Opening Core
Dumps}, for details.

@item Open Source
@lbindex Open Source
Open a source file of the currently debugged program.  @xref{Opening
Source Files}, for details.

@item Open Session
@lbindex Open Session
@kindex Ctrl+N
Resume a previously saved @DDD{} session (@key{Ctrl+N}).  @xref{Resuming
Sessions}, for details.

@item Save Session As
@lbindex Save Session As
@kindex Ctrl+S
Save the current @DDD{} session such that you can resume it later
(@key{Ctrl+S}).  @xref{Saving Sessions}, for details.

@item Attach to Process
@lbindex Attach to Process
Attach to a running process of the debugged program.  @xref{Attaching to
a Process}, for details.

@item Detach Process
@lbindex Detach Process
Detach from the running process.  @xref{Attaching to a Process}, for
details.

@item Print Graph
@lbindex Print Graph
Print the current graph on a printer.  @xref{Printing the Graph}, for
details.

@item Change Directory
@lbindex Change Directory
Change the working directory of your program.  @xref{Working Directory}, 
for details.

@item Make
@lbindex Make
@kindex Ctrl+M
Run the @code{make} program (@key{Ctrl+M}).  @xref{Recompiling}, for
details.

@item Close
@lbindex Close
@kindex Ctrl+W
Close this @DDD{} window (@key{Ctrl+W}).  @xref{Quitting}, for details.

@item Restart
@lbindex Restart
Restart @DDD{}.

@item Exit
@lbindex Exit
@kindex Ctrl+Q
Exit @DDD{} (@key{Ctrl+Q}).  @xref{Quitting}, for details.
@end table


@node Edit Menu
@subsection The Edit Menu
@lbindex Edit
@cindex Clipboard

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

@table @code
@item Undo
@lbindex Undo
@kindex Ctrl+Z
Undo the most recent action (@key{Ctrl+Z}).  Almost all commands can be
undone this way.  @xref{Undo and Redo}, for details.

@item Redo
@lbindex Redo
@kindex Ctrl+Y
Redo the action most recently undone (@key{Ctrl+Y}).  Every command
undone can be redone this way.  @xref{Undo and Redo}, for details.

@item Cut
@lbindex Cut
@kindex Ctrl+X
@kindex Shift+Del
Removes the selected text block from the current text area and makes it
the X clipboard selection (@key{Ctrl+X} or @key{Shift+Del};
@xref{Customizing the Edit Menu}, for details).  Before executing this
command, you have to select a region in a text area---either with the
mouse or with the usual text selection keys.

This item can also be applied to displays (@pxref{Deleting Displays}).

@item Copy
@lbindex Copy
@kindex Ctrl+C
@kindex Ctrl+Ins
Makes a selected text block the X clipboard selection (@key{Ctrl+C} or
@key{Ctrl+Ins}; @xref{Customizing the Edit Menu}, for details).  You
can select text by selecting a text region with the usual text selection
keys or with the mouse.  @xref{Customizing the Edit Menu}, for changing
the default accelerator.

This item can also be applied to displays (@pxref{Deleting Displays}).

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

@item Clear
@lbindex Clear
@kindex Ctrl+U
Clears the most recently selected text area (@key{Ctrl+U}).

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

This item can also be applied to displays (@pxref{Deleting Displays}).

@item Select All
@lbindex Select All
@kindex Ctrl+A
@kindex Ctrl+Shift+A
Selects all characters from the most recently selected text area
(@key{Ctrl+A} or or @key{Ctrl+Shift+A}; @pxref{Customizing the Edit
Menu}, for details).


@item Preferences
@lbindex Preferences
Allows you to customize @DDD{} interactively.  @xref{Customizing},
for details.

@item Debugger Settings
@lbindex Debugger Settings
@lbindex GDB Settings
@lbindex DBX Settings
@lbindex Ladebug Settings
@lbindex XDB Settings
@lbindex JDB Settings
@lbindex PYDB Settings
@lbindex Perl Settings
Allows you to customize the inferior debugger.  @xref{Debugger
Settings}, for details.

@item Save Options
@lbindex Save Options
If set, all preferences and settings will be saved for the next @DDD{}
invocation.  @xref{Saving Options}, for details.
@end table



@node View Menu
@subsection The View Menu
@lbindex View

The @samp{View} menu allows accessing the individual @DDD{}
windows.

@table @code
@item Command Tool
@lbindex Command Tool
@kindex Alt+8
Open and recenter the command tool (@key{Alt+8}).  @xref{Command Tool},
for details.

@item Execution Window
@lbindex Execution Window
@kindex Alt+9
Open the separate execution window (@key{Alt+9}).  @xref{Using the
Execution Window}, for details.

@item Debugger Console
@lbindex GDB Console
@lbindex DBX Console
@lbindex Ladebug Console
@lbindex XDB Console
@lbindex JDB Console
@lbindex PYDB Console
@lbindex Perl Console
@lbindex Bash Console
@lbindex GNU Make Console
@kindex Alt+1
Open the debugger console (@key{Alt+1}).  @xref{Commands}, for details.

@item Source Window
@lbindex Source Window
@kindex Alt+2
Open the source window (@key{Alt+2}).  @xref{Navigating}, for details.

@item Data Window
@lbindex Data Window
@kindex Alt+3
Open the data window (@key{Alt+3}).  @xref{Displaying Values}, for details.

@item Machine Code Window
@lbindex Machine Code Window
@kindex Alt+4
Show machine code (@key{Alt+4}).  @xref{Machine Code}, for details.
@end table


@node Program Menu
@subsection The Program Menu
@lbindex Program

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

Most of these operations are also found on the command tool
(@pxref{Command Tool}).

@table @code
@item Run
@lbindex Run
@kindex F2
Start program execution, prompting for program arguments (@key{F2}).
@xref{Starting Program Execution}, for details.

@item Run Again
@lbindex Run Again
@kindex F3
Start program execution with the most recently used arguments (@key{F3}).
@xref{Starting Program Execution}, for details.

@item Run in Execution Window
@lbindex Run in Execution Window
If enabled, start next program execution in separate execution window.
@xref{Using the Execution Window}, for details.

@item Step
@lbindex Step
@kindex F5
Continue running your program until control reaches a different source
line, then stop it and return control to @DDD{} (@key{F5}).
@xref{Resuming Execution}, for details.

@item Step Instruction
@lbindex Step Instruction
@kindex Shift+F5
Execute one machine instruction, then stop and return to @DDD{}
(@key{Shift+F5}).  @xref{Machine Code Execution}, for details.

@item Next
@lbindex Next
@kindex F6
Continue to the next source line in the current (innermost) stack frame
(@key{F6}).  This is similar to @samp{Step}, but function calls that
appear within the line of code are executed without stopping.
@xref{Resuming Execution}, for details.

@item Next Instruction
@lbindex Next Instruction
@kindex Shift+F6
Execute one machine instruction, but if it is a function call,
proceed until the function returns (@key{Shift+F6}).
@xref{Machine Code Execution}, for details.

@item Until
@lbindex Until
@kindex F7
Continue running until a source line past the current line, in the
current stack frame, is reached (@key{F7}).  @xref{Resuming Execution},
for details.

@item Finish
@lbindex Finish
@kindex F8
Continue running until just after function in the selected stack frame
returns (@key{F8}).  Print the returned value (if any).  @xref{Resuming
Execution}, for details.

@item Continue
@lbindex Continue
@kindex F9
Resume program execution, at the address where your program last stopped
(@key{F9}); any breakpoints set at that address are bypassed.
@xref{Resuming Execution}, for details.

@item Continue Without Signal
@lbindex Continue Without Signal
@kindex Shift+F9
Continue execution without giving a signal (@key{Shift+F9}).  This is
useful when your program stopped on account of a signal and would
ordinary see the signal when resumed with @samp{Continue}.
@xref{Signals}, for details.

@item Kill
@lbindex Kill
@kindex F4
Kill the process of the debugged program (@key{F4}).  @xref{Killing the
Program}, for details.

@item Interrupt
@lbindex Interrupt
@kindex Esc
@kindex Ctrl+C
Interrupt program execution (@key{Esc} or @key{Ctrl+C};
@pxref{Customizing the Edit Menu}, for details).  This is equivalent to
sending an interrupt signal to the process.  @xref{Interrupting}, for
details.

@item Abort
@lbindex Abort
@cindex Aborting execution
@cindex Execution, aborting
@cindex SIGABRT signal
@kindex Ctrl+\
Abort program execution (and maybe debugger execution, too;
@key{Ctrl+\}).  This is equivalent to sending a @code{SIGABRT} signal to
the process.  @xref{Quitting}, for details.
@end table


@node Commands Menu
@subsection The Commands Menu
@lbindex Commands

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

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

@table @code
@item Command History
@lbindex Command History
View the command history.  @xref{Command History}, for details.

@item Previous
@lbindex Previous
@kindex Up
Show the previous command from the command history (@key{Up}).
@xref{Command History}, for details.

@item Next
@lbindex Next
@kindex Down
Show the next command from the command history (@key{Down}).
@xref{Command History}, for details.

@item Find Backward
@lbindex Find Backward
@kindex Ctrl+B
Do an incremental search backward through the command history
(@key{Ctrl+B}).  @xref{Command History}, for details.

@item Find Forward
@lbindex Find Forward
@kindex Ctrl+F
Do an incremental search forward through the command history (@key{Ctrl+F}).
@xref{Command History}, for details.

@item Quit Search
@lbindex Quit Search
@kindex Esc
Quit incremental search through the command history (@key{Esc}).
@xref{Command History}, for details.

@item Complete
@lbindex Complete
@kindex Tab
Complete the current command in the debugger console (@key{Tab}).
@xref{Entering Commands}, for details.

@item Apply
@lbindex Apply
@kindex Return
Apply the current command in the debugger console (@key{Apply}).
@xref{Entering Commands}, for details.

@item Clear Line
@lbindex Clear Line
@kindex Ctrl+U
Clear the current command line in the debugger console (@key{Ctrl+U}).
@xref{Entering Commands}, for details.

@item Clear Window
@lbindex Clear Window
@kindex Shift+Ctrl+U
Clear the debugger console (@key{Shift+Ctrl+U}).  @xref{Entering
Commands}, for details.

@item Define Command
@lbindex Define Command
Define a new debugger command.  @xref{Defining Commands}, for details.

@item Edit Buttons
@lbindex Edit Buttons
Customize @DDD{} buttons.  @xref{Defining Buttons}, for details.
@end table


@node Status Menu
@subsection The Status Menu
@lbindex Status

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

@table @code
@item Backtrace
@lbindex Backtrace
View the current backtrace.  @xref{Backtraces}, for a discussion.

@item Registers
@lbindex Registers
View the current register contents.  @xref{Registers}, for details.

@item Threads
@lbindex Threads
View the current threads.  @xref{Threads}, for details.

@item Signals
@lbindex Signals
View and edit the current signal handling.  @xref{Signals}, for details.

@item Up
@lbindex Up
@kindex Ctrl+Up
Select the stack frame (i.e. the function) that called this one
(@key{Ctrl+Up}).  This advances toward the outermost frame, to higher
frame numbers, to frames that have existed longer.  @xref{Stack}, for
details.

@item Down
@lbindex Down
@kindex Ctrl+Down
Select the stack frame (i.e. the function) that was called by this one
(@key{Ctrl+Down}).  This advances toward the innermost frame, to lower
frame numbers, to frames that were created more recently.  @xref{Stack},
for details.
@end table


@node Source Menu
@subsection The Source Menu
@lbindex Source

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

@table @code
@item Breakpoints
@lbindex Breakpoints
Edit all Breakpoints.  @xref{Editing all Breakpoints}, for details.

@item Lookup ()
@lbindex Lookup ()
@kindex Ctrl+/
Look up the argument @samp{()} in the source code (@key{Ctrl+/}).
@xref{Looking up Definitions}, for details.


@item Find >> ()
@lbindex Find >> ()
@kindex Ctrl+.
Look up the next occurrence of the argument @samp{()} in the current
source code (@key{Ctrl+.}).  @xref{Textual Search}, for details.

@item Find << ()
@lbindex Find << ()
@kindex Ctrl+,
Look up the previous occurrence of the argument @samp{()} in the current
source code (@key{Ctrl+,}).  @xref{Textual Search}, for details.


@item Find Words Only
@lbindex Find Words Only
@kindex Alt+W
If enabled, find only complete words (@key{Alt+W}).  @xref{Textual
Search}, for details.


@item Find Case Sensitive
@lbindex Find Case Sensitive
@kindex Alt+I
If enabled, find is case-sensitive (@key{Alt+I}).  @xref{Textual
Search}, for details.


@item Display Line Numbers
@lbindex Display Line Numbers
@kindex Alt+N
If enabled, prefix source lines with their line number (@key{Alt+N}).
@xref{Customizing Source}, for details.


@item Display Machine Code
@lbindex Display Machine Code
@kindex Alt+4
If enabled, show machine code (@key{Alt+4}).  @xref{Machine Code}, for details.


@item Edit Source
@lbindex Edit Source
@kindex Shift+Ctrl+V
Invoke an editor for the current source file (@key{Shift+Ctrl+V}).
@xref{Editing Source Code}, for details.

@item Reload Source
@lbindex Reload Source
@kindex Shift+Ctrl+L
Reload the current source file (@key{Shift+Ctrl+L}).  @xref{Editing
Source Code}, for details.
@end table


@node Data Menu
@subsection The Data Menu
@lbindex Data

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

@table @code
@item Displays
@lbindex Displays
Invoke the Display Editor.  @xref{Editing all Displays}, for details.

@item Watchpoints
@lbindex Watchpoints
Edit all Watchpoints.  @xref{Editing all Watchpoints}, for details.

@item Memory
@lbindex Memory
View a memory dump.  @xref{Examining Memory}, for details.

@item Print ()
@lbindex Print ()
@kindex Ctrl+=
Print the value of @samp{()} in the debugger console (@key{Ctrl+=}).
@xref{Printing Values}, for details.

@item Display ()
@lbindex Display ()
@kindex Ctrl+-
Display the value of @samp{()} in the data window (@key{Ctrl+-}).
@xref{Displaying Values}, for details.

@item Detect Aliases
@lbindex Detect Aliases
@kindex Alt+A
If enabled, detect shared data structures (@key{Alt+A}).  @xref{Shared
Structures}, for a discussion.

@item Display Local Variables
@lbindex Display Local Variables
@kindex Alt+L
Show all local variables in a display (@key{Alt+L}).  @xref{Displaying Local
Variables}, for details.

@item Display Arguments
@lbindex Display Arguments
@kindex Alt+U
Show all arguments of the current function in a display (@key{Alt+U}).
@xref{Displaying Local Variables}, for details.

@item Status Displays
@lbindex Status Displays
Show current debugging information in a display.  @xref{Displaying
Program Status}, for details.

@item Align on Grid
@lbindex Align on Grid
@kindex Alt+G
Align all displays on the grid (@key{Alt+G}).  @xref{Aligning Displays}, for a
discussion.

@item Rotate Graph
@lbindex Rotate Graph
@kindex Alt+R
Rotate the graph by 90 degrees (@key{Alt+R}).  @xref{Rotating the Graph}, for details.

@item Layout Graph
@lbindex Layout Graph
@kindex Alt+Y
Layout the graph (@key{Alt+Y}).  @xref{Layouting the Graph}, for details.

@item Refresh
@lbindex Refresh
@kindex Ctrl+L
Update all values in the data window (@key{Ctrl+L}).  @xref{Refreshing
the Data Window}, for details.
@end table


@node Maintenance Menu
@subsection The Maintenance Menu
@lbindex Maintenance

The @samp{Maintenance} menu performs operations that are useful for
debugging @DDD{}.  

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

@table @code
@item Debug @DDD{}
@kindex F12
@lbindex Debug @value{DDD}
Invoke a debugger (typically, @GDB{}) and attach it to this @DDD{}
process (@key{F12}).  This is useful only if you are a @DDD{} maintainer.

@item Dump Core Now
@lbindex Dump Core Now
@cindex SIGUSR1 signal
Make this @DDD{} process dump core.  This can also be achieved by
sending @DDD{} a @code{SIGUSR1} signal.

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

@item When @DDD{} Crashes
@lbindex When @value{DDD} Crashes
Select what to do when @DDD{} gets a fatal signal.

@table @code
@item Debug @DDD{}
@lbindex Debug @DDD{}
Invoke a debugger on the @DDD{} core dump when @DDD{}
crashes.  This is useful only if you are a @DDD{} maintainer.

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

@item Do Nothing
@lbindex Do Nothing
Do not dump core or invoke a debugger when @DDD{} crashes.
@end table

@item Remove Menu
@lbindex Remove Menu
Make this menu inaccessible again.
@end table

@node Help Menu
@subsection The Help Menu
@lbindex Help

The @samp{Help} menu gives help on @DDD{} usage.  @xref{Getting
Help}, for a discussion on how to get help within @DDD{}.


@table @code
@item Overview
@lbindex Overview
Explains the most important concepts of @DDD{} help.

@item On Item
@lbindex On item
Lets you click on an item to get help on it.

@item On Window
@lbindex On item
Gives you help on this @DDD{} window.

@item What Now?
@lbindex What Now?
Gives a hint on what to do next.

@item Tip of the Day
@lbindex Tip of the Day
Shows the current tip of the day.

@item @DDD{} Reference
@lbindex @value{DDD} Reference
Shows the @DDD{} Manual.

@item @DDD{} News
@lbindex @value{DDD} News
Shows what's new in this @DDD{} release.

@item Debugger Reference
@lbindex Bash Reference
@lbindex DBX Reference
@lbindex Debugger Reference
@lbindex GDB Reference
@lbindex JDB Reference
@lbindex Ladebug Reference
@lbindex Perl Reference
@lbindex PYDB Reference
@lbindex XDB Reference
Shows the on-line documentation for the inferior debugger.

@item @DDD{} License
@lbindex @value{DDD} License
Shows the @DDD{} License (@pxref{License}).

@item @DDD{} @WWW{} Page
@lbindex @value{DDD} WWW Page
Invokes a @WWW{} browser for the @DDD{} @WWW{} page.

@item About @DDD{}
@lbindex About @DDD{}
Shows version and copyright information.
@end table

@node Customizing the Menu Bar
@subsection Customizing the Menu Bar

The Menu Bar can be customized in various ways (@pxref{Customizing}).

@menu
* Auto-Raise Menus::            
* Customizing the Edit Menu::   
@end menu

@node Auto-Raise Menus
@subsubsection Auto-Raise Menus

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

@defvr Resource autoRaiseMenu (class AutoRaiseMenu)
If @samp{on} (default), @DDD{} will always keep the pull down 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 @samp{off}.
@end defvr

@defvr Resource autoRaiseMenuDelay (class AutoRaiseMenuDelay)
The time (in ms) during which an initial auto-raised window blocks
further auto-raises.  This is done to prevent two overlapping
auto-raised windows from entering an @emph{auto-raise loop}.  Default is
@code{100}.
@end defvr


@node Customizing the Edit Menu
@subsubsection Customizing the Edit Menu

In the Menu Bar, the @samp{Edit} Menu can be customized in various ways.
Use @samp{Edit @result{} Preferences @result{} Startup} to customize
these keys.

@kindex Ctrl+C
@lbindex Ctrl+C is
The @key{Ctrl+C} key can be bound to different actions, each in
accordance with a specific style guide.

@table @code
@item Copy
@kindex ESC
This setting binds @key{Ctrl+C} to the Copy operation, as specified by
the KDE style guide.  In this setting, use @key{ESC} to interrupt the
debuggee.

@item Interrupt
@kindex Ctrl+C
@end table
This (default) setting binds @key{Ctrl+C} to the Interrupt operation, as
used in several @UNIX{} command-line programs.  In this setting, use
@key{Ctrl+Ins} to copy text to the clipboard.

@lbindex Ctrl+A is
The @key{Ctrl+A} key can be bound to different actions, too.

@table @code
@item Select All
@kindex Home
This (default) setting binds @key{Ctrl+A} to the @samp{Select All}
operation, as specified by the KDE style guide.  In this setting, use
@key{Home} to move the cursor to the beginning of a line.

@item Beginning of Line
@kindex Ctrl+Shift+A
This setting binds @key{Ctrl+A} to the @samp{Beginning of Line}
operation, as used in several @UNIX{} text-editing programs.  In this
setting, use @key{Ctrl+Shift+A} to select all text.
@end table

Here are the related @DDD{} resources:

@defvr Resource cutCopyPasteBindings (class BindingStyle)
Controls the key bindings for clipboard operations.

@itemize @bullet
@item
If this is @samp{Motif} (default), Cut/Copy/Paste is on
@key{Shift+Del}/@key{Ctrl+Ins}/@key{Shift+Ins}.  This is conformant to
the M*tif style guide.
@item
If this is @samp{KDE}, Cut/Copy/Paste is on
@key{Ctrl+X}/@key{Ctrl+C}/@key{Ctrl+V}.  This is conformant to the KDE
style guide.  Note that this means that @key{Ctrl+C} no longer
interrupts the debuggee; use @key{ESC} instead.
@end itemize
@end defvr

@defvr Resource selectAllBindings (class BindingStyle)
Controls the key bindings for the @samp{Select All} operation.

@itemize @bullet
@item
If this is @samp{Motif}, Select All is on @key{Shift+Ctrl+A}.
@item
If this is @samp{KDE} (default), Select All is on @key{Ctrl+A}.  This is
conformant to the KDE style guide.  Note that this means that
@key{Ctrl+A} no longer moves the cursor to the beginning of a line; use
@key{Home} instead.
@end itemize
@end defvr



@node Tool Bar
@section The Tool Bar

Some @DDD{} commands require an @emph{argument}.  This argument
is specified in the @emph{argument field}, labeled @samp{():}.
Basically, there are four ways to set arguments:

@itemize @bullet
@item
You can @emph{key in} the argument manually.
@item
You can @emph{paste} the current selection into the argument field
(typically using @kbd{mouse button 2}).  To clear old contents
beforehand, click on the @samp{():} label.
@item
You can @emph{select an item} from the source and data windows.  This
will automatically copy the item to the argument field.
@item
You can select a @emph{previously used argument} from the drop-down
menu at the right of the argument field.
@end itemize

@kindex TAB
Using @GDB{} and Perl, the argument field provides a completion mechanism.
You can enter the first few characters of an item an press the @key{TAB}
key to complete it.  Pressing @key{TAB} again shows alternative
completions.

After having entered an argument, you can select one of the buttons on
the right.  Most of these buttons also have menus associated with them;
this is indicated by a small arrow in the upper right corner.  Pressing
and holding @emph{mouse button 1} on such a button will pop up a menu
with further operations.

@ifnotinfo
@sp 1
@center @image{PICS/ddd-toolbar, 16cm}
@sp 1
@end ifnotinfo


These are the buttons of the tool bar.  Note that not all buttons may be
inactive, depending on the current state and the capabilities of the
inferior debugger.

@table @code
@item Lookup
@lbindex Lookup
@cindex Looking up items

Look up the argument @samp{()} in the source code.  @xref{Looking up
Definitions}, for details.


@item Find >>
@lbindex Find >>
@cindex Finding items
@cindex Search, using @samp{Find >>}

Look up the next occurrence of the argument @samp{()} in the current
source code.  @xref{Textual Search}, for details.


@item Break/Clear
@cindex Breakpoint, toggling

Toggle a breakpoint (@pxref{Breakpoints}) at the location @samp{()}.

@table @code
@item Break
@lbindex Break
If there is no breakpoint at @samp{()}, then this button is labeled
@samp{Break}.  Clicking on @samp{Break} sets a breakpoint at the
location @samp{()}.  @xref{Setting Breakpoints}, for details.

@item Clear
@lbindex Clear
If there already is a breakpoint at @samp{()}, then this button is
labeled @samp{Clear}.  Clicking on @samp{Clear} clears (deletes) the
breakpoint at the location @samp{()}.  @xref{Deleting Breakpoints}, for
details.
@end table


@item Watch/Unwatch
@cindex Watchpoint, toggling

Toggle a watchpoint (@pxref{Watchpoints}) on the expression @samp{()}.

@table @code
@item Watch
@lbindex Watch
If @samp{()} is not being watched, then this button is labeled
@samp{Watch}.  Clicking on @samp{Watch} creates a watchpoint on the
expression @samp{()}.  @xref{Setting Watchpoints}, for details.

@item Unwatch
@lbindex Unwatch
If @samp{()} is being watched, then this button is labeled
@samp{Unwatch}.  Clicking on @samp{Unwatch} clears (deletes) the
watchpoint on @samp{()}.  @xref{Deleting Watchpoints}, for details.
@end table


@item Print
@lbindex Print
@cindex Values, printing with @samp{Print}
@cindex Printing values with @samp{Print}

Print the value of @samp{()} in the debugger console.  @xref{Printing
Values}, for details.


@item Display
@lbindex Display
@cindex Values, displaying with @samp{Display}
@cindex Displaying values with @samp{Display}
@cindex Display, creating

Display the value of @samp{()} in the data window.  @xref{Displaying
Values}, for details.


@item Plot
@lbindex Plot
@cindex Values, plotting with @samp{Plot}
@cindex Plotting values

Plot @samp{()} in a plot window.  @xref{Plotting Values}, for details.


@item Show/Hide
@lbindex Show
@lbindex Hide
@cindex Display, toggling detail
@cindex Detail toggling with @samp{Show/Hide}

Toggle details of the selected display(s).  @xref{Showing and Hiding
Details}, for a discussion.


@item Rotate
@lbindex Rotate
@cindex Display, rotating
@cindex Rotating displays with @samp{Rotate}

Rotate the selected display(s).  @xref{Rotating Displays}, for details.


@item Set
@lbindex Set
@cindex Display, setting
@cindex Setting variables with @samp{Set}
@cindex Variables, setting with @samp{Set}

Set (change) the value of @samp{()}.  @xref{Assignment}, for details.


@item Undisp
@lbindex Undisp
@cindex Display, deleting
@cindex Deleting displays

Undisplay (delete) the selected display(s).  @xref{Deleting Displays},
for details.
@end table


@menu
* Customizing the Tool Bar::    
@end menu

@node Customizing the Tool Bar
@subsection Customizing the Tool Bar

The @DDD{} tool bar buttons can appear in a variety of styles,
customized via @samp{Edit @result{} Preferences @result{} Startup}.

@table @code
@item Images
This lets each tool bar button show an image illustrating the action.

@item Captions
This shows the action name below the image.
@end table

The default is to have images as well as captions, but you can choose to
have only images (saving space) or only captions.

@ifnotinfo
@sp 1
@center @image{PICS/ddd-toolbars, 16cm}
@sp 1
@end ifnotinfo

If you choose to have neither images nor captions, tool bar buttons are
labeled like other buttons, as in @DDD{} 2.x.  Note that this
implies that in the stacked window configuration, the common tool bar
cannot be displayed; it is replaced by two separate tool bars, as in
@DDD{} 2.x.

If you enable @samp{Flat} buttons (default), the border of tool bar
buttons will appear only if the mouse pointer is over them.  This
latest-and-greatest @acronym{GUI} invention can be disabled, such that
the button border is always shown.

If you enable @samp{Color} buttons, tool bar images will be colored when
entered.  If @DDD{} was built using M*tif 2.0 and later, you can
also choose a third setting, where buttons appear in color all the time.

Here are the related resources (@pxref{Customizing}):

@defvr Resource activeButtonColorKey (class ColorKey)
The @acronym{XPM} color key to use for the images of active buttons
(entered or armed).  @samp{c} means color, @samp{g} (default) means
grey, and @samp{m} means monochrome.
@end defvr

@defvr Resource buttonCaptions (class ButtonCaptions)
Whether the tool bar buttons should be shown using captions
(@samp{on}, default) or not (@samp{off}).  If neither captions nor
images are enabled, tool bar buttons are shown using ordinary labels.
See also @samp{buttonImages}, below.
@end defvr

@defvr Resource buttonCaptionGeometry (class ButtonCaptionGeometry)
The geometry of the caption subimage within the button icons.  Default
is @samp{29x7+0-0}.
@end defvr

@defvr Resource buttonImages (class ButtonImages)
Whether the tool bar buttons should be shown using images (@samp{on},
default) or not (@samp{off}).  If neither captions nor images are
enabled, tool bar buttons are shown using ordinary labels.  See also
@samp{buttonCaptions}, above.
@end defvr

@defvr Resource buttonImageGeometry (class ButtonImageGeometry)
The geometry of the image within the button icon.  Default is
@samp{25x21+2+0}.
@end defvr

@defvr Resource buttonColorKey (class ColorKey)
The @acronym{XPM} color key to use for the images of inactive buttons
(non-entered or insensitive).  @samp{c} means color, @samp{g}
(default) means grey, and @samp{m} means monochrome.
@end defvr

@defvr Resource flatToolbarButtons (class FlatButtons)
If @samp{on} (default), all tool bar buttons with images or captions
are given a `flat' appearance---the 3-D border only shows up when the
pointer is over the icon.  If @samp{off}, the 3-D border is shown all
the time.
@end defvr

@defvr Resource flatDialogButtons (class FlatButtons)
If @samp{on} (default), all dialog buttons with images or captions
are given a `flat' appearance---the 3-D border only shows up when
the pointer is over the icon.  If @samp{off}, the 3-D border is shown
all the time.
@end defvr




@node Command Tool
@section The Command Tool

The command tool is a small window that gives you access to the most
frequently used @DDD{} commands.  It can be moved around on top of
the @DDD{} windows, but it can also be placed besides them.

By default, the command tool @emph{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 is also
@emph{auto-raised}, such that it stays on top of other @DDD{}
windows.

The command tool can be configured to appear as a command tool bar above
the source window; see @samp{Edit @result{} Preferences @result{} Source
@result{} Tool Buttons Location} for details.

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.  To move the command tool to its
saved position, use @samp{View @result{} Command Tool}.

@ifnotinfo
@sp 1
@center @image{PICS/ddd-tool, 16cm}
@sp 1
@end ifnotinfo

These are the buttons of the command tool.  Note that not all buttons
may be inactive, depending on the current state and the capabilities of
the inferior debugger.

@table @code
@item Run
@lbindex Run
Start program execution.  When you click this button, your program will
begin to execute immediately.  @xref{Starting Program Execution}, for
details.

@item Interrupt
@lbindex Interrupt
Interrupt program execution.  This is equivalent to sending an interrupt
signal to the process.  @xref{Interrupting}, for details.

@item Step
@lbindex Step
Continue running your program until control reaches a different source
line, then stop it and return control to @DDD{}.  @xref{Resuming
Execution}, for details.

@item Stepi
@lbindex Stepi
Execute one machine instruction, then stop and return to @DDD{}.
@xref{Machine Code Execution}, for details.

@item Next
@lbindex Next
Continue to the next source line in the current (innermost) stack
frame.  This is similar to @samp{Step}, but function calls that appear
within the line of code are executed without stopping.
@xref{Resuming Execution}, for details.

@item Nexti
@lbindex Nexti
Execute one machine instruction, but if it is a function call,
proceed until the function returns.
@xref{Machine Code Execution}, for details.

@item Until
@lbindex Until
Continue running until a source line past the current line, in the
current stack frame, is reached.  @xref{Resuming Execution}, for details.

@item Finish
@lbindex Finish
Continue running until just after function in the selected stack frame
returns.  Print the returned value (if any).  @xref{Resuming Execution},
for details.

@item Cont
@lbindex Cont
Resume program execution, at the address where your program last
stopped; any breakpoints set at that address are bypassed.
@xref{Resuming Execution}, for details.

@item Kill
@lbindex Kill
Kill the process of the debugged program.  @xref{Killing the Program},
for details.

@item Up
@lbindex Up
Select the stack frame (i.e. the function) that called this one.  This
advances toward the outermost frame, to higher frame numbers, to frames
that have existed longer.  @xref{Stack}, for details.

@item Down
@lbindex Down
Select the stack frame (i.e. the function) that was called by this one.
This advances toward the innermost frame, to lower frame numbers, to
frames that were created more recently.  @xref{Stack}, for details.

@item Undo
@lbindex Undo
Undo the most recent action.  Almost all commands can be undone this
way.  @xref{Undo and Redo}, for details.

@item Redo
@lbindex Redo
Redo the action most recently undone.  Every command undone can be
redone this way.  @xref{Undo and Redo}, for details.

@item Edit
@lbindex Edit
Invoke an editor for the current source file.  @xref{Editing Source
Code}, for details.

@item Make
@lbindex Make
Run the @code{make} program with the most recently given arguments.
@xref{Recompiling}, for details.
@end table


@menu
* Customizing the Command Tool::  
* Customizing Tool Position::   
@end menu

@node Customizing the Command Tool
@subsection Customizing the Command Tool

The Command Tool can be customized in various ways.

@menu
* Disabling the Command Tool::  
@end menu

@xref{Customizing Buttons}, for details on customizing the tool buttons.

@node Disabling the Command Tool
@subsubsection Disabling the Command Tool

@lbindex Tool Buttons Location
You can disable the command tool and show its buttons in a separate row
beneath the tool bar.  To disable the command tool, set @samp{Edit
@result{} Preferences @result{} Source @result{} Tool Buttons Location
@result{} Source Window}.

@ifnotinfo
@sp 1
@center @image{PICS/ddd-source-prefs, 16cm}
@sp 1
@end ifnotinfo

Here's the related resource:

@defvr Resource commandToolBar (class ToolBar)
Whether the tool buttons should be shown in a tool bar above the source
window (@samp{on}) or within the command tool (@samp{off}, default).
Enabling the command tool bar disables the command tool and vice versa.
@end defvr


@node Customizing Tool Position
@subsection Command Tool Position

The following resources control the position of the command tool
(@pxref{Customizing}):

@defvr Resource autoRaiseTool (class AutoRaiseTool)
If @samp{on} (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 @samp{off}.
@end defvr

@defvr Resource stickyTool (class StickyTool)
If @samp{on} (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 @samp{off}, the command tool
does not follow source window movements.
@end defvr

@defvr Resource 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.
@end defvr

@defvr Resource 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.
@end defvr


@menu
* Customizing Tool Decoration::  
@end menu

@node Customizing Tool Decoration
@subsubsection Customizing Tool Decoration

The following resources control the decoration of the command tool
(@pxref{Customizing}):

@defvr Resource decorateTool (class Decorate)
This resource controls the decoration of the command tool.

@itemize @bullet
@item
If this is @samp{off}, the command tool is created as a @emph{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.

@item
If this is @samp{on}, @DDD{} realizes the command tool as a
@emph{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
@samp{autoRaiseTool} resource, too.

@item
If this is @samp{auto} (default), @DDD{} checks whether the window
manager decorates transients.  If yes, the command tool is realized as a
transient window (as in the @samp{off} setting); if no, the command tool
is realized as a top-level window (as in the @samp{on} setting).  Hence,
the command tool is always decorated using the ``best'' method, but the
extra check takes some time.
@end itemize
@end defvr



@node Getting Help
@section Getting Help
@cindex Help

@DDD{} has an extensive on-line help system.  Here's how to get
help while working with @DDD{}.

@itemize @bullet
@item
@cindex Button tip
@cindex Tool tip
@cindex Balloon help
@cindex Help, on buttons
@cindex Tip, on buttons
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 @dfn{button tip}; also known as @dfn{tool tip} or
@dfn{balloon help}) 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.

@item
@cindex Help, in the status line
@cindex Status line
The @dfn{status line} also displays information about the currently selected
item.  By clicking on the status line, you can redisplay the most
recent messages.

@item
@cindex Help, on items
@cindex Context-sensitive help
@kindex F1
You can get detailed help on any visible @DDD{} item.  Just
point on the item you want help and press the @samp{F1} key.  This
pops up a detailed help text.

@item
@lbindex Help
The @DDD{} dialogs all contain @samp{Help} buttons that give
detailed information about the dialog.

@item
@cindex Help, on commands
@cmindex help
You can get help on debugger commands by entering @command{help} at the
debugger prompt.  @xref{Entering Commands}, for details on entering
commands.

@item
@lbindex What Now?
@kindex Ctrl+F1
@cindex Help, when stuck
If you are totally stuck, try @samp{Help @result{} What Now?} (the
@samp{What Now?} item in the @samp{Help} menu) or press @key{Ctrl+F1}.
Depending on the current state, @DDD{} will give you some hints on
what you can do next.

@item
Of course, you can always refer to the @emph{on-line documentation}:

@itemize @minus
@item
@lbindex @value{DDD} Reference
@samp{Help @result{} @DDD{} Reference} gives you access to the
@DDD{} manual, the ultimate @DDD{} reference.

@item
@lbindex Debugger Reference
@lbindex GDB Reference
@lbindex DBX Reference
@lbindex Ladebug Reference
@lbindex XDB Reference
@lbindex JDB Reference
@lbindex PYDB Reference
@lbindex Perl Reference
@lbindex Bash Reference
@samp{Help @result{} Debugger Reference} shows you the
on-line documentation of the inferior debugger.

@item
@samp{Help @result{} @DDD{} @WWW{} Page} gives you access to the
latest and greatest information on @DDD{}.
@lbindex @value{DDD} @WWW{} Page
@end itemize

@item
Finally, the @DDD{} @dfn{Tip Of The Day} gives you important hints
with each new @DDD{} invocation.
@cindex Tip of the day
@end itemize

All these functions can be customized in various ways
(@pxref{Customizing Help}).

If, after all, you made a mistake, don't worry: almost every @DDD{}
command can be undone.  @xref{Undo and Redo}, for details.


@node Undo and Redo
@section Undoing and Redoing Commands
@lbindex Undo
@cindex Undoing commands

Almost every @DDD{} command can be undone, using @samp{Edit
@result{} Undo} or the @samp{Undo} button on the command tool.

@lbindex Redo
@cindex Redoing commands
Likewise, @samp{Edit @result{} Redo} repeats the command most recently
undone.

The @samp{Edit} menu shows which commands are to be undone and redone
next; this is also indicated by the popup help on the @samp{Undo} and
@samp{Redo} buttons.




@node Customizing
@section Customizing @value{DDD}

@DDD{} is controlled by several @emph{resources}---user-defined
variables that take specific values in order to control and customize
@DDD{} behavior.

Most @DDD{} resources can be set interactively while @DDD{} is
running or when invoking @DDD{}.  @xref{Resource Index}, for the full list
of @DDD{} resources.

We first discuss how customizing works in general; then we turn to
customizing parts of @DDD{} introduced so far.

@menu
* How Customizing Works::       
* Customizing Help::            
* Customizing Undo::            
* Customizing Windows::         
* Debugger Settings::           
@end menu

@node How Customizing Works
@subsection How Customizing @value{DDD} Works

@menu
* Resources::                   
* Changing Resources::          
* Saving Options::              
@end menu

@node Resources
@subsubsection Resources
@cindex Resources

Just like any X program, @DDD{} has a number of places to get
resource values from.  For @DDD{}, the most important places to
specify resources are:

@itemize @bullet
@item
@flindex init
@flindex ~
The @file{~/.@value{ddd}/init} file (@file{~} stands for your home
directory).  This file is read in by @DDD{} upon start-up; the
resources specified herein override all other sources (except for
resources given implicitly by command-line options).

@enindex DDD_STATE
If the environment variable @env{DDD_STATE} is set, its value
is used instead of @file{~/.@value{ddd}/}.

@item
@flindex Ddd
The @file{@value{Ddd}} application-defaults file.  This file is
typically compiled into the @DDD{} executable.  If it exists, its
resource values override the values compiled into @DDD{}.  If the
versions of the @file{@value{Ddd}} application-defaults file and the
@DDD{} executable do not match, @DDD{} may not function
properly; @DDD{} will give you a warning in this case.@footnote{If
you use a @file{@value{Ddd}} application-defaults file, you will not be
able to maintain multiple @DDD{} versions at the same time.  This
is why the suiting @file{@value{Ddd}} is normally compiled into the
@DDD{} executable.}

@item
The command-line options.  These options override all other resource
settings.

@item
@enindex DDD_SESSION
If the environment variable @env{DDD_SESSION} is set, it
indicates the name of a session to start, overriding all options and
resources.  This is used by @DDD{} when restarting itself.
@end itemize

Not every resource has a matching command-line option.  Each resource
(whether in @file{~/.@value{ddd}/init} or @file{@value{Ddd}}) is
specified using a line

@example
@value{Ddd}*@var{resource}: @var{value}
@end example

For instance, to set the @samp{pollChildStatus} resource to @samp{off},
you would specify in @file{~/.@value{ddd}/init}:

@example
@value{Ddd}*pollChildStatus: off
@end example

For more details on the syntax of resource specifications, see the
section @cite{RESOURCES} in the @cite{X(1)} manual page.


@node Changing Resources
@subsubsection Changing Resources

You can change @DDD{} resources by three methods:

@itemize @bullet{}
@item
Use @DDD{} to change the options, notably @samp{Edit @result{}
Preferences}.  This works for the most important @DDD{} resources.
Be sure to save the options (@pxref{Saving Options}) such that they
apply to future @DDD{} sessions, too.

@item
You can also invoke @DDD{} with an appropriate command-line option.
This changes the related @DDD{} resource for this particular
@DDD{} invocation.  However, if you save the options (@pxref{Saving
Options}), the changed resource will also apply to future invocations.

@item
Finally, you can set the appropriate resource in a file named
@file{.@value{ddd}/init} in your home directory.  
@xref{Resource Index}, for a list of @DDD{} resources to be set.
@end itemize


@node Saving Options
@subsubsection Saving Options

You can save the current option settings by setting @samp{Edit @result{}
Save Options}.  Options are saved in a file named
@file{.@value{ddd}/init} in your home directory when @DDD{} exits.  If a
session @var{session} is active, options will be saved in
@file{~/.@value{ddd}/sessions/@var{session}/init} instead.

The options are automatically saved when exiting @DDD{}.  You can turn
off this feature by unsetting @samp{Edit @result{} Save Options}.  This
is tied to the following resource:

@defvr Resource saveOptionsOnExit (class SaveOnExit)
If @samp{on} (default), the current option settings are automatically saved
when @DDD{} exits.
@end defvr


@node Customizing Help
@subsection Customizing @value{DDD} Help

@DDD{} Help can be customized in various ways.

@menu
* Button tips::                 Turning off tips.
* Tip of the day::              Turning off the tip of the day.
* Help Helpers::                Helper programs invoked by Help.
@end menu

@node Button tips
@subsubsection Button Tips

@lbindex Automatic Display of Button Hints
@cindex Button tip, turning off
Button tips are helpful for novices, but may be distracting for
experienced users.  You can turn off button tips via @samp{Edit
@result{} Preferences @result{} General @result{} Automatic display of
Button Hints @result{} as Popup Tips}.

You can also turn off the hint that is displayed in the status line.
Just toggle @samp{Edit @result{} Preferences @result{} General @result{}
Automatic Display of Button Hints @result{} in the Status Line}.

@ifnotinfo
@sp 1
@center @image{PICS/ddd-general-prefs, 16cm}
@sp 1
@end ifnotinfo

These are the related @DDD{} resources (@pxref{Customizing}):

@defvr Resource buttonTips (class Tips)
If @samp{on} (default), enable button tips.
@end defvr

@defvr Resource buttonDocs (class Docs)
If @samp{on} (default), show button hints in the status line.
@end defvr


@node Tip of the day
@subsubsection Tip of the day
@cindex Tip of the day, turning off

You can turn off the tip of the day by toggling @samp{Edit @result{}
Preferences @result{} Startup @result{} Startup Windows @result{} Tip of
the Day}.

Here is the related @DDD{} resource (@pxref{Customizing}):

@defvr Resource startupTips (class StartupTips)
If @samp{on} (default), show a tip of the day upon @DDD{} startup.
@end defvr

@xref{Options}, for options to set this resource upon @DDD{}
invocation.

The actual tips are controlled by these resources (@pxref{Customizing}):

@defvr Resource startupTipCount (class StartupTipCount)
The number @var{n} of the tip of the day to be shown at startup.  See
also the @samp{tip@var{n}} resources.
@end defvr

@defvr Resource tip@var{n} (class Tip)
The tip of the day numbered @var{n} (a string).
@end defvr



@node Help Helpers
@subsubsection Help Helpers

@DDD{} relies on a number of external commands, specified via
@samp{Edit @result{} Preferences @result{} Helpers}.

@ifnotinfo
@sp 1
@center @image{PICS/ddd-helpers, 16cm}
@sp 1
@end ifnotinfo

@lbindex Uncompress
To uncompress help texts, you can define a @samp{Uncompress} command:

@defvr Resource uncompressCommand (class UncompressCommand)
@cmindex gzip
@cmindex gunzip
@cmindex zcat
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 @command{gzip -d -c}; typical values include
@command{zcat} and @command{gunzip -c}.
@end defvr

@lbindex Web Browser
To view @WWW{} pages, you can define a @samp{Web Browser} command:

@defvr Resource wwwCommand (class WWWCommand)
@enindex WWWBROWSER
@pindex netscape
@pindex mozilla
@pindex emacs
@pindex xemacs
@pindex firefox
@pindex gnudoit
@pindex lynx
The command to invoke a @WWW{} browser.  The string @samp{@@URL@@} is
replaced by the @acronym{URL} to open.  Default is to try a running
Netscape first (trying @command{mozilla}, then @command{netscape}), then
@command{$WWWBROWSER}, then to invoke a new Netscape process, then to
let a running Emacs or XEmacs do the job (via @command{gnudoit}), then
to invoke Firefox, then to invoke Lynx in an xterm.

To specify @samp{netscape-6.0} as browser, use the setting:

@example
Ddd*wwwCommand: \
     netscape-6.0 -remote 'openURL(@@URL@@)' \
  || netscape-6.0 '@@URL@@'
@end example

This command first tries to connect to a running @code{netscape-6.0}
browser; if this fails, it starts a new @code{netscape-6.0} process.
@end defvr

This is the default @WWW{} Page shown by @samp{Help @result{} @DDD{}
@WWW{} Page}:

@defvr Resource wwwPage (class @WWW{}Page)
The @DDD{} @WWW{} page.  Value:
@uref{http://www.gnu.org/software/ddd/}
@end defvr



@node Customizing Undo
@subsection Customizing Undo

@DDD{} Undo can be customized in various ways.

@lbindex Undo Buffer Size
To set a maximum size for the undo buffer, set @samp{Edit @result{}
Preferences @result{} General @result{} Undo Buffer Size}.

This is related to the @samp{maxUndoSize} resource:

@defvr Resource maxUndoSize (class MaxUndoSize)
The maximum memory usage (in bytes) of the undo buffer.  Useful for
limiting @DDD{} memory usage.  A negative value means to place no
limit.  Default is @code{2000000}, or 2000 kBytes.
@end defvr

You can also limit the number of entries in the undo buffer, regardless
of size (@pxref{Customizing}):

@defvr Resource maxUndoDepth (class MaxUndoDepth)
The maximum number of entries in the undo buffer.  This limits the
number of actions that can be undone, and the number of states that
can be shown in historic mode.  Useful for limiting @DDD{}
memory usage.  A negative value (default) means to place no limit.
@end defvr

@lbindex Clear Undo Buffer
To clear the undo buffer at any time, thus reducing memory usage, use
@samp{Edit @result{} Preferences @result{} General @result{} Clear Undo
Buffer}


@node Customizing Windows
@subsection Customizing the @value{DDD} Windows

You can customize the @DDD{} Windows in various ways.

@menu
* Splash Screen::               Turning off the splash screen.
* Window Layout::               Re-arranging windows.
* Customizing Fonts::           Using alternate fonts.
* Toggling Windows::            Turning off windows.
* Text Fields::                 Popdown histories.
* Icons::                       Iconifying @DDD{} windows.
* Adding Buttons::              Create your own button set.
* More Customizations::         
@end menu

@node Splash Screen
@subsubsection Splash Screen

@lbindex @value{DDD} Splash Screen
You can turn off the @DDD{} splash screen shown upon startup.  Just
select @samp{Edit @result{} Preferences @result{} Startup @DDD{}
Splash Screen}.

@ifnotinfo
@sp 1
@center @image{PICS/ddd-startup-prefs, 16cm}
@sp 1
@end ifnotinfo

The value applies only to the next @DDD{} invocation.

This setting is related to the following resource:

@defvr Resource splashScreen (class SplashScreen)
If @samp{on} (default), show a @DDD{} splash screen upon
start-up.
@end defvr

You can also customize the appearance of the splash screen
(@pxref{Customizing}):

@defvr Resource splashScreenColorKey (class ColorKey)
The color key to use for the @DDD{} splash screen.  Possible
values include:

@itemize @bullet
@item 
@samp{c} (default) for a color visual, 
@item 
@samp{g} for a multi-level greyscale visual,
@item 
@samp{g4} for a 4-level greyscale visual, and
@item 
@samp{m} for a dithered monochrome visual.
@item
@samp{best} chooses the best visual available for your display.
@end itemize

Please note: if @DDD{} runs on a monochrome display, or if @DDD{} was
compiled without the @acronym{XPM} library, only the monochrome version
(@samp{m}) can be shown.
@end defvr


@node Window Layout
@subsubsection Window Layout

@lbindex Window Layout
By default, @DDD{} stacks commands, source, and data in one single
top-level window.  To have separate top-level windows for source, data,
and debugger console, set @samp{Edit @result{} Preferences @result{}
Startup @result{} Window Layout @result{} Separate Windows}.

@ifnotinfo
@sp 1
@center @image{PICS/ddd-separate, 16cm}
@sp 1
@end ifnotinfo

Here are the related @DDD{} resources:

@defvr Resource separateDataWindow (class Separate)
If @samp{on}, the data window and the debugger console are realized in
different top-level windows.  If @samp{off} (default), the data window
is attached to the debugger console.
@end defvr

@defvr Resource separateSourceWindow (class Separate)
If @samp{on}, the source window and the debugger console are realized in
different top-level windows.  If @samp{off} (default), the source window
is attached to the debugger console.
@end defvr

@lbindex Tool Bar Appearance
@cindex Tool Bar, location
By default, the @DDD{} tool bars are located on top of the window.
If you prefer the tool bar being located at the bottom, as in
@DDD{} 2.x and earlier, set @samp{Edit @result{} Preferences
@result{} Startup @result{} Tool Bar Appearance @result{} Bottom}.

This is related to the @samp{toolbarsAtBottom} resource:

@defvr Resource toolbarsAtBottom (class ToolbarsAtBottom)
Whether source and data tool bars should be placed above source and
data, respectively (@samp{off}, default), or below, as in @DDD{}
2.x (@samp{on}).
@end defvr

The bottom setting is only supported for separate tool bars---that is,
you must either choose separate windows or configure the tool bar to
have neither images nor captions (@pxref{Customizing the Tool Bar}).

If you use stacked windows, you can choose whether there should be one
tool bar or two tool bars.  By default, @DDD{} uses two tool bars
if you use separate windows and disable captions and images, but you can
also explicitly change the setting via this resource:

@defvr Resource commonToolBar (class ToolBar)
Whether the tool bar buttons should be shown in one common tool bar at
the top of the common @DDD{} window (@samp{on}, default), or
whether they should be placed in two separate tool bars, one for data,
and one for source operations, as in @DDD{} 2.x (@samp{off}).
@end defvr

@cindex Status line, location
You can also change the location of the @emph{status line}
(@pxref{Customizing}):

@defvr Resource statusAtBottom (class StatusAtBottom)
If @samp{on} (default), the status line is placed at the bottom of the
@DDD{} source window.  If @samp{off}, the status line is placed at
the top of the @DDD{} source window (as in @DDD{} 1.x).
@end defvr

@xref{Options}, for options to set these resources upon @DDD{}
invocation.


@node Customizing Fonts
@subsubsection Customizing Fonts
@cindex Fonts

You can configure the basic @DDD{} fonts at run-time.  Each
font is specified using two members:

@itemize @bullet
@item
The @dfn{font family} is an X font specifications, where the initial
@samp{@var{foundry}-} specification may be omitted, as well as any
specification after @var{family}.  Thus, a pair
@samp{@var{family}-@var{weight}} usually suffices.

@item
The @dfn{font size} is given as (resolution-independent) 1/10 points.
@end itemize

To specify fonts, select @samp{Edit @result{} Preferences @result{}
Fonts}.

@ifnotinfo
@sp 1
@center @image{PICS/ddd-font-prefs, 16cm}
@sp 1
@end ifnotinfo

The @samp{Browse} button opens a font selection program, where you can
select fonts and attributes interactively.  Clicking @samp{quit} or
@samp{select} in the font selector causes all non-default values to be
transferred to the @DDD{} font preferences panel.

The following fonts can be set using the preferences panel:

@table @code
@item Default Font
The default @DDD{} font to use for labels, menus, and buttons.
Default is @samp{helvetica-bold}.

@item Variable Width
The variable width @DDD{} font to use for help texts and messages.
Default is @samp{helvetica-medium}.

@item Fixed Width
The fixed width @DDD{} font to use for source code, the debugger
console, text fields, and the execution window.  Default
is @samp{lucidatypewriter-medium}.

@item Data
The @DDD{} font to use for data displays.  Default
is @samp{lucidatypewriter-medium}.
@end table

Changes in this panel will take effect only in the next @DDD{} session.
To make it effective right now, restart @DDD{} (using @samp{File
@result{} Restart @DDD{}}).

After having made changes in the panel, @DDD{} will automatically
offer you to restart itself, such that you can see the changes taking
effect.

The @samp{Reset} button restores the most recently saved preferences.

Here are the resources related to font specifications:

@defvr Resource defaultFont (class Font)
The default @DDD{} font to use for labels, menus, buttons, etc.
The font is specified as an X font spec, where the initial @var{Foundry}
specification may be omitted, as well as any specification after
@var{Family}.  

Default value is @samp{helvetica-bold}.

To set the default @DDD{} font to, say, @samp{helvetica medium},
insert a line

@example
@value{Ddd}*defaultFont: helvetica-medium
@end example

@noindent
in your @file{~/.@value{ddd}/init} file.
@end defvr

@defvr Resource defaultFontSize  (class FontSize)
The size of the default @DDD{} font, in 1/10 points.  This resource
overrides any font size specification in the @samp{defaultFont} resource
(see above).  The default value is @code{120} for a 12.0 point font.
@end defvr

@defvr Resource variableWidthFont (class Font)
The variable width @DDD{} font to use for help texts and messages.
The font is specified as an X font spec, where the initial @var{Foundry}
specification may be omitted, as well as any specification after
@var{Family}.

Default value is @samp{helvetica-medium-r}.

To set the variable width @DDD{} font family to, say,
@samp{times}, insert a line

@example
@value{Ddd}*fixedWidthFont: times-medium
@end example

@noindent
in your @file{~/.@value{ddd}/init} file.
@end defvr

@defvr Resource variableWidthFontSize  (class FontSize)
The size of the variable width @DDD{} font, in 1/10 points.  This
resource overrides any font size specification in the
@samp{variableWidthFont} resource (see above).  The default value is
@code{120} for a 12.0 point font.
@end defvr

@defvr Resource fixedWidthFont (class Font)
The fixed width @DDD{} font to use for source code, the debugger
console, text fields, and the execution window.  The font
is specified as an X font spec, where the initial @var{Foundry}
specification may be omitted, as well as any specification after
@var{Family}.

Default value is @samp{lucidatypewriter-medium}.

To set the fixed width @DDD{} font family to, say, @samp{courier},
insert a line

@example
@value{Ddd}*fixedWidthFont: courier-medium
@end example

@noindent
in your @file{~/.@value{ddd}/init} file.
@end defvr

@defvr Resource fixedWidthFontSize  (class FontSize)
The size of the fixed width @DDD{} font, in 1/10 points.  This
resource overrides any font size specification in the
@samp{fixedWidthFont} resource (see above).  The default value is
@code{120} for a 12.0 point font.
@end defvr

@defvr Resource dataFont (class Font)
The fixed width @DDD{} font to use data displays.  The font
is specified as an X font spec, where the initial @var{Foundry}
specification may be omitted, as well as any specification after
@var{Family}.

Default value is @samp{lucidatypewriter-medium}.

To set the @DDD{} data font family to, say, @samp{courier},
insert a line

@example
@value{Ddd}*dataFont: courier-medium
@end example

@noindent
in your @file{~/.@value{ddd}/init} file.
@end defvr

@defvr Resource dataFontSize  (class FontSize)
The size of the @DDD{} data font, in 1/10 points.  This
resource overrides any font size specification in the
@samp{dataFont} resource (see above).  The default value is
@code{120} for a 12.0 point font.
@end defvr

As all font size resources have the same class (and by default the
same value), you can easily change the default @DDD{} font size
to, say, 9.0 points by inserting a line

@example
@value{Ddd}*FontSize: 90
@end example

@noindent
in your @file{~/.@value{ddd}/init} file.

Here's how to specify the command to select fonts:

@defvr Resource fontSelectCommand (class FontSelectCommand)
A command to select from a list of fonts.  The string @samp{@@FONT@@} is
replaced by the current @DDD{} default font; the string
@samp{@@TYPE@@} is replaced by a symbolic name of the @DDD{} font
to edit.  The program must either place the name of the selected font in
the @code{PRIMARY} selection or print the selected font on standard
output.  A typical value is:
@example
@value{Ddd}*fontSelectCommand: xfontsel -print
@end example
@pindex xfontsel
@end defvr

@xref{Options}, for options to set these resources upon @DDD{}
invocation.




@node Toggling Windows
@subsubsection Toggling Windows

In the default stacked window setting, you can turn the individual
@DDD{} windows on and off by toggling the respective items in the
@samp{View} menu (@pxref{View Menu}).  When using separate windows
(@pxref{Window Layout}), you can close the individual windows via
@samp{File @result{} Close} or by closing them via your window manager.

Whether windows are opened or closed when starting @DDD{} is
controlled by the following resources, immediately tied to the
@samp{View} menu items:

@defvr Resource openDataWindow (class Window)
If @samp{off} (default), the data window is closed upon start-up.
@end defvr

@defvr Resource openDebuggerConsole (class Window)
If @samp{off}, the debugger console is closed upon start-up.
@end defvr

@defvr Resource openSourceWindow (class Window)
If @samp{off}, the source window is closed upon start-up.
@end defvr

@xref{Options}, for options to set these resources upon @DDD{}
invocation.


@node Text Fields
@subsubsection Text Fields

The @DDD{} text fields can be customized using the following
resources:

@defvr Resource popdownHistorySize (class HistorySize)
The maximum number of items to display in pop-down value histories.  A
value of @code{0} (default) means an unlimited number of values.
@end defvr

@defvr Resource sortPopdownHistory (class SortPopdownHistory)
If @samp{on} (default), items in the pop-down value histories are sorted
alphabetically.  If @samp{off}, most recently used values will appear at
the top.
@end defvr


@node Icons
@subsubsection Icons

@lbindex Iconify all windows at once
If you frequently switch between @DDD{} and other multi-window
applications, you may like to set @samp{Edit @result{} Preferences
@result{} General @result{} Iconify all windows at once}.  This
way, all @DDD{} windows are iconified and deiconified as a group.

This is tied to the following resource:

@defvr Resource groupIconify (class GroupIconify)
If this is @samp{on}, (un)iconifying any @DDD{} window
causes all other @DDD{} windows to (un)iconify as well.
Default is @samp{off}, meaning that each @DDD{} window can
be iconified on its own.
@end defvr


If you want to keep @DDD{} off your desktop during a longer
computation, you may like to set @samp{Edit @result{} Preferences
@result{} General @result{} Uniconify when ready}.  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).
@xref{Program Stop}, for a discussion.

Here is the related resource:

@defvr Resource uniconifyWhenReady (class UniconifyWhenReady)
If this is @samp{on} (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 @samp{off} leaves the
@DDD{} windows iconified.
@end defvr


@node Adding Buttons
@subsubsection Adding Buttons

You can extend @DDD{} with new buttons.  @xref{Defining Buttons},
for details.


@node More Customizations
@subsubsection More Customizations

@flindex Ddd
You can change just about any label, color, keyboard mapping, etc.  by
changing resources from the @file{Ddd} application defaults file which
comes with the @DDD{} source distribution.  Here's how it works:

@itemize @bullet
@item
Identify the appropriate resource in the @file{Ddd} file.

@item
Copy the resource line to your @file{~/.@value{ddd}/init} file
and change it at will.
@end itemize

@xref{Application Defaults}, for details on the application-defaults
file.



@node Debugger Settings
@subsection Debugger Settings

For most inferior debuggers, you can change their internal settings
using @samp{Edit @result{} 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.

@ifnotinfo
@sp 1
@center @image{PICS/ddd-settings, 16cm}
@sp 1
@end ifnotinfo

The capabilities of the settings editor depend on the capabilities of
your inferior debugger.  Clicking on @samp{?} gives an an explanation on
the specific item; the @GDB{} documentation gives more details.

Use @samp{Edit @result{} Undo} to undo changes.  Clicking on
@samp{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
@samp{gdbInitCommands} and @samp{dbxInitCommands} resources for details.

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





@node Navigating
@chapter Navigating through the Code

This chapter discusses how to access code from within @DDD{}.

@menu
* Compiling for Debugging::     Always use `-g' to compile.
* Opening Files::               How to open a program for debugging.
* Looking up Items::            Searching files and functions.
* Customizing Source::          Arranging the source window.
@end menu

@node Compiling for Debugging
@section Compiling for Debugging

In order to debug a program effectively, you need to generate debugging
information when you compile it.  This debugging information is stored
in the object file; it describes the data type of each variable or
function and the correspondence between source line numbers and
addresses in the executable code.@footnote{If you use @DDD{} to
debug Perl, Python or Bash scripts, then this section does not apply.}

To request debugging information, specify the @option{-g} option when you
run the compiler.

Many C compilers are unable to handle the @option{-g} and @option{-O}
options together.  Using those compilers, you cannot generate optimized
executables containing debugging information.

@cindex GCC
@acronym{GCC}, the @GNU{} C compiler, supports @option{-g} with or without
@option{-O}, making it possible to debug optimized code.  We recommend
that you @emph{always} use @option{-g} whenever you compile a program.
You may think your program is correct, but there is no sense in pushing
your luck.

@cindex Optimized code, debugging
@cindex Debugging optimized code
When you debug a program compiled with @option{-g -O}, remember that the
optimizer is rearranging your code; the debugger shows you what is
really there.  Do not be too surprised when the execution path does not
exactly match your source file!  An extreme example: if you define a
variable, but never use it, @DDD{} never sees that
variable---because the compiler optimizes it out of existence.


@node Opening Files
@section Opening Files
@cindex Files, opening

If you did not invoke @DDD{} specifying a program to be debugged,
you can use the @samp{File} menu to open programs, core dumps and
sources.

@menu
* Opening Programs::            How to open a program for debugging.
* Opening Core Dumps::          Analyze a previous crash.
* Opening Source Files::        Open a source file of the program.
* Filtering Files::             @DDD{} only lists matching files.
@end menu

@node Opening Programs
@subsection Opening Programs
@cindex Program, opening
@cindex Class, opening
@lbindex Open Program
@lbindex Open

To open a program to be debugged, select @samp{File @result{} Open
Program}.@footnote{With @XDB{} and some @DBX{} variants, the debugged program
must be specified upon invocation and cannot be changed at run time.}
Click on @samp{Open} to open the program

@lbindex Open Class
In @JDB{}, select @samp{File @result{} Open Class} instead.  This gives you
a list of available classes to choose from.

@ifnotinfo
@sp 1
@center @image{PICS/ddd-open, 16cm}
@sp 1
@end ifnotinfo

@lbindex Open Recent
To re-open a recently debugged program or class, select @samp{File
@result{} Open Recent} and choose a program or class from the list.

If no sources are found, @xref{Source Path}, for specifying source
directories.


@node Opening Core Dumps
@subsection Opening Core Dumps
@cindex Core dump, opening

If a previous run of the program has crashed and you want to find out
why, you can have @DDD{} examine its @dfn{core dump}.@footnote{@JDB{},
@PYDB{}, Perl, and Bash do not support core dumps.}

@lbindex Open
To open a core dump for the program, select @samp{File @result{} Open
Core Dump}.  Click on @samp{Open} to open the core dump.

Before @samp{Open Core Dump}, you should first use @samp{File @result{}
Open Program} to specify the program that generated the core dump and to
load its symbol table.


@node Opening Source Files
@subsection Opening Source Files
@cindex Source file, opening
@lbindex Open Source

To open a source file of the debugged program, select @samp{File
@result{} Open Source}.

@itemize @bullet{}
@item
Using @GDB{}, this gives you a list of the sources used for compiling your
program.

@item
Using other inferior debuggers, this gives you a list of accessible
source files, which may or may not be related to your program.
@end itemize

@lbindex Open
Click on @samp{Open} to open the source file.  @xref{Source Path}, if no
sources are found.


@node Filtering Files
@subsection Filtering Files

When presenting files to be opened, @DDD{} by default filters files
when opening execution files, core dumps, or source files, such that the
selection shows only suitable files.  This requires that @DDD{}
opens each file, which may take time.  @xref{Customizing File
Filtering}, if you want to turn off this feature.


@node Looking up Items
@section Looking up Items

As soon as the source of the debugged program is available, the
@emph{source window} displays its current source text.  (@pxref{Source
Path}, if a source text cannot be found.)

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

@menu
* Looking up Definitions::      Jump towards a specific item.
* Textual Search::              Search within the current source.
* Looking up Previous Locations::  Navigate back and forth.
* Source Path::                 Make @DDD{} know where to search.
@end menu

@node Looking up Definitions
@subsection Looking up Definitions
@lbindex Lookup

If you wish to lookup a specific function or variable definition whose
name is visible in the source text, click with @emph{mouse button 1} on
the function or variable name.  The name is copied to the argument
field.  Change the name if desired and click on the @samp{Lookup} button
to find its definition.

@ifnotinfo
@sp 1
@center @image{PICS/ddd-source-popup, 16cm}
@sp 1
@end ifnotinfo

As a faster alternative, you can simply press @emph{mouse button 3} on the
function name and select the @samp{Lookup} item from the source popup
menu.

As an even faster alternative, you can also double-click on a function 
call (an identifier followed by a @samp{(} character) to lookup the
function definition.

If a source file is not found, @xref{Source Path}, for specifying source
directories.


@node Textual Search
@subsection Textual Search
@lbindex Find >>
@lbindex Find <<

If the item you wish to search is visible in the source text, click with
@emph{mouse button 1} on it.  The identifier is copied to the argument
field.  Click on the @samp{Find >>} button to find following occurrences
and on @samp{Find >> @result{} Find << ()} to find previous occurrences.

@lbindex Find Words Only
By default, @DDD{} finds only complete words.  To search for
arbitrary substrings, change the value of the @samp{Source @result{}
Find Words Only} option.


@node Looking up Previous Locations
@subsection Looking up Previous Locations
@lbindex Undo
@lbindex Redo
@cindex Undoing lookups
@cindex Redoing lookups
@cindex Lookups, undoing
@cindex Lookups, redoing

After looking up a location, use @samp{Edit @result{} Undo} (or the
@samp{Undo} button on the command tool) to go back to the original
locations.  @samp{Edit @result{} Redo} brings you back again to the
location you looked for.

@ifnotinfo
@sp 1
@center @image{PICS/ddd-source, 16cm}
@sp 1
@end ifnotinfo


@node Source Path
@subsection Specifying Source Directories
@cindex Source, accessing
@cindex Source directory

Executable programs sometimes do not record the directories of the
source files from which they were compiled, just the names.  Even when
they do, the directories could be moved between the compilation and your
debugging session.

Here's how @GDB{} accesses source files; other inferior debuggers have
similar methods.

@cindex Source path
@GDB{} has a list of directories to search for source files; this is called
the @dfn{source path}.  Each time @GDB{} wants a source file, it tries all
the directories in the list, in the order they are present in the list,
until it finds a file with the desired name.  Note that the executable
search path is @emph{not} used for this purpose.  Neither is the current
working directory, unless it happens to be in the source path.

If @GDB{} cannot find a source file in the source path, and the object
program records a directory, @GDB{} tries that directory too.  If the
source path is empty, and there is no record of the compilation
directory, @GDB{} looks in the current directory as a last resort.

@lbindex Search path for source files
@cindex Source path, specifying
To specify a source path for your inferior debugger, use @samp{Edit
@result{} Debugger Settings} (@pxref{Debugger Settings} and search for
appropriate entries (in @GDB{}, this is @samp{Search path for source
files}).

If @samp{Debugger Settings} has no suitable entry, you can also specify
a source path for the inferior debugger when invoking @DDD{}.
@xref{Inferior Debugger Options}, for details.

@enindex CLASSPATH
When using @JDB{}, you can set the @env{CLASSPATH} environment variable to
specify directories where @JDB{} (and @DDD{}) should search for
classes.

If @value{DDD} does not find a source file for any reason, check the
following issues:

@itemize @bullet
@item 
In order to debug a program effectively, you need to generate debugging
information when you compile it.  Without debugging information, the
inferior debugger will be unable to locate the source code. To request
debugging information, specify the @option{-g} option when you run the
compiler.  @xref{Compiling for Debugging}, for details.

@item
You may need to tell your inferior debugger where the source code files
are.  @xref{Source Path}, for details.

@cmindex directory
Using @GDB{}, you can also create a local @file{.gdbinit} file that
contains a line @command{directory @var{path}}.  Here, @var{path} is a
colon-separated list of source paths.
@end itemize




@node Customizing Source
@section Customizing the Source Window

The source window can be customized in a number of ways, most of them
accessed via @samp{Edit @result{} Preferences @result{} Source}.

@ifnotinfo
@sp 1
@center @image{PICS/ddd-source-prefs, 16cm}
@sp 1
@end ifnotinfo


@menu
* Customizing Glyphs::          
* Customizing Searching::       
* Customizing Source Appearance::  
* Customizing Source Scrolling::  
* Customizing Source Lookup::   
* Customizing File Filtering::  
@end menu

@node Customizing Glyphs
@subsection Customizing Glyphs

@cindex Glyph
@lbindex Show Position and Breakpoints
In the source text, the current execution position and breakpoints are
indicated by symbols (@dfn{glyphs}).  As an alternative, @DDD{} can
also indicate these positions using text characters.  If you wish to
disable glyphs, set @samp{Edit @result{} Preferences @result{} Source
@result{} Show Position and Breakpoints @result{} as Text Characters}
option.  This also makes @DDD{} run slightly faster, especially
when scrolling.

This setting is tied to this resource:

@defvr Resource displayGlyphs (class DisplayGlyphs)
If this is @samp{on}, the current execution position and breakpoints are
displayed as glyphs; otherwise, they are shown through characters in the
text.  The default is @samp{on}.  @xref{Options}, for the
@option{--glyphs} and @option{--no-glyphs} options.
@end defvr

You can further control glyphs using the following resources:

@defvr Resource cacheGlyphImages (class CacheMachineCode)
Whether to cache (share) glyph images (@samp{on}) or not (@samp{off}).
Caching glyph images requires less X resources, but has been reported to
fail with OSF/Motif 2.1 on XFree86 servers.  Default is @samp{off} for
OSF/Motif 2.1 or later on @GNU{}/Linux machines, and @samp{on}
otherwise.
@end defvr

@defvr Resource glyphUpdateDelay (class GlyphUpdateDelay)
A delay (in ms) that says how much time to wait before updating glyphs
while scrolling the source text.  A small value results in glyphs
being scrolled with the text, a large value disables glyphs while
scrolling and makes scrolling faster.  Default: @code{10}.
@end defvr

@defvr Resource maxGlyphs (class MaxGlyphs)
The maximum number of glyphs to be displayed (default: @code{10}).
Raising this value causes more glyphs to be allocated, possibly
wasting resources that are never needed.
@end defvr



@node Customizing Searching
@subsection Customizing Searching

Searching in the source text (@pxref{Textual Search}) is controlled by
these resources, changed via the @samp{Source} menu:

@defvr Resource findCaseSensitive (class FindCaseSensitive)
If this is @samp{on} (default), the @samp{Find} commands are
case-sensitive.  Otherwise, occurrences are found regardless of case.
@end defvr

@defvr Resource findWordsOnly (class FindWordsOnly)
If this is @samp{on} (default), the @samp{Find} commands find
complete words only.  Otherwise, arbitrary occurrences are found.
@end defvr



@node Customizing Source Appearance
@subsection Customizing Source Appearance

@cindex Line numbers
@lbindex Display Source Line Numbers
You can have @DDD{} show line numbers within the source window.
Use @samp{Edit @result{} Preferences @result{} Source @result{} Display
Source Line Numbers}.

@defvr Resource displayLineNumbers (class DisplayLineNumbers)
If this is @samp{on}, lines in the source text are prefixed with
their respective line number.  The default is @samp{off}.
@end defvr

@cindex Indent, source code
@lbindex Source indentation
You can instruct @DDD{} to indent the source code, leaving more
room for breakpoints and execution glyphs.  This is done using the
@samp{Edit @result{} Preferences @result{} Source @result{} Source
indentation} slider.  The default value is @code{0} for no indentation
at all.

@defvr Resource indentSource (class Indent)
The number of columns to indent the source code, such that there is
enough place to display breakpoint locations.  Default: @code{0}.
@end defvr

By default, @DDD{} uses a minimum indentation for script languages.
@defvr Resource indentScript (class Indent)
The minimum indentation for script languages, such as Perl, Python, and
Bash.  Default: @code{4}.
@end defvr

The maximum width of line numbers is controlled by this resource.

@defvr Resource 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: @code{4}.
@end defvr

@cindex Tab width
@lbindex Tab Width

If your source code uses a tab width different from @code{8} (the
default), you can set an alternate width using the @samp{Edit @result{}
Preferences @result{} Source @result{} Tab width} slider.

@defvr Resource tabWidth (class TabWidth)
The tab width used in the source window (default: @code{8})
@end defvr



@node Customizing Source Scrolling
@subsection Customizing Source Scrolling

These resources control when the source window is scrolled:

@defvr Resource linesAboveCursor (class LinesAboveCursor)
The minimum number of lines to show before the current location.
Default is @code{2}.
@end defvr

@defvr Resource linesBelowCursor (class LinesBelowCursor)
The minimum number of lines to show after the current location.
Default is @code{3}.
@end defvr


@node Customizing Source Lookup
@subsection Customizing Source Lookup

@lbindex Refer to Program Sources
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 @samp{Edit @result{}
Preferences @result{} Source @result{} Refer to Program Sources by full
path name} option.

This is related to the following resource:

@defvr Resource useSourcePath (class UseSourcePath)
If this is @samp{off} (default), the inferior debugger refers to
source code locations only by their base names.  If this is
@samp{on} (default), @DDD{} uses the full source code paths.
@end defvr


@lbindex Cache source files
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 @samp{Edit @result{}
Preferences @result{} Source @result{} Cache source files} option.

This is related to the following resource:

@defvr Resource cacheSourceFiles (class CacheSourceFiles)
Whether to cache source files (@samp{on}, default) or not
(@samp{off}).  Caching source files requires more memory, but makes
@DDD{} run faster.
@end defvr


@node Customizing File Filtering
@subsection Customizing File Filtering

You can control whether @DDD{} should filter files to be opened.

@defvr Resource filterFiles (class FilterFiles)
If this is @samp{on} (default), @DDD{} filters files when opening
execution files, core dumps, or source files, such that the selection
shows only suitable files.  This requires that @DDD{} opens each
file, which may take time.  If this is @samp{off}, @DDD{} always
presents all available files.
@end defvr




@node Stopping
@chapter Stopping the Program

The principal purposes of using a debugger are so that you can stop your
program before it terminates; or so that, if your program runs into
trouble, you can investigate and find out why.

Inside @DDD{}, your program may stop for any of several reasons,
such as a signal, a breakpoint, or reaching a new line after a
@DDD{} command such as @samp{Step}.  You may then examine and
change variables, set new breakpoints or remove old ones, and then
continue execution.

The inferior debuggers supported by @DDD{} support two mechanisms
for stopping a program upon specific events:

@itemize @bullet

@item
@cindex Breakpoint
A @dfn{breakpoint} makes your program stop whenever a certain point in
the program is reached.  For each breakpoint, you can add conditions to
control in finer detail whether your program stops.  Typically,
breakpoints are set before running the program.

@item
@cindex Watchpoint
A @dfn{watchpoint} is a special breakpoint that stops your program when
the value of an expression changes.
@end itemize

@menu
* Breakpoints::                 Stop at a certain point.
* Watchpoints::                 Stop at a certain condition.
* Interrupting::                Stop manually.
* Stopping X Programs::         Take care of grabbed pointers!
@end menu

@node Breakpoints
@section Breakpoints

@menu
* Setting Breakpoints::         
* Deleting Breakpoints::        
* Disabling Breakpoints::       
* Temporary Breakpoints::       
* Editing Breakpoint Properties::  
* Breakpoint Conditions::       
* Breakpoint Ignore Counts::    
* Breakpoint Commands::         
* Moving and Copying Breakpoints::  
* Looking up Breakpoints::      
* Editing all Breakpoints::     
* Hardware-Assisted Breakpoints::  
@end menu

@node Setting Breakpoints
@subsection Setting Breakpoints
@cindex Breakpoint, setting

You can set breakpoints by location or by name.

@c @node Setting Breakpoints by Location
@subsubsection Setting Breakpoints by Location

Breakpoints are set at a specific location in the program.

@lbindex Break
If the source line is visible, click with @emph{mouse button 1} on the
left of the source line and then on the @samp{Break} button.

As a faster alternative, you can simply press @emph{mouse button 3} on
the left of the source line and select the @samp{Set Breakpoint} item
from the line popup menu.

@ifnotinfo
@sp 1
@center @image{PICS/ddd-line-popup, 16cm}
@sp 1
@end ifnotinfo

As an even faster alternative, you can simply double-click on the left
of the source line to set a breakpoint.

@lbindex Break
As yet another alternative, you can select @samp{Source @result{}
Breakpoints}.  Click on the @samp{Break} button and enter the location.

(If you find this number of alternatives confusing, be aware that
@DDD{} users fall into three categories, which must all be
supported.  @emph{Novice users} explore @DDD{} and may prefer to
use one single mouse button.  @emph{Advanced users} know how to use
shortcuts and prefer popup menus.  @emph{Experienced users} prefer the
command line interface.)

Breakpoints are indicated by a plain stop sign, or as @samp{#@var{n}},
where @var{n} is the breakpoint number.  A greyed out stop sign (or
@samp{_@var{n}_}) indicates a disabled breakpoint.  A stop sign with a
question mark (or @samp{?@var{n}?}) indicates a conditional breakpoint
or a breakpoint with an ignore count set.

If you set a breakpoint by mistake, use @samp{Edit @result{} Undo} to delete
it again.


@c @node Setting Breakpoints by Name
@subsubsection Setting Breakpoints by Name

If the function name is visible, click with @emph{mouse button 1} on the
function name.  The function name is then copied to the argument field.
Click on the @samp{Break} button to set a breakpoint there.

As a shorter alternative, you can simply press @emph{mouse button 3} on
the function name and select the @samp{Break at} item from the popup
menu.

As yet another alternative, you can click on @samp{Break@dots{}} from
the Breakpoint editor (invoked through @samp{Source @result{}
Breakpoints}) and enter the function name.


@c @node Setting Regexp Breakpoints
@subsubsection Setting Regexp Breakpoints

Using @GDB{}, you can also set a breakpoint on all functions that match a
given string.  @samp{Break @result{} Set Breakpoints at Regexp ()} sets
a breakpoint on all functions whose name matches the @emph{regular
expression} given in @samp{()}.  Here are some examples:

@itemize @bullet
@item
To set a breakpoint on every function that starts with @samp{Xm}, set
@samp{()} to @samp{^Xm}.
@item
To set a breakpoint on every member of class @samp{Date}, set
@samp{()} to @samp{^Date::}.
@item
To set a breakpoint on every function whose name contains
@samp{_fun}, set @samp{()} to @samp{_fun}.
@item
To set a breakpoint on every function that ends in @samp{_test}, 
set @samp{()} to @samp{_test$}.
@end itemize



@node Deleting Breakpoints
@subsection Deleting Breakpoints
@cindex Breakpoint, deleting

@lbindex Clear
To delete a visible breakpoint, click with @emph{mouse button 1} on the
breakpoint.  The breakpoint location is copied to the argument field.
Click on the @samp{Clear} button to delete all breakpoints there.

If the function name is visible, click with @emph{mouse button 1} on the
function name.  The function name is copied to the argument field.
Click on the @samp{Clear} button to clear all breakpoints there.

@lbindex Delete Breakpoint
As a faster alternative, you can simply press @emph{mouse button 3} on
the breakpoint and select the @samp{Delete Breakpoint} item from the
popup menu.

@lbindex Delete
As yet another alternative, you can select the breakpoint and click on
@samp{Delete} in the Breakpoint editor (invoked through @samp{Source
@result{} Breakpoints}).

As an even faster alternative, you can simply double-click on the
breakpoint while holding @key{Ctrl}.


@node Disabling Breakpoints
@subsection Disabling Breakpoints
@cindex Breakpoint, disabling
@cindex Breakpoint, enabling

Rather than deleting a breakpoint or watchpoint, you might prefer to
@dfn{disable} it.  This makes the breakpoint inoperative as if it had
been deleted, but remembers the information on the breakpoint so that
you can @dfn{enable} it again later.@footnote{@JDB{} does not support
breakpoint disabling.}

@lbindex Disable Breakpoint
@lbindex Enable Breakpoint
To disable a breakpoint, press @emph{mouse button 3} on the breakpoint
symbol and select the @samp{Disable Breakpoint} item from the breakpoint
popup menu.  To enable it again, select @samp{Enable Breakpoint}.

@ifnotinfo
@sp 1
@center @image{PICS/ddd-bp-popup, 16cm}
@sp 1
@end ifnotinfo

@lbindex Disable
@lbindex Enable
As an alternative, you can select the breakpoint and click on
@samp{Disable} or @samp{Enable} in the Breakpoint editor (invoked
through @samp{Source @result{} Breakpoints}.

Disabled breakpoints are indicated by a grey stop sign, or
@samp{_@var{n}_}, where @var{n} is the breakpoint number.

@lbindex Clear
The @samp{Disable Breakpoint} item is also accessible via the
@samp{Clear} button.  Just press and hold @emph{mouse button 1} on the
button to get a popup menu.


@node Temporary Breakpoints
@subsection Temporary Breakpoints
@cindex Breakpoint, temporary

A @dfn{temporary breakpoint} is immediately deleted as soon as it is
reached.@footnote{@JDB{} does not support temporary breakpoints.}

@lbindex Set Temporary Breakpoint
To set a temporary breakpoint, press @emph{mouse button 3} on the left
of the source line and select the @samp{Set Temporary Breakpoint} item
from the popup menu.

As a faster alternative, you can simply double-click on the left of the
source line while holding @key{Ctrl}.

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.

@lbindex Continue Until Here
The @samp{Continue Until Here} item from the popup menu sets a temporary
breakpoint on the left of the source line and immediately continues
execution.  Execution stops when the temporary breakpoint is reached.

The @samp{Set Temporary Breakpoint} and @samp{Continue Until Here} items
are also accessible via the @samp{Break} button.  Just press and hold
@emph{mouse button 1} on the button to get a popup menu.




@node Editing Breakpoint Properties
@subsection Editing Breakpoint Properties
@cindex Breakpoint properties
@cindex Breakpoint, editing

You can change all properties of a breakpoint by pressing @emph{mouse
button 3} on the breakpoint symbol and select @samp{Properties}
from the breakpoint popup menu.  This will pop up a dialog showing the 
current properties of the selected breakpoint.

@ifnotinfo
@sp 1
@center @image{PICS/ddd-bp-properties, 16cm}
@sp 1
@end ifnotinfo

As an even faster alternative, you can simply double-click on the
breakpoint.

@itemize @bullet
@item
Click on @samp{Lookup} to move the cursor to the breakpoint's
location.
@lbindex Lookup
@item
Click on @samp{Enable} to enable the breakpoint.
@lbindex Enable
@item
Click on @samp{Disable} to disable the breakpoint.
@lbindex Disable
@item
Click on @samp{Temp} to make the breakpoint temporary.@footnote{@GDB{} has
no way to make a temporary breakpoint non-temporary again.}
@lbindex Temp
@item
Click on @samp{Delete} to delete the breakpoint.
@lbindex Delete
@end itemize


@node Breakpoint Conditions
@subsection Breakpoint Conditions
@cindex Conditions on breakpoints
@cindex Breakpoint conditions

The simplest sort of breakpoint breaks every time your program reaches a
specified place.  You can also specify a @dfn{condition} for a
breakpoint.  A condition is just a Boolean expression in your
programming language.  A breakpoint with a condition evaluates the
expression each time your program reaches it, and your program stops
only if the condition is @emph{true}.

@cindex Assertions and breakpoints
This is the converse of using assertions for program validation; in that
situation, you want to stop when the assertion is violated--that is,
when the condition is false.  In C, if you want to test an assertion
expressed by the condition @var{assertion}, you should set the condition
@samp{!@var{assertion}} on the appropriate breakpoint.

Break conditions can have side effects, and may even call functions in
your program.  This can be useful, for example, to activate functions
that log program progress, or to use your own print functions to format
special data structures. The effects are completely predictable unless
there is another enabled breakpoint at the same address.  (In that case,
@DDD{} might see the other breakpoint first and stop your program
without checking the condition of this one.)

@cindex Breakpoint commands, vs. conditions
Note that breakpoint commands are usually more convenient and flexible
for the purpose of performing side effects when a breakpoint is reached.
@xref{Breakpoint Commands}, for details.


@node Breakpoint Ignore Counts
@subsection Breakpoint Ignore Counts
@cindex Breakpoint ignore counts
@cindex Ignore count

A special case of a breakpoint condition is to stop only when the
breakpoint has been reached a certain number of times.  This is so
useful that there is a special way to do it, using the @dfn{ignore
count} of the breakpoint.  Every breakpoint has an ignore count, which
is an integer.  Most of the time, the ignore count is zero, and
therefore has no effect.  But if your program reaches a breakpoint whose
ignore count is positive, then instead of stopping, it just decrements
the ignore count by one and continues.  As a result, if the ignore count
value is @var{n}, the breakpoint does not stop the next @var{n} times
your program reaches it.

@lbindex Ignore Count
In the field @samp{Ignore Count} of the @samp{Breakpoint Properties}
panel, you can specify the breakpoint ignore count.@footnote{@JDB{}, Perl
and some @DBX{} variants do not support breakpoint ignore counts.}

If a breakpoint has a positive ignore count and a condition, the
condition is not checked.  Once the ignore count reaches zero,
@DDD{} resumes checking the condition.


@node Breakpoint Commands
@subsection Breakpoint Commands
@cindex Breakpoint commands
@cindex Command, breakpoint

You can give any breakpoint (or watchpoint) a series of @DDD{}
commands to execute when your program stops due to that breakpoint.  For
example, you might want to print the values of certain expressions, or
enable other breakpoints.@footnote{@JDB{}, @PYDB{}, and some @DBX{} variants do
not support breakpoint commands.}

Using the @samp{Commands} buttons of the @samp{Breakpoint Properties}
panel, you can edit commands to be executed when the breakpoint is hit.

To edit breakpoint commands, click on @samp{Edit >>} and enter the
commands in the commands editor.  When done with editing, click on
@samp{Edit <<} to close the commands editor.

Using @GDB{}, you can also @dfn{record} a command sequence to be executed.
To record a command sequence, follow these steps:

@enumerate
@item
Click on @samp{Record} to begin the recording of the breakpoint
commands.
@lbindex Record
@item
Now interact with @DDD{}.  While recording, @DDD{} does not
execute commands, but simply records them to be executed when the
breakpoint is hit.  The recorded debugger commands are shown in the
debugger console.
@item
To stop the recording, click on @samp{End} or enter @samp{end} at the
@GDB{} prompt.  To @dfn{cancel} the recording, click on @samp{Interrupt}
or press @key{ESC}.
@lbindex End
@item
You can edit the breakpoint commands just recorded using @samp{Edit >>}.
@lbindex Edit >>
@end enumerate


@node Moving and Copying Breakpoints
@subsection Moving and Copying Breakpoints
@cindex Breakpoint, moving
@cindex Breakpoint, copying
@cindex Breakpoint, dragging

To move a breakpoint to a different location, press @emph{mouse button
1} on the stop sign and drag it to the desired location.@footnote{When
glyphs are disabled (@pxref{Customizing Source}), breakpoints cannot be
dragged.  Delete and set breakpoints instead.}  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.

To copy a breakpoint to a new location, press @key{Shift} while
dragging.


@node Looking up Breakpoints
@subsection Looking up Breakpoints
@cindex Breakpoint, looking up
@cindex Looking up breakpoints

If you wish to lookup a specific breakpoint, select @samp{Source
@result{} Breakpoints @result{} Lookup}.  After selecting a breakpoint
from the list and clicking the @samp{Lookup} button, the breakpoint
location is displayed.

As an alternative, you can enter @samp{#@var{n}} in the argument field,
where @var{n} is the breakpoint number, and click on the @samp{Lookup}
button to find its definition.


@node Editing all Breakpoints
@subsection Editing all Breakpoints
@cindex Breakpoints, editing

To view and edit all breakpoints at once, select @samp{Source @result{}
Breakpoints}.  This will popup the @dfn{Breakpoint Editor} which
displays the state of all breakpoints.

@ifnotinfo
@sp 1
@center @image{PICS/ddd-edit-breakpoints, 16cm}
@sp 1
@end ifnotinfo

In the breakpoint editor, you can select individual breakpoints by
clicking on them.  Pressing @key{Ctrl} while clicking toggles the
selection.  To edit the properties of all selected breakpoints, click on
@samp{Props}.


@node Hardware-Assisted Breakpoints
@subsection Hardware-Assisted Breakpoints
@cindex Breakpoint, hardware-assisted

Using @GDB{}, a few more commands related to breakpoints can be invoked
through the debugger console:

@table @command
@item hbreak @var{position}
@cmindex hbreak
@cindex @acronym{EPROM} code debugging
@cindex @acronym{ROM} code debugging
Sets a hardware-assisted breakpoint at @var{position}.  This command
requires hardware support and some target hardware may not have this
support.  The main purpose of this is @acronym{EPROM}/@acronym{ROM} code
debugging, so you can set a breakpoint at an instruction without
changing the instruction.

@item thbreak @var{pos}
@cmindex thbreak
Set a temporary hardware-assisted breakpoint at @var{pos}.
@end table

@xref{Setting breakpoints, Setting breakpoints, Setting Breakpoints,
gdb, Debugging with @GDB{}}, for details.



@node Watchpoints
@section Watchpoints
@cindex Watchpoint

@cindex Assertions and watchpoints
You can make the program stop as soon as some variable value changes, or
when some variable is read or written.  This is called @dfn{setting a
watchpoint on a variable}.@footnote{Watchpoints are available in @GDB{} and
some @DBX{} variants only.  In @XDB{}, a similar feature is available via @XDB{}
@dfn{assertions}; see the @XDB{} documentation for details.}

Watchpoints have much in common with breakpoints: in particular, you can
enable and disable them.  You can also set conditions, ignore counts,
and commands to be executed when a watched variable changes its value.

Please note: on architectures without special watchpoint support,
watchpoints currently make the program execute two orders of magnitude
more slowly.  This is so because the inferior debugger must interrupt
the program after each machine instruction in order to examine whether
the watched value has changed.  However, this delay can be well worth it
to catch errors when you have no clue what part of your program is the
culprit.

@menu
* Setting Watchpoints::         
* Editing Watchpoint Properties::  
* Editing all Watchpoints::     
* Deleting Watchpoints::        
@end menu

@node Setting Watchpoints
@subsection Setting Watchpoints
@cindex Watchpoint, setting

If the variable name is visible, click with @emph{mouse button 1} on the
variable name.  The variable name is copied to the argument field.
Otherwise, enter the variable name in the argument field.  Click on the
@samp{Watch} button to set a watchpoint there.

@lbindex Watch
Using @GDB{} and @JDB{} 1.2, you can set different types of watchpoints.
Click and hold @emph{mouse button 1} on the @samp{Watch} button to get a
menu.


@node Editing Watchpoint Properties
@subsection Editing Watchpoint Properties
@cindex Watchpoint properties
@cindex Watchpoint, editing

@lbindex Watch
To change the properties of a watchpoint, enter the name of the watched
variable in the argument field.  Click and hold @emph{mouse button 1} on
the @samp{Watch} button and select @samp{Watchpoint Properties}.

@lbindex Print
The Watchpoint Properties panel has the same functionality as the
Breakpoint Properties panel (@pxref{Editing Breakpoint Properties}).  As
an additional feature, you can click on @samp{Print} to see the current
value of a watched variable.


@node Editing all Watchpoints
@subsection Editing all Watchpoints
@cindex Watchpoints, editing

To view and edit all watchpoints at once, select @samp{Data @result{}
Watchpoints}.  This will popup the @dfn{Watchpoint Editor} which
displays the state of all watchpoints.

@lbindex Print
The Watchpoint Editor has the same functionality as the Breakpoint
Editor (@pxref{Editing all Breakpoints}).  As an additional feature, you
can click on @samp{Print} to see the current value of a watched
variable.


@node Deleting Watchpoints
@subsection Deleting Watchpoints
@cindex Watchpoint, deleting

To delete a watchpoint, enter the name of the watched variable in the
argument field and click the @samp{Unwatch} button.


@node Interrupting
@section Interrupting

@lbindex Interrupt
@kindex ESC
@kindex Ctrl+C
@cindex SIGINT signal
If the program is already running (@pxref{Running}), you can interrupt
it any time by clicking the @samp{Interrupt} button or typing @key{ESC}
in a @DDD{} window.@footnote{If @key{Ctrl+C} is not bound to
@samp{Copy} (@pxref{Customizing the Edit Menu}), you can also use
@key{Ctrl+C} to interrupt the running program.}  Using @GDB{}, this is
equivalent to sending a @code{SIGINT} (Interrupt) signal.

@samp{Interrupt} and @key{ESC} also interrupt a running debugger
command, such as printing data.


@node Stopping X Programs
@section Stopping X Programs
@cindex X programs, stopping
@cindex X server, frozen
@cindex Mouse pointer, frozen
@cindex Display, frozen
@cindex Grabbed pointer

If your program is a modal X application, @DDD{} may interrupt it
while it has grabbed the mouse pointer, making further interaction
impossible---your X display will be unresponsive to any user actions.

By default, @DDD{} will check after each interaction whether the
pointer is grabbed.  If the pointer is grabbed, @DDD{} will
continue the debugged program such that you can continue to use your X
display.

This is how this feature works: When the program stops, @DDD{}
checks for input events such as keyboard or mouse interaction.  If
@DDD{} does not receive any event within the next 5 seconds,
@DDD{} checks whether the mouse pointer is grabbed by attempting to
grab and ungrab it.  If this attempt fails, then @DDD{} considers
the pointer grabbed.

Unfortunately, @DDD{} cannot determine the program that grabbed the
pointer---it may be the debugged program, or another program.
Consequently, you have another 10 seconds to cancel continuation before
@DDD{} continues the program automatically.

@cindex X server, locked
@cindex Display, locked
@lbindex Continue Automatically when Mouse Pointer is Frozen
There is one situation where this fails: if you lock your X display
while @DDD{} is running, then @DDD{} will consider a resulting pointer
grab as a result of running the program---and automatically continue
execution of the debugged program.  Consequently, you can turn off this
feature via @samp{Edit @result{} Preferences @result{} General @result{}
Continue Automatically when Mouse Pointer is Frozen}.


@menu
* Customizing Grab Checking::   
@end menu

@node Customizing Grab Checking
@subsection Customizing Grab Checking

The grab checks are controlled by the following resources:

@defvr Resource checkGrabs (class CheckGrabs)
If this is @samp{on} (default), @DDD{} will check after each
interaction whether the pointer is grabbed.  If this is so, @DDD{}
will automatically continue execution of debugged program.
@end defvr

@defvr Resource checkGrabDelay (class CheckGrabDelay)
The time to wait (in ms) after a debugger command before checking for a
grabbed pointer.  If @DDD{} sees some pointer event within this
delay, the pointer cannot be grabbed and an explicit check for a grabbed
pointer is unnecessary.  Default is @code{5000}, or 5 seconds.
@end defvr

@defvr Resource grabAction (class grabAction)
@cmindex cont
@cmindex kill
@cmindex quit
The action to take after having detected a grabbed mouse pointer.
This is a list of newline-separated commands.  Default is
@command{cont}, meaning to continue the debuggee.  Other possible
choices include @command{kill} (killing the debuggee) or @command{quit}
(exiting @DDD{}).
@end defvr

@defvr Resource grabActionDelay (class grabActionDelay)
The time to wait (in ms) before taking an action due to having
detected a grabbed pointer.  During this delay, a working dialog pops
up telling the user about imminent execution of the grab action (see
the @samp{grabAction} resource, above).  If the pointer grab is
released within this delay, the working dialog pops down and no action 
is taken.  This is done to exclude pointer grabs from sources other
than the debugged program (including @DDD{}).  Default is
@code{10000}, or 10 seconds.
@end defvr


@node Running
@chapter Running the Program
@cindex Running the debugged program

You may start the debugged program with its arguments, if any, in an
environment of your choice.  You may redirect your program's input and
output, debug an already running process, or kill a child process.

@menu
* Starting Program Execution::  
* Using the Execution Window::  
* Attaching to a Process::      
* Program Stop::                
* Resuming Execution::          
* Continuing Somewhere Else::   
* Stack::                       
* Undoing Program Execution::   
* Threads::                     
* Signals::                     
* Killing the Program::         
@end menu

@node Starting Program Execution
@section Starting Program Execution
@cindex Arguments, program
@cindex Program arguments

@lbindex Run
To start execution of the debugged program, select @samp{Program
@result{} Run}.  You will then be prompted for the arguments to pass 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 @samp{Run} button to start execution with the selected arguments.

@ifnotinfo
@sp 1
@center @image{PICS/ddd-arguments, 16cm}
@sp 1
@end ifnotinfo

@cmindex run
@lbindex Run
@lbindex Run Again
To run your program again, with the same arguments, select @samp{Program
@result{} Run Again} or press the @samp{Run} button on the command tool.
You may also enter @command{run}, followed by arguments at the debugger
prompt instead.

When you click on @samp{Run}, your program begins to execute
immediately.  @xref{Stopping}, for a discussion of how to arrange for
your program to stop.  Once your program has stopped, you may call
functions in your program to examine data.  @xref{Examining Data}, for
details.

If the modification time of your symbol file has changed since the last
time @GDB{} read its symbols, @GDB{} discards its symbol table, and reads it
again.  When it does this, @GDB{} and @DDD{} try to retain your
current debugger state, such as breakpoints.


@menu
* Arguments::                   Your program's arguments.
* Environment::                 Your program's environment.
* Working Directory::           Your program's directory.
* Input/Output::                Your program's I/O.
@end menu

@node Arguments
@subsection Your Program's Arguments
@cindex Arguments, of the debugged program

The arguments to your program are specified by the arguments of the
@samp{run} command, as composed in @samp{Program @result{} Run}.

@enindex SHELL
In @GDB{}, the arguments are passed to a shell, which expands wildcard
characters and performs redirection of I/O, and thence to your program.
Your @env{SHELL} environment variable (if it exists) specifies what
shell @GDB{} uses.  If you do not define @env{SHELL}, @GDB{} uses
@samp{/bin/sh}.

If you use another inferior debugger, the exact semantics on how the
arguments are interpreted depend on the inferior debugger you are using.
Normally, the shell is used to pass the arguments, so that you may use
normal conventions (such as wildcard expansion or variable substitution)
in describing the arguments.

@node Environment
@subsection Your Program's Environment
@cindex Environment, of the debugged program

Your program normally inherits its environment from the inferior
debugger, which again inherits it from @DDD{}, which again inherits
it from its parent process (typically the shell or desktop).

@cmindex unset environment
@cmindex set environment
In @GDB{}, you can use the commands @command{set environment} and
@command{unset environment} to change parts of the environment that
affect your program.  @xref{Your program's environment, Your program's
environment, Your Program's Environment, gdb, Debugging with @GDB{}},
for details.

The following environment variables are set by @DDD{}:

@table @env
@item DDD
@enindex DDD
Set to a string indicating the @DDD{} version.  By testing
whether @env{DDD} is set, a debuggee (or inferior debugger) can
determine whether it was invoked by @DDD{}.

@item TERM
@enindex TERM
Set to @samp{dumb}, the @DDD{} terminal type.  This is set for the
inferior debugger only.@footnote{If the debuggee runs in a separate
execution window, the debuggee's @env{TERM} value is set according to
the @samp{termType} resource; @xref{Customizing the Execution Window},
for details.}

@item TERMCAP
@enindex TERMCAP
Set to `' (none), the @DDD{} terminal capabilities.

@item PAGER
@enindex PAGER
Set to @samp{cat}, the preferred @DDD{} pager.
@end table

The inferior debugger, in turn, might also set or unset some environment
variables.



@node Working Directory
@subsection Your Program's Working Directory
@cindex Working directory, of the debugged program
@cindex Directory, of the debugged program

Your program normally inherits its working directory from the inferior
debugger, which again inherits it from @DDD{}, which again inherits
it from its parent process (typically the shell or desktop).

@lbindex Change Directory
You can change the working directory of the inferior debugger via
@samp{File @result{} Change Directory} or via the @samp{cd} command of
the inferior debugger.


@node Input/Output
@subsection Your Program's Input and Output
@cindex Input of the debugged program
@cindex Output of the debugged program
@cindex Redirecting I/O of the debugged program
@cindex Redirection

By default, the program you run under @DDD{} does input and output to
the debugger console.  Normally, you can redirect your program's input
and/or output using @dfn{shell redirections} with the arguments---that
is, additional arguments like @samp{< @var{input}} or @samp{>
@var{output}}.  You can enter these shell redirections just like other
arguments (@pxref{Arguments}).

@cindex Pipe
@emph{Warning:} While input and output redirection work, you cannot use
pipes to pass the output of the program you are debugging to another
program; if you attempt this, @DDD{} may wind up debugging the wrong
program.  @xref{Attaching to a Process}, for an alternative.

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.

@cindex Program output, confusing
Program output that confuses @DDD{} includes:

@itemize @bullet
@item
Primary debugger prompts (e.g. @samp{(gdb) }, @samp{(dbx) } or
@samp{(ladebug) })

@item
Secondary debugger prompts (e.g. @samp{>})

@item 
Confirmation prompts (e.g. @samp{(y or n) })

@item
Prompts for more output (e.g. @samp{Press RETURN to continue})

@item
Display output (e.g. @samp{$pc = 0x1234})
@end itemize

If your program outputs any of these strings, you may encounter problems
with @DDD{} mistaking them for debugger output.  These problems can
easily be avoided by redirecting program I/O, for instance to the
separate execution window (@pxref{Using the Execution Window}).

@cindex @acronym{TTY} settings
@pindex stty
If the inferior debugger changes the default @TTY{} settings, for
instance through a @command{stty} command in its initialization file,
@DDD{} may also become confused.  The same applies to debugged programs
which change the default @TTY{} settings.

The behavior of the debugger console can be controlled using the
following resource:

@defvr Resource lineBufferedConsole (class LineBuffered)
If this is @samp{on} (default), each line from the inferior debugger is
output on each own, such that the final line is placed at the bottom of
the debugger console.  If this is @samp{off}, all lines are output as a
whole.  This is faster, but results in a random position of the last
line.
@end defvr



@node Using the Execution Window
@section Using the Execution Window
@cindex Execution window
@cindex Redirecting I/O to the execution window

@lbindex Run in Execution Window
By default, input and output of your program go to the debugger console.
As an alternative, @DDD{} can also invoke an @dfn{execution
window}, where the program terminal input and output is
shown.@footnote{The execution window is not available in @JDB{}.}

To activate the execution window, select @samp{Program @result{} Run in
Execution Window}.

Using the execution window has an important side effect: The output of
your program no longer gets intermixed with the output of the inferior
debugger.  This makes it far easier for @DDD{} to parse the debugger
output correctly.  @xref{Debugger Communication}, for details on the
@samp{bufferGDBOutput} resource.

The execution window is opened automatically as soon as you start the
debugged program.  While the execution window is active, @DDD{}
redirects the standard input, output, and error streams of your program
to the execution window.  Note that the device @samp{/dev/tty} still
refers to the debugger console, @emph{not} the execution window.

@cindex Redirection, to execution window
You can override the @DDD{} stream redirection by giving alternate
redirection operations as arguments.  For instance, to have your program
read from @var{file}, but to write to the execution window, invoke your
program with @samp{< @var{file}} as argument.  Likewise, to redirect the
standard error output to the debugger console, use @samp{2> /dev/tty}
(assuming the inferior debugger and/or your @UNIX{} shell support standard
error redirection).

@menu
* Customizing the Execution Window::  
@end menu

@node Customizing the Execution Window
@subsection Customizing the Execution Window

You can customize the @DDD{} execution window and use a different
@TTY{} command.  The command is set by @samp{Edit @result{}
Preferences @result{} Helpers @result{} Execution Window}:
@lbindex Execution Window

@defvr Resource termCommand (class TermCommand)
The command to invoke for the execution window---a @TTY{}
emulator that shows the input/output of the debugged program.  A Bourne
shell command to run in the separate @TTY{} is appended to this
string.  The string @samp{@@FONT@@} is replaced by the name of the fixed
width font used by @DDD{}.  A simple value is

@example
Ddd*termCommand: xterm -fn @@FONT@@ -e /bin/sh -c
@end example
@pindex xterm
@end defvr

You can also set the terminal type:

@defvr Resource termType (class TermType)
The terminal type provided by the @samp{termCommand} resource---that is,
the value of the @env{TERM} environment variable to be passed to the
debugged program.  Default: @samp{xterm}.
@enindex TERM
@end defvr


Whether the execution window is active or not, as set by @samp{Program
@result{} Run in Execution Window}, is saved using this resource:

@defvr Resource separateExecWindow (class Separate)
If @samp{on}, the debugged program is executed in a separate
execution window.  If @samp{off} (default), the debugged program is
executed in the console window.
@end defvr



@node Attaching to a Process
@section Attaching to a Running Process
@cindex Process, attaching

If the debugged program is already running in some process, you can
@dfn{attach} to this process (instead of starting a new one with
@samp{Run}).@footnote{@JDB{}, @PYDB{}, Perl, and Bash do not support
attaching the debugger to running processes.}

@lbindex Attach
@lbindex Attach to Process
To attach @DDD{} to a process, select @samp{File @result{} Attach
to Process}.  You can now choose from a list of processes.  Then, press
the @samp{Attach} button to attach to the specified process.

@ifnotinfo
@sp 1
@center @image{PICS/ddd-attach, 16cm}
@sp 1
@end ifnotinfo

@cindex Continuing process execution
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 @samp{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 @samp{Continue} after attaching
@DDD{} to the process.

@lbindex Open Program
When using @samp{Attach to Process}, you should first use @samp{Open
Program} to specify the program running in the process and load its
symbol table.

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

@lbindex List Processes
You can customize the list of processes shown by defining an alternate
command to list processes.  See @samp{Edit @result{} Preferences
@result{} Helpers @result{} List Processes}; @xref{Customizing Attaching
to Processes}, for details.


@menu
* Customizing Attaching to Processes::  
@end menu

@node Customizing Attaching to Processes
@subsection Customizing Attaching to Processes

When attaching to a process (@pxref{Attaching to a Process}),
@DDD{} uses a @command{ps} command to get the list of processes.  This
command is defined by the @samp{psCommand} resource.

@defvr Resource psCommand (class PsCommand)
@pindex ps
The command to get a list of processes.  Usually @command{ps}.  Depending
on your system, useful alternate values include @command{ps -ef} and
@command{ps ux}.  The first line of the output must either contain a
@samp{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.
@end defvr


@node Program Stop
@section Program Stops

After the program has been started, it runs until one of the following
happens:

@itemize @bullet
@item
A breakpoint is reached (@pxref{Breakpoints}).

@item
A watched value changes (@pxref{Watchpoints}).

@item
The program is interrupted (@pxref{Interrupting}).

@item
A signal is received (@pxref{Signals}).

@item
Execution completes.
@end itemize

@DDD{} shows the current program status in the debugger console.
The current execution position is highlighted by an arrow.

@lbindex Uniconify When Ready
If @samp{Edit @result{} Preferences @result{} General @result{}
Uniconify When Ready} is set, @DDD{} automatically deiconifies
itself when the program stops.  This way, you can iconify @DDD{}
during a lengthy computation and have it uniconify as soon as the
program stops.


@node Resuming Execution
@section Resuming Execution

@subsection Continuing
@cindex Continuing execution
@cindex Execution, continuing

@lbindex Continue
To resume execution, at the current execution position, click on the
@samp{Continue} button.  Any breakpoints set at the current execution
position are bypassed.


@subsection Stepping one Line
@cindex Execution, one line
@cindex Continue, one line

@lbindex Step
To execute just one source line, click on the @samp{Step} button.  The
program is executed until control reaches a different source line, which
may be in a different function.  Then, the program is stopped and
control returns to @DDD{}.

@emph{Warning}: If you use the @samp{Step} button while control is
within a function that was compiled without debugging information,
execution proceeds until control reaches a function that does have
debugging information.  Likewise, it will not step into a function which
is compiled without debugging information.  To step through functions
without debugging information, use the @samp{Stepi} button
(@pxref{Machine Code Execution}).

In @GDB{}, the @samp{Step} button only stops at the first instruction of a
source line.  This prevents the multiple stops that used to occur in
switch statements, for loops, etc.  @samp{Step} continues to stop if a
function that has debugging information is called within the line.

Also, the @samp{Step} in @GDB{} only enters a subroutine if there is line
number information for the subroutine.  Otherwise it acts like the
@samp{Next} button.


@subsection Continuing to the Next Line
@cindex Execution, to next line
@cindex Continue, to next line

@lbindex Next
To continue to the next line in the current function, click on the
@samp{Next} button.  This is similar to @samp{Step}, but any function
calls appearing within the line of code are executed without stopping.

Execution stops when control reaches a different line of code at the
original stack level that was executing when you clicked on @samp{Next}.


@subsection Continuing Until Here
@cindex Execution, to location
@cindex Continue, to location

To continue running until a specific location is reached, use the
@samp{Continue Until Here} facility from the line popup menu.
@xref{Temporary Breakpoints}, for a discussion.



@subsection Continuing Until a Greater Line is Reached
@cindex Execution, until greater line is reached
@cindex Continue, until greater line is reached

@lbindex Until
To continue until a greater line in the current function is reached,
click on the @samp{Until} button.  This is useful to avoid single
stepping through a loop more than once.

@samp{Until} is like @samp{Next}, except that when @samp{Until}
encounters a jump, it automatically continues execution until the
program counter is greater than the address of the jump.

This means that when you reach the end of a loop after single stepping
though it, @samp{until} makes your program continue execution until it
exits the loop.  In contrast, clicking on @samp{Next} at the end of a
loop simply steps back to the beginning of the loop, which forces you to
step through the next iteration.

@samp{Until} always stops your program if it attempts to exit the
current stack frame.

@samp{Until} works by means of single instruction stepping, and hence is
slower than continuing until a breakpoint is reached.


@subsection Continuing Until Function Returns
@cindex Execution, until function returns
@cindex Continue, until function returns

@lbindex Finish
To continue running until the current function returns, use the
@samp{Finish} button.  The returned value (if any) is printed.


@node Continuing Somewhere Else
@section Continuing at a Different Address
@cindex Execution, at different address
@cindex Continue, at different address
@cindex Jump to different address

Ordinarily, when you continue your program, you do so at the place where
it stopped.  You can instead continue at an address of your own
choosing.

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.

@lbindex Set Execution Position
To set the execution position to the current location, use @samp{Set
Execution Position} from the breakpoint popup menu.  This item is also
accessible by pressing and holding the @samp{Break/Clear}
button.@footnote{@JDB{}, @PYDB{}, Perl, and Bash do not support
altering the execution position.}

@cindex Execution position, dragging
As a quicker alternative, you can also press @emph{mouse button 1} on
the arrow and drag it to a different location.@footnote{When glyphs are
disabled (@pxref{Customizing Source}), dragging the execution position
is not possible.  Set the execution position explicitly instead.}

@ifnotinfo
@sp 1
@center @image{PICS/ddd-drag, 16cm}
@sp 1
@end ifnotinfo

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.

@lbindex Continue
After moving the execution position, click on @samp{Continue} to resume
execution.


@node Stack
@section Examining the Stack

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

@cindex Frame
@cindex Stack frame
@cindex Call stack
Each time your program performs a function call, information about the
call is generated.  That information includes the location of the call
in your program, the arguments of the call, and the local variables of
the function being called.  The information is saved in a block of data
called a @dfn{stack frame}.  The stack frames are allocated in a region
of memory called the @dfn{call stack}.

When your program stops, the @DDD{} commands for examining the
stack allow you to see all of this information.

One of the stack frames is @dfn{selected} by @DDD{} and many
@DDD{} commands refer implicitly to the selected frame.  In
particular, whenever you ask @DDD{} for the value of a variable in
your program, the value is found in the selected frame.  There are
special @DDD{} commands to select whichever frame you are
interested in.

@menu
* Frames::                      Callers and callees.
* Backtraces::                  And you may ask yourself, `how did I get here?'
* Selecting a frame::           Moving up and down.
@end menu

@node Frames
@subsection Stack Frames

@cindex Frame
@cindex Stack Frame
The call stack is divided up into contiguous pieces called @dfn{stack
frames}, or @dfn{frames} for short; each frame is the data associated
with one call to one function.  The frame contains the arguments given
to the function, the function's local variables, and the address at
which the function is executing.

@cindex Initial frame
@cindex Outermost frame
@cindex Innermost frame
When your program is started, the stack has only one frame, that of the
function @code{main}.  This is called the @dfn{initial} frame or the
@dfn{outermost} frame.  Each time a function is called, a new frame is
made.  Each time a function returns, the frame for that function invocation
is eliminated.  If a function is recursive, there can be many frames for
the same function.  The frame for the function in which execution is
actually occurring is called the @dfn{innermost} frame.  This is the most
recently created of all the stack frames that still exist.

@cindex Frame pointer
Inside your program, stack frames are identified by their addresses.  A
stack frame consists of many bytes, each of which has its own address; each
kind of computer has a convention for choosing one byte whose
address serves as the address of the frame.  Usually this address is kept
in a register called the @dfn{frame pointer register} while execution is
going on in that frame.

@cindex Frame number
@GDB{} assigns numbers to all existing stack frames, starting with zero for
the innermost frame, one for the frame that called it, and so on upward.
These numbers do not really exist in your program; they are assigned by
@GDB{} to give you a way of designating stack frames in @GDB{} commands.


@node Backtraces
@subsection Backtraces

@DDD{} provides a @dfn{backtrace window} showing a summary of how
your program got where it is.  It shows one line per frame, for many
frames, starting with the currently executing frame (frame zero),
followed by its caller (frame one), and on up the stack.

To enable the backtrace window, select @samp{Status @result{}
Backtrace}.

@ifnotinfo
@sp 1
@center @image{PICS/ddd-backtrace, 16cm}
@sp 1
@end ifnotinfo

Using @GDB{}, each line in the backtrace shows the frame number and the
function name.  The program counter value is also shown---unless you use
the @GDB{} command @samp{set print address off}.  The backtrace also shows
the source file name and line number, as well as the arguments to the
function.  The program counter value is omitted if it is at the
beginning of the code for that line number.


@node Selecting a frame
@subsection Selecting a Frame
@cindex Frame, selecting
@cindex Selecting frames
@cindex Stack, moving within

Most commands for examining the stack and other data in your program
work on whichever stack frame is selected at the moment.  Here are the
commands for selecting a stack frame.@footnote{Perl does not allow
changing the current stack frame.}

In the backtrace window, you can @emph{select} an arbitrary frame to
move from one stack frame to another.  Just click on the desired frame.

@lbindex Up
The @samp{Up} button selects the function that called the current
one---that is, it moves one frame up.

@lbindex Down
The @samp{Down} button selects the function that was called by
the current one---that is, it moves one frame down.

@cmindex up
@cmindex down
@kindex Ctrl+Up
@kindex Ctrl+Down
You can also directly type the @command{up} and @command{down} commands at
the debugger prompt.  Typing @key{Ctrl+Up} and @key{Ctrl+Down},
respectively, will also move you through the stack.

@samp{Up} and @samp{Down} actions can be undone via @samp{Edit @result{}
Undo}.
@lbindex Undo
@cindex Undoing frame changes
@cindex Frame changes, undoing


@node Undoing Program Execution
@section ``Undoing'' Program Execution
@cindex Execution, ``undoing''
@cindex Undoing program execution

If you take a look at the @samp{Edit @result{} Undo} menu item after an
execution command, you'll find that @DDD{} offers you to undo
execution commands just as other commands.  Does this mean that
@DDD{} allows you to go backwards in time, undoing program
execution as well as undoing any side-effects of your program?

Sorry---we must disappoint you.  @DDD{} cannot undo what your
program did.  (After a little bit of thought, you'll find that this
would be impossible in general.)  However, @DDD{} can do something
different: it can show @emph{previously recorded states} of your
program.

After ``undoing'' an execution command (via
@samp{Edit @result{} Undo}, or the @samp{Undo} button), the execution
position moves back to the earlier position and displayed variables
take their earlier values.  Your program state is in fact unchanged,
but @DDD{} gives you a @emph{view} on the earlier state as recorded by
@DDD{}.

@cindex Historic mode
@lbindex Undo
@lbindex Redo
In this so-called @dfn{historic mode}, most normal @DDD{}
commands that would query further information from the program are
disabled, since the debugger cannot be queried for the earlier state.
However, you can examine the current execution position, or the
displayed variables.  Using @samp{Undo} and @samp{Redo}, you can
move back and forward in time to examine how your program got into the
present state.

To let you know that you are operating in historic mode, the execution
arrow gets a dashed-line appearance (indicating a past position);
variable displays also come with dashed lines.  Furthermore, the
status line informs you that you are seeing an earlier program state.

Here's how historic mode works: each time your program stops,
@DDD{} collects the current execution position and the values of
displayed variables.  Backtrace, thread, and register information is
also collected if the corresponding dialogs are open.  When
``undoing'' an execution command, @DDD{} updates its view
from this collected state instead of querying the program.

@cmindex cont
If you want to collect this information without interrupting your
program---within a loop, for instance---you can place a breakpoint with
an associated @command{cont} command (@pxref{Breakpoint Commands}).
When the breakpoint is hit, @DDD{} will stop, collect the data, and
execute the @samp{cont} command, resuming execution.  Using a later
@samp{Undo}, you can step back and look at every single loop iteration.

To leave historic mode, you can use @samp{Redo} until you are back in
the current program state.  However, any @DDD{} command that
refers to program state will also leave historic mode immediately by
applying to the current program state instead.  For instance,
@samp{Up} leaves historic mode immediately and selects an alternate
frame in the restored current program state.

If you want to see the history of a specific variable, as recorded
during program stops, you can enter the @DDD{} command

@example
graph history @var{name}
@end example

This returns a list of all previously recorded values of the variable
@var{name}, using array syntax.  Note that @var{name} must have been
displayed at earlier program stops in order to record values.


@node Threads
@section Examining Threads
@cindex Threads

In some operating systems, a single program may have more than one
@emph{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 @emph{current
thread}---the thread which is the focus of debugging.  @DDD{} shows
all program information from the perspective of the current
thread.@footnote{Currently, threads are supported in @GDB{} and @JDB{} only.}

@ifnotinfo
@sp 1
@center @image{PICS/ddd-threads, 16cm}
@sp 1
@end ifnotinfo

@lbindex Threads
To view all currently active threads in your program, select
@samp{Status @result{} Threads}.  The current thread is highlighted.
Select any thread to make it the current thread.

Using @JDB{}, additional functionality is available:

@itemize @bullet
@item
Select a @emph{thread group} to switch between viewing all threads and
the threads of the selected thread group;
@item
Click on @samp{Suspend} to suspend execution of the selected threads;
@item
Click on @samp{Resume} to resume execution of the selected threads.
@end itemize

For more information on threads, see the @JDB{} and @GDB{} documentation
(@pxref{Threads, Debugging programs with multiple threads, Debugging
Programs with Multiple Threads, gdb, Debugging with @GDB{}}).


@node Signals
@section Handling Signals
@cindex Signals
@cindex SIGINT signal
@cindex SIGSEGV signal
@cindex SIGALRM signal

A signal is an asynchronous event that can happen in a program.  The
operating system defines the possible kinds of signals, and gives each
kind a name and a number.  For example, in @UNIX{}, @code{SIGINT} is the
signal a program gets when you type an interrupt; @code{SIGSEGV} is
the signal a program gets from referencing a place in memory far away
from all the areas in use; @code{SIGALRM} occurs when the alarm clock
timer goes off (which happens only if your program has requested an
alarm).

@cindex Signal, fatal
Some signals, including @code{SIGALRM}, are a normal part of the
functioning of your program.  Others, such as @code{SIGSEGV}, indicate
errors; these signals are @emph{fatal} (kill your program immediately)
if the program has not specified in advance some other way to handle the
signal.  @code{SIGINT} does not indicate an error in your program, but
it is normally fatal so it can carry out the purpose of the interrupt:
to kill the program.

@GDB{} has the ability to detect any occurrence of a signal in your
program.  You can tell @GDB{} in advance what to do for each kind of
signal.

@cindex Signal settings, editing
@lbindex Signals
Normally, @DDD{} is set up to ignore non-erroneous signals like
@code{SIGALRM} (so as not to interfere with their role in the
functioning of your program) but to stop your program immediately
whenever an error signal happens.  In @DDD{}, you can view and edit
these settings via @samp{Status @result{} Signals}.

@samp{Status @result{} Signals} pops up a panel showing all the kinds of
signals and how @GDB{} has been told to handle each one.  The settings
available for each signal are:

@table @code
@item Stop
@lbindex Stop
If set, @GDB{} should stop your program when this signal happens.
This also implies @samp{Print} being set.

@item Print
@lbindex Print
If set, @GDB{} should print a message when this signal happens.

If unset, @GDB{} should not mention the occurrence of the signal at all.
This also implies @samp{Stop} being unset.

@item Pass
@lbindex Pass
If set, @GDB{} should allow your program to see this signal; your
program can handle the signal, or else it may terminate if the signal
is fatal and not handled.

If unset, @GDB{} should not allow your program to see this signal.
@end table

@ifnotinfo
@sp 1
@center @image{PICS/ddd-signals, 16cm}
@sp 1
@end ifnotinfo

@lbindex All Signals
@cindex SIGTRAP signal
The entry @samp{All Signals} is special.  Changing a setting here
affects @emph{all signals at once}---except those used by the debugger,
typically @code{SIGTRAP} and @code{SIGINT}.

@lbindex Reset
@cindex Undoing signal handling
To undo any changes, use @samp{Edit @result{} Undo}.  The @samp{Reset}
button restores the saved settings.

When a signal stops your program, the signal is not visible until you
continue.  Your program sees the signal then, if @samp{Pass} is in
effect for the signal in question @emph{at that time}.  In other words,
after @GDB{} reports a signal, you can change the @samp{Pass} setting in
@samp{Status @result{} Signals} to control whether your program sees
that signal when you continue.

@lbindex Send
You can also cause your program to see a signal it normally would not
see, or to give it any signal at any time.  The @samp{Send} button will
resume execution where your program stopped, but immediately give it the
signal shown.

@lbindex Continue Without Signal
On the other hand, you can also prevent your program from seeing a
signal.  For example, if your program stopped due to some sort of memory
reference error, you might store correct values into the erroneous
variables and continue, hoping to see more execution; but your program
would probably terminate immediately as a result of the fatal signal
once it saw the signal.  To prevent this, you can resume execution using
@samp{Commands @result{} Continue Without Signal}.

@lbindex Save Options
@lbindex Save Session As
@cindex Signal settings, saving
Signal settings are not saved across DDD invocations, since changed
signal settings are normally useful within specific projects only.
Instead, signal settings are saved with the current session, using
@samp{File @result{} Save Session As}.


@node Killing the Program
@section Killing the Program
@cindex Killing the debugged program

You can kill the process of the debugged program at any time using the
@samp{Kill} button.
@lbindex Kill

Killing the process is useful if you wish to debug a core dump instead
of a running process.  @GDB{} ignores any core dump file while your program
is running.

The @samp{Kill} button is also useful if you wish to recompile and
relink your program, since on many systems it is impossible to modify an
executable file while it is running in a process.  In this case, when
you next click on @samp{Run}, @GDB{} notices that the file has changed, and
reads the symbol table again (while trying to preserve your current
debugger state).


@node Examining Data
@chapter Examining Data

@DDD{} provides several means to examine data.

@itemize @bullet
@item 
@cindex Value tip
@cindex Tip, value
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 (called @dfn{value tip}) shows the
variable value.  This is useful for quick examination of several simple
values.

@item
@cindex Printing values
@cindex Value, printing
If you want to refer to variable values at a later time, you can
@dfn{print} the value in the debugger console.  This allows for
displaying and examining larger data structures.

@item
@cindex Displaying values
@cindex Value, displaying
If you want to examine complex data structures, you can @dfn{display}
them graphically in the data window.  Displays remain effective until
you delete them; they are updated each time the program stops.  This is
useful for large dynamic structures.

@item
@cindex Plotting values
@cindex Value, plotting
If you want to examine arrays of numeric values, you can @dfn{plot} them
graphically in a separate plot window.  The plot is updated each time
the program stops.  This is useful for large numeric arrays.

@item
Using @GDB{} or @DBX{}, you can also @dfn{examine memory contents} in any of
several formats, independently of your program's data types.
@cindex Dumping values
@cindex Value, dumping
@cindex Memory, dumping contents
@end itemize

@menu
* Value Tips::                  Just move the pointer on a variable.
* Printing Values::             Printing a value in the debugger console.
* Displaying Values::           Displaying structures as graphs.
* Plotting Values::             Displaying values as plots.
* Examining Memory::            Low-level memory examination.
@end menu

@node Value Tips
@section Showing Simple Values using Value Tips
@cindex Value tip
@cindex Tip, value

To display the value of a simple variable, move the mouse pointer on its
name.  After a second, a small window (called @dfn{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.

@ifnotinfo
@sp 1
@center @image{PICS/ddd-value-tip, 16cm}
@sp 1
@end ifnotinfo

You can disable value tips via @samp{Edit @result{} Preferences
@result{} General @result{} Automatic display of variable values as
popup tips}.

You can disable displaying variable values in the status line via
@samp{Edit @result{} Preferences @result{} General @result{} Automatic
display of variable values in the status line}.

These customizations are tied to the following resources:

@defvr Resource valueTips (class Tips)
Whether value tips are enabled (@samp{on}, default) or not
(@samp{off}).  Value tips affect @DDD{} performance and may
be distracting for some experienced users.
@end defvr

@defvr Resource valueDocs (class Docs)
Whether the display of variable values in the status line is enabled
(@samp{on}, default) or not (@samp{off}).
@end defvr



@lbindex Automatic Display of Variable Values
You can turn off value tips via @samp{Edit @result{} Preferences
@result{} General @result{} Automatic Display of Variable Values}.


@node Printing Values
@section Printing Simple Values in the Debugger Console
@cindex Printing values
@cindex Value, printing
@lbindex Print

The variable value can also be printed in the debugger console, making
it available for future operations.  To print a variable value, select
the desired variable by clicking @emph{mouse button 1} on its name.  The
variable name is copied to the argument field.  By clicking the
@samp{Print} button, the value is printed in the debugger console.  The
printed value is also shown in the status line.

As a shorter alternative, you can simply press @emph{mouse button 3} on
the variable name and select the @samp{Print} item from the popup menu.

@ifnotinfo
@sp 1
@center @image{PICS/ddd-print-popup, 16cm}
@sp 1
@end ifnotinfo

@cmindex print
@cindex Print, output formats
In @GDB{}, the @samp{Print} button generates a @command{print} command, which
has several more options.  @xref{Data, Examining Data, Examining Data,
gdb, Debugging with @GDB{}}, for @GDB{}-specific expressions, variables, and
output formats.



@node Displaying Values
@section Displaying Complex Values in the Data Window
@cindex Data Window
@cindex Value, displaying
@cindex Display
@cindex Displaying values

To explore complex data structures, you can @dfn{display} them
permanently in the @emph{data window}.  The data window displays
selected data of your program, showing complex data structures
graphically.  It is updated each time the program stops.

@menu
* Display Basics::              How to create, manipulate, and delete displays.
* Arrays::                      Special functions for arrays.
* Assignment::                  Setting variable values.
* Examining Structures::        Dereferencing pointers and other references.
* Customizing Displays::        Data Themes.
* Layouting the Graph::         Automatic layout.
* Printing the Graph::          Printing on paper.
@end menu

@node Display Basics
@subsection Display Basics

This section discusses how to create, manipulate, and delete displays.
The essentials are:

@itemize @bullet
@item
@lbindex Display
Click on @samp{Display} to display the variable in @samp{()}.

@item
Click on a display to select it.

@item
Click on @samp{Undisplay} to delete the selected display.
@lbindex Undisplay
@end itemize


@menu
* Creating Single Displays::    
* Selecting Displays::          
* Showing and Hiding Details::  
* Rotating Displays::           
* Displaying Local Variables::  
* Displaying Program Status::   
* Refreshing the Data Window::  
* Placement::                   
* Clustering::                  
* Creating Multiple Displays::  
* Editing all Displays::        
* Deleting Displays::           
@end menu

@node Creating Single Displays
@subsubsection Creating Single Displays
@cindex Display, creating
@lbindex Display

To create a new display showing a specific variable, select the variable
by clicking @emph{mouse button 1} on its name.  The variable name is
copied to the argument field.  By clicking the @samp{Display} button, a
new display is created in the data window.  The data window opens
automatically as soon as you create a display.

@ifnotinfo
@sp 1
@center @image{PICS/ddd-display, 16cm}
@sp 1
@end ifnotinfo

@lbindex Display
As a shorter alternative, you can simply press @emph{mouse button 3} on
the variable name and select @samp{Display} from the popup menu.

As an even faster alternative, you can also double-click on the variable
name.

As another alternative, you may also enter the expression to be
displayed in the argument field and press the @samp{Display} button.

Finally, you may also type in a command at the debugger prompt:

@cmindex graph display
@example
graph display @var{expr} [clustered] [at (@var{x}, @var{y})] 
    [dependent on @var{display}] [[now or] when in @var{scope}]
@end example

This command creates a new display showing the value of the expression
@var{expr}.  The optional parts have the following meaning:

@table @code
@item clustered
@cindex Clustered display, creating
@cindex Display, clustered
If given, the new display is created in a cluster.  @xref{Clustering},
for a discussion.

@item at (@var{x}, @var{y})
@cindex Display position
@cindex Position, of display
If given, the new display is created at the position (@var{x}, @var{y}).
Otherwise, a default position is assigned.

@item dependent on @var{display}
@cindex Dependent display
@cindex Display, dependent
If given, an edge from the display numbered or named @emph{display} to
the new display is created.  Otherwise, no edge is created.
@xref{Dependent Values}, for details.

@item when in @var{scope}
@itemx now or when in @var{scope}
@cindex Deferred display
@cindex Display, deferred
If @samp{when in} is given, the display creation is @dfn{deferred} until
execution reaches the given @var{scope} (a function name, as in the
backtrace output).

If @samp{now or when in} is given, @DDD{} first attempts to create
the display immediately.  The display is deferred only if display
creation fails.

If neither @samp{when in} suffix nor @samp{now or when in} suffix is
given, the display is created immediately.
@end table



@node Selecting Displays
@subsubsection Selecting Displays

@cindex Display title
@cindex Title, display
@cindex Display name
@cindex Name, display
@cindex Display value
@cindex Value, display
Each display in the data window has a @emph{title bar} containing the
@emph{display number} and the displayed expression (the @emph{display
name}).  Below the title, the @emph{display value} is shown.

@cindex Display, selecting
@cindex Selecting single displays
You can select single displays by clicking on them with @emph{mouse
button 1}.

@cindex Extending display selection
@cindex Display selection
@kindex Shift
You can @emph{extend} an existing selection by pressing the @key{Shift}
key while selecting.  You can also @emph{toggle} an existing selection
by pressing the @key{Shift} key while selecting already selected
displays.

@kindex Up
@kindex Down
@kindex Left
@kindex Right
Single displays may also be selected by using the arrow keys @key{Up},
@key{Down}, @key{Left}, and @key{Right}.

@cindex Selecting multiple displays
@emph{Multiple displays} are selected by pressing and holding
@emph{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.

@kindex Shift
If the @key{Shift} key is pressed while selecting, the existing
selection is @emph{extended}.

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

@ifnotinfo
@sp 1
@center @image{PICS/ddd-select-display, 16cm}
@sp 1
@end ifnotinfo



@node Showing and Hiding Details
@subsubsection Showing and Hiding Details

Aggregate values (i.e. records, structs, classes, and arrays) can be
shown @emph{expanded}, that is, displaying all details, or
@emph{hidden}, that is, displayed as @samp{@{@dots{}@}}.

@lbindex Show
@cindex Display, showing details
@cindex Detail, showing
@cindex Showing display details
To show details about an aggregate, select the aggregate by clicking
@emph{mouse button 1} on its name or value and click on the @samp{Show}
button.  Details are shown for the aggregate itself as well as for all
contained sub-aggregates.

@lbindex Hide
@cindex Display, hiding details
@cindex Detail, hiding
@cindex Hiding display details
To hide details about an aggregate, select the aggregate by clicking
@emph{mouse button 1} on its name or value and click on the @samp{Hide}
button.

@ifnotinfo
@sp 1
@center @image{PICS/ddd-hide-display, 16cm}
@sp 1
@end ifnotinfo

When pressing and holding @emph{mouse button 1} on the @samp{Show/Hide}
button, a menu pops up with even more alternatives:

@table @code
@item Show More ()
@lbindex 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.

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

@item Show All ()
@lbindex Show All
Shows all details of the selected aggregate and of its sub-aggregates.
This item is equivalent to the @samp{Show} button.

@item Hide ()
Hide all details of the selected aggregate.  This item is equivalent
to the @samp{Hide} button.
@lbindex Hide
@end table

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

As an even faster alternative, you can also double-click @emph{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
@emph{hide} the value instead.  This way, you can double-click on a
value until you get the right amount of details.

@cindex Disabled displays
@cindex Display, disabled
If @emph{all} details of a display are hidden, the display is called
@dfn{disabled}; this is indicated by the string @samp{(Disabled)}.

Displays can also be disabled or enabled via a @DDD{} command,
which you enter at the debugger prompt:

@cmindex graph disable display
@example
graph disable display @var{displays@dots{}}
@end example

@noindent
disables the given displays.

@cmindex graph enable display
@example
graph enable display @var{displays@dots{}}
@end example

@noindent
re-enables the given displays.

In both commands, @var{displays@dots{}} is either
@itemize @bullet
@item
a space-separated list of display numbers to disable or enable, or

@item
a single display name.  If you specify a display by name, all displays 
with this name will be affected.
@end itemize

@cindex Undo disabling displays
@cindex Disabling displays, undoing
@lbindex Undo
Use @samp{Edit @result{} Undo} to undo disabling or enabling displays.



@node Rotating Displays
@subsubsection Rotating Displays
@cindex Display, rotating

Arrays, structures and lists can be oriented horizontally or vertically.
To change the orientation of a display, select it and then click on the
@samp{Rotate} button.

As a faster alternative, you can also press @emph{mouse button 3} on the
array and select @samp{Rotate} from the popup menu.

@ifnotinfo
@sp 1
@center @image{PICS/ddd-rotate-display, 16cm}
@sp 1
@end ifnotinfo

If a structure or list is oriented horizontally, @DDD{}
automatically suppresses the member names.  This can be handy for saving
space.

The last chosen display orientation is used for the creation of new
displays.  If you recently rotated an array to horizontal orientation,
the next array you create will also be oriented horizontally.  These
settings are tied to the following resources:

@defvr Resource arrayOrientation (class Orientation)
How arrays are to be oriented.  Possible values are @samp{XmVERTICAL}
(default) and @samp{XmHORIZONTAL}.
@end defvr

@defvr Resource showMemberNames (class ShowMemberNames)
Whether to show struct member names or not.  Default is @samp{on}.
@end defvr

@defvr Resource structOrientation (class Orientation)
How structs are to be oriented.  Possible values are @samp{XmVERTICAL}
(default) and @samp{XmHORIZONTAL}.
@end defvr



@node Displaying Local Variables
@subsubsection Displaying Local Variables
@lbindex Display Local Variables
@lbindex Display Arguments
@cindex Local variables, displaying
@cindex Arguments, displaying

You can display all local variables at once by choosing @samp{Data
@result{} Display Local Variables}.  When using @DBX{}, @XDB{}, @JDB{}, or Perl,
this displays all local variables, including the arguments of the
current function.  When using @GDB{} or @PYDB{}, function arguments are
contained in a separate display, activated by @samp{Data @result{}
Display Arguments}.

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

@ifnotinfo
@sp 1
@center @image{PICS/ddd-locals, 16cm}
@sp 1
@end ifnotinfo


@node Displaying Program Status
@subsubsection Displaying Program Status

You can create a display from the output of an arbitrary debugger
command.  By entering

@cmindex graph display
@example
graph display `@var{command}`
@end example

@noindent
@cindex Status display
the output of @var{command} is turned into a @emph{status display}
updated each time the program stops.

For instance, the command

@example
graph display `where`
@end example

@noindent
creates a status display named @samp{Where} that shows the current
backtrace.

@lbindex Status Displays
If you are using @GDB{}, @DDD{} provides a panel from which you can
choose useful status displays.  Select @samp{Data @result{} Status
Displays} and pick your choice from the list.

@ifnotinfo
@sp 1
@center @image{PICS/ddd-status-displays, 16cm}
@sp 1
@end ifnotinfo

Refreshing status displays at each stop takes time; you should delete
status displays as soon as you don't need them any more.



@node Refreshing the Data Window
@subsubsection Refreshing the Data Window
@cindex Display, refreshing
@cindex Display, updating
@cindex Refreshing displayed values
@cindex Updating displayed values

The data window is automatically updated or @dfn{refreshed} each time
the program stops.  Values that have changed since the last refresh are
highlighted.

However, there may be situations where you should refresh the data
window explicitly.  This is especially the case whenever you changed
debugger settings that could affect the data format, and want the data
window to reflect these settings.

@lbindex Refresh Displays
You can refresh the data window by selecting @samp{Data @result{}
Refresh Displays}.

@lbindex Refresh Displays
As an alternative, you can press @emph{mouse button 3} on the background
of the data window and select the @samp{Refresh Displays} item.

Typing

@cmindex graph refresh
@example
graph refresh
@end example

@noindent
at the debugger prompt has the same effect.


@node Placement
@subsubsection Display Placement
@cindex Display, placement
@cindex Placement

@lbindex Left to right
@lbindex Top to bottom
@lbindex Placement
By default, displays are created from @emph{top to bottom}---that is,
each new display is placed below the downmost one.  You can change this
setting to @emph{left to right} via @samp{Edit @result{} Preferences
@result{} Data @result{} Placement @result{} Left to right}.

@ifnotinfo
@sp 1
@center @image{PICS/ddd-data-prefs, 16cm}
@sp 1
@end ifnotinfo

This setting is tied to the following resource:

@defvr Resource displayPlacement (class Orientation)
If this is @samp{XmVERTICAL} (default), @DDD{} places each new
independent display below the downmost one.  If this is
@samp{XmHORIZONTAL}, each new independent display is placed on the right
of the rightmost one.
@end defvr

Note that changing the placement of new displays also affects the
placement of @emph{dependent displays} (@pxref{Dependent Values}).  In
@emph{top to bottom} mode, dependent displays are created on the right
of the originating display; in @emph{left to right} mode, dependent
displays are created on the below the originating display.


@node Clustering
@subsubsection Clustering Displays
@cindex Cluster
@cindex Display, clustering

If you examine several variables at once, having a separate display for
each of them uses a lot of screen space.  This is why @DDD{}
supports @dfn{clusters}.  A cluster merges several logical data displays
into one physical display, saving screen space.

There are two ways to create clusters:
@itemize @bullet
@item
@lbindex Cluster
You can create clusters @emph{manually}.  This is done by selecting the
displays to be clustered and choosing @samp{Undisp @result{} Cluster
()}.  This creates a new cluster from all selected displays.  If an
already existing cluster is selected, too, the selected displays will be
clustered into the selected cluster.

@item
@lbindex Cluster Data Displays
You can create a cluster @emph{automatically} for all independent data
displays, such that all new data displays will automatically be
clustered, too.  This is achieved by enabling @samp{Edit @result{}
Preferences @result{} Data @result{} Placement @result{} clustered}.
@end itemize

@ifnotinfo
@sp 1
@center @image{PICS/ddd-clusters, 16cm}
@sp 1
@end ifnotinfo

Displays in a cluster can be selected and manipulated like parts of an
ordinary display; in particular, you can show and hide details, or
dereference pointers.  However, edges leading to clustered displays can
not be shown, and you must either select one or all clustered displays.

Disabling a cluster is called @emph{unclustering}, and again, there
are two ways of doing it:

@itemize @bullet
@item
@lbindex Uncluster
You can uncluster displays @emph{manually}, by selecting the cluster
and choosing @samp{Undisp @result{} Uncluster ()}.

@item
You can uncluster all current and future displays by disabling
@samp{Edit @result{} Preferences @result{} Data @result{} Placement @result{} 
clustered}.
@lbindex clustered
@lbindex Placement
@end itemize


@node Creating Multiple Displays
@subsubsection Creating Multiple Displays

To display several successive objects of the same type (a section of an
array, or an array of dynamically determined size), you can use the
notation @samp{@var{from}..@var{to}} in display expressions.

@var{from} and @var{to} are numbers that denote the first and last
expression to display.  Thus,

@example
graph display argv[0..9]
@end example

@noindent
creates 10 new displays for @samp{argv[0]}, @samp{argv[1]}, @dots{},
@samp{argv[9]}.  The displays are clustered automatically
(@pxref{Clustering}), such that you can easily handle the set just like
an array.

The @samp{@var{from}..@var{to}} notation can also be used multiple
times.  For instance,

@example
graph display 1..5 * 1..5
@end example

@noindent
creates a handy small multiplication table.

The @samp{@var{from}..@var{to}} notation creates several displays, which
takes time to create and update.  If you want to display only a part of
an array, @emph{array slices} are a more efficient way.  @xref{Array
Slices}, for a discussion.


@node Editing all Displays
@subsubsection Editing all Displays
@cindex Display Editor

You can view the state of all displays by selecting @samp{Data @result{}
Displays}.  This invokes the @dfn{Display Editor}.

@ifnotinfo
@sp 1
@center @image{PICS/ddd-edit-displays, 16cm}
@sp 1
@end ifnotinfo

The Display Editor shows the properties of each display, using the
following fields:

@table @samp
@item Num
The display number.

@item Expression
The displayed expression.

@item State
One of

@table @samp
@item enabled
Normal state.

@item disabled
Disabled; all details are hidden.  Use @samp{Show} to enable.

@item not active
Out of scope.

@item deferred
Will be created as soon as its @samp{Scope} is reached (@pxref{Creating
Single Displays}).

@item clustered
Part of a cluster (@pxref{Clustering}).  Use @samp{Undisp @result{}
Uncluster} to uncluster.

@item alias of @var{display}
A suppressed alias of display @var{display} (@pxref{Shared Structures}).
@end table

@item Scope
The scope in which the display was created.  For deferred displays, this 
is the scope in which the display will be created.

@item Address
The address of the displayed expression.  Used for resolving aliases
(@pxref{Shared Structures}).
@end table


@node Deleting Displays
@subsubsection Deleting Displays
@cindex Display, deleting
@cindex Deleting displays
@lbindex Undisp

To delete a single display, select its title or value and click on the
@samp{Undisp} button.  As an alternative, you can also press @emph{mouse
button 3} on the display and select the @samp{Undisplay} item.

When a display is deleted, its immediate ancestors and descendants are
automatically selected, so that you can easily delete entire graphs.

@cindex Theme, for suppressing values
@cindex Values, suppressing
@cindex Display, suppressing
@cindex Suppressing values
@lbindex Suppress Values
If you have selected only part of a display, clicking on the
@samp{Undisp} button allows you to @emph{suppress} this part---by
applying the @emph{Suppress Values} theme on the part.  You'll be asked
for confirmation first.  @xref{Using Data Themes}, for details.

@ifnotinfo
@sp 1
@center @image{PICS/ddd-suppress, 16cm}
@sp 1
@end ifnotinfo

To delete several displays at once, use the @samp{Undisp} button in the
Display Editor (invoked via @samp{Data @result{} Displays}).  Select any
number of display items in the usual way and delete them by pressing
@samp{Undisp}.

As an alternative, you can also use a @DDD{} command:

@example
graph undisplay @var{displays@dots{}}
@end example

Here, @var{displays@dots{}} is either
@itemize @bullet
@item
a space-separated list of display numbers to disable or enable, or

@item
a single display name.  If you specify a display by name, all displays 
with this name will be affected.
@end itemize

@lbindex Close data window when deleting last display
If you are using stacked windows, deleting the last display from the
data window also automatically closes the data window.  (You can change
this via @samp{Edit @result{} Preferences @result{} Data @result{} Close
data window when deleting last display}.)

@lbindex Undo
@cindex Undo deleting displays
@cindex Deleting displays, undoing
If you deleted a display by mistake, use @samp{Edit @result{} Undo} to
re-create it.

@cindex Cutting displays
@cindex Display, cutting
@cindex Copying displays
@cindex Display, copying
@cindex Pasting displays
@cindex Display, pasting
@cindex Clipboard, putting displays
@lbindex Cut
@lbindex Copy
@lbindex Paste
Finally, you can also cut, copy, and paste displays using the
@samp{Cut}, @samp{Copy}, and @samp{Paste} items from the @samp{Edit}
menu.  The clipboard holds the @emph{commands} used to create the
displays; @samp{Paste} inserts the display commands in the debugger
console.  This allows you to save displays for later usage or to copy
displays across multiple @DDD{} instances.



@node Arrays
@subsection Arrays

@DDD{} has some special features that facilitate handling of
arrays.

@menu
* Array Slices::                Displaying @var{from}..@var{to} parts of an array
* Repeated Values::             How repeated values are handled.
* Arrays as Tables::            Displaying two-dimensional arrays.
@end menu

@node Array Slices
@subsubsection Array Slices
@cindex Array slices
@cindex Array, artificial
@cindex Artificial arrays

It is often useful to print out several successive objects of the same
type in memory; a @dfn{slice} (section) of an array, or an array of
dynamically determined size for which only a pointer exists in the
program.

Using @DDD{}, you can display slices using the
@samp{@var{from}..@var{to}} notation (@pxref{Creating Multiple
Displays}).  But this requires that you already know @var{from} and
@var{to}; it is also inefficient to create several single displays.  If
you use @GDB{}, you have yet another alternative.

Using @GDB{}, you can display successive objects by referring to a
contiguous span of memory as an @dfn{artificial array}, using the binary
operator @samp{@@}.  The left operand of @samp{@@} should be the first
element of the desired array and be an individual object.  The right
operand should be the desired length of the array.  The result is an
array value whose elements are all of the type of the left argument.
The first element is actually the left argument; the second element
comes from bytes of memory immediately following those that hold the
first element, and so on.  

Here is an example.  If a program says

@example
int *array = (int *) malloc (len * sizeof (int));
@end example

@noindent
you can print the contents of @code{array} with

@example
print array[0]@@len
@end example

@noindent
and display the contents with

@example
graph display array[0]@@len
@end example

The general form of displaying an array slice is thus

@example
graph display @var{array}[@var{first}]@@@var{nelems}
@end example

@noindent
where @var{array} is the name of the array to display, @var{first} is
the index of the first element, and @var{nelems} is the number of
elements to display.

The left operand of @samp{@@} must reside in memory.  Array values made
with @samp{@@} in this way behave just like other arrays in terms of
subscripting, and are coerced to pointers when used in expressions.



@node Repeated Values
@subsubsection Repeated Values

Using @GDB{}, an array value that is repeated 10 or more times is displayed
only once.  The value is shown with a @samp{<@var{n}x>} postfix added,
where @var{n} is the number of times the value is repeated.  Thus, the
display @samp{0x0 <30x>} stands for 30 array elements, each with the
value @samp{0x0}.  This saves a lot of display space, especially with
homogeneous arrays.

@ifnotinfo
@sp 1
@center @image{PICS/ddd-repeats, 16cm}
@sp 1
@end ifnotinfo

@lbindex Threshold for repeated print elements
@lbindex Refresh Displays
The default @GDB{} threshold for repeated array values is 10.  You can
change it via @samp{Edit @result{} @GDB{} Settings @result{} Threshold for
repeated print elements}.  Setting the threshold to @code{0} will cause
@GDB{} (and @DDD{}) to display each array element individually.  Be
sure to refresh the data window via @samp{Data @result{} Refresh
Displays} after a change in @GDB{} settings.

You can also configure @DDD{} to display each array element
individually:

@defvr Resource expandRepeatedValues (class ExpandRepeatedValues)
@GDB{} can print repeated array elements as @samp{@var{value} <repeated
@var{n} times>}.  If @samp{expandRepeatedValues} is @samp{on},
@DDD{} will display @var{n} instances of @var{value} instead.  If
@samp{expandRepeatedValues} is @samp{off} (default), @DDD{} will
display @var{value} with @samp{<@var{n}x>} appended to indicate the
repetition.
@end defvr


@node Arrays as Tables
@subsubsection Arrays as Tables

@lbindex Display Two-Dimensional Arrays as Tables
By default, @DDD{} lays out two-dimensional arrays as tables, such
that all array elements are aligned with each other.@footnote{This
requires that the full array size is known to the debugger.}  To disable
this feature, unset @samp{Edit @result{} Preferences @result{} Data
@result{} Display Two-Dimensional Arrays as Tables}.  This is tied to
the following resource:

@defvr Resource align2dArrays (class Align2dArrays)
If @samp{on} (default), @DDD{} lays out two-dimensional arrays
as tables, such that all array elements are aligned with each other.
If @samp{off}, @DDD{} treats a two-dimensional array as an
array of one-dimensional arrays, each aligned on its own.
@end defvr



@node Assignment
@subsection Assignment to Variables
@cindex Assignment
@cindex Setting variables
@cindex Variables, setting
@lbindex Set

During program execution, you can change the values of arbitrary
variables.@footnote{@JDB{} 1.1 does not support changing variable values.}

To change the value of a variable, enter its name in @samp{()}---for
instance, by selecting an occurrence or a display.  Then, click on the
@samp{Set} button.  In a dialog, you can edit the variable value at
will; clicking the @samp{OK} or @samp{Apply} button commits your change
and assigns the new value to the variable.

@ifnotinfo
@sp 1
@center @image{PICS/ddd-set, 16cm}
@sp 1
@end ifnotinfo

@lbindex Set Value
To change a displayed value, you can also select @samp{Set Value} menu
from the data popup menu,

If you made a mistake, you can use @samp{Edit @result{} Undo} to re-set
the variable to its previous value.




@node Examining Structures
@subsection Examining Structures

Besides displaying simple values, @DDD{} can also visualize the
@dfn{Dependencies} between values---especially pointers and other
references that make up complex data structures.

@menu
* Dependent Values::            Edges from values to values.
* Dereferencing Pointers::      Examining pointer-based data structures.
* Shared Structures::           Multiple pointers to one display.
* Display Shortcuts::           Customize your own menus.
@end menu

@node Dependent Values
@subsubsection Displaying Dependent Values

@cindex Edge
@cindex Display, dependent
Dependent displays are created from an existing display.  The dependency
is indicated by an @dfn{edge} leading from the originating display to
the dependent display.

To create a dependent display, select the originating display or display
part and enter the dependent expression in the @samp{():} argument
field.  Then click on the @samp{Display} button.

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).
@xref{Shared Structures}, for details on how to examine such structures.


@node Dereferencing Pointers
@subsubsection Dereferencing Pointers
@cindex Dereferencing
@cindex Pointers, dereferencing

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.

@lbindex Disp *
To dereference a pointer, select the originating pointer value or name
and click on the @samp{Disp *} button.  A new display showing the
dereferenced pointer value is created.

@lbindex Display *
As a faster alternative, you can also press @emph{mouse button 3} on the
originating pointer value or name and select the @samp{Display *} menu
item.

As an even faster alternative, you can also double-click @emph{mouse
button 1} on the originating pointer value or name.  If you press
@key{Ctrl} while double-clicking, the display will be dereferenced
@emph{in place}--that is, it will be replaced by the dereferenced
display.

@lbindex Display *()
The @samp{Display *()} function is also accessible by pressing and
holding the @samp{Display} button.


@node Shared Structures
@subsubsection Shared 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 @samp{p1} and @samp{p2} point at the same data
object @samp{d}, the data displays @samp{d}, @samp{*p1}, and @samp{*p2}
will be separate, although they denote the same object.

@lbindex Detect Aliases
@cindex Aliases, detecting
@cindex Shared structures, detecting
@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
@dfn{aliases} into one single data display, the @emph{original data
display}.  This mode is called @emph{Alias Detection}; it is enabled via
@samp{Data @result{} Detect Aliases}.

When alias detection is enabled, @DDD{} inquires the memory
location (the @emph{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 @emph{original data display}); all other aliases are
@emph{suppressed}, i.e. completely hidden.  The edges leading to the
aliases are replaced by edges leading to the original data display.

@cindex Edge hint
An edge created by alias detection is somewhat special: rather than
connecting two displays directly, it goes through an @dfn{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 @samp{Undisp}.

@ifnotinfo
@sp 1
@center @image{PICS/ddd-aliases, 16cm}
@sp 1
@end ifnotinfo

To access suppressed display aliases, you can also use the Display
Editor.  Suppressed displays are listed in the Display Editor as
@emph{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

@itemize @bullet
@item
alias detection is disabled, 

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

@item
the original data display is deleted, such that the least recently
changed alias becomes the new original data display.
@end itemize

Please note the following @emph{caveats} with alias detection:

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

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

@item
Alias detection slows down @DDD{} slightly, which is why you can turn
it off.  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.
@end itemize


Alias detection is controlled by the following resources:

@defvr Resource deleteAliasDisplays (class DeleteAliasDisplays)
If this is @samp{on} (default), the @samp{Undisplay ()} button also
deletes all aliases of the selected displays.  If this is @samp{off},
only the selected displays are deleted; the aliases remain, and one of
the aliases will be unsuppressed.
@end defvr

@defvr Resource detectAliases (class DetectAliases)
If @samp{on} (default), @DDD{} attempts to recognize shared data structures.
If @samp{off}, shared data structures are not
recognized.
@end defvr

@defvr Resource typedAliases (class TypedAliases)
If @samp{on} (default), @DDD{} requires structural equivalence in
order to recognize shared data structures.  If this is @samp{off}, two
displays at the same address are considered aliases, regardless of their
structure.
@end defvr




@node Display Shortcuts
@subsubsection Display Shortcuts

@DDD{} maintains a @emph{shortcut menu} of frequently used display
expressions.  This menu is activated

@itemize @bullet
@item
by pressing and holding the @samp{Display} button, or

@item
by pressing @emph{mouse button 3} on some display and selecting
@samp{New Display}, or

@item
by pressing @key{Shift} and @emph{mouse button 3} on some display.
@end itemize

By default, the shortcut menu contains frequently used base conversions.

@lbindex Other
The @samp{Other} entry in the shortcut menu lets you create a new
display that @emph{extends} the shortcut menu.

As an example, assume you have selected a display named @samp{date_ptr}.
Selecting @samp{Display @result{} Other} pops up a dialog that allows
you to enter a new expression to be displayed---for instance, you can
cast the display @samp{date_ptr} to a new display @samp{(char
*)date_ptr}.  If the @samp{Include in @samp{New Display} Menu} toggle
was activated, the shortcut menu will then contain a new entry
@samp{Display (char *)()} that will cast @emph{any} selected display
@var{display} to @samp{(char *)@var{display}}.  Such shortcuts can save
you a lot of time when examining complex data structures.

@ifnotinfo
@sp 1
@center @image{PICS/ddd-shortcuts, 16cm}
@sp 1
@end ifnotinfo

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

@ifnotinfo
@sp 1
@center @image{PICS/ddd-shortcut-editor, 16cm}
@sp 1
@end ifnotinfo

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

@example
/t ()   // Convert to Bin
/d ()   // Convert to Dec
/x ()   // Convert to Hex
/o ()   // Convert to Oct
@end example

@lbindex New Display
Feel free to add other conversions here.  @DDD{} supports up to 20
@samp{New Display} menu items.

The shortcut menu is controlled by the following resources:

@defvr Resource dbxDisplayShortcuts (class DisplayShortcuts)
A newline-separated list of display expressions to be included in the
@samp{New Display} menu for @DBX{}.  

If a line contains a label delimiter@footnote{The string @samp{//}; can
be changed via the @samp{labelDelimiter} resource.  @xref{Customizing
Buttons}, for details.}, the string before the delimiter is used as
@var{expression}, and the string after the delimiter is used as label.
Otherwise, the label is @samp{Display @var{expression}}.  Upon
activation, the string @samp{()} in @var{expression} is replaced by the
name of the currently selected display.
@end defvr

@defvr Resource gdbDisplayShortcuts (class DisplayShortcuts)
A newline-separated list of display expressions to be included in the
@samp{New Display} menu for @GDB{}.  See the description of
@samp{dbxDisplayShortcuts}, above.
@end defvr

@defvr Resource jdbDisplayShortcuts (class DisplayShortcuts)
A newline-separated list of display expressions to be included in the
@samp{New Display} menu for @JDB{}.  See the description of
@samp{dbxDisplayShortcuts}, above.
@end defvr

@defvr Resource perlDisplayShortcuts (class DisplayShortcuts)
A newline-separated list of display expressions to be included in the
@samp{New Display} menu for Perl.  See the description of
@samp{dbxDisplayShortcuts}, above.
@end defvr

@defvr Resource bashDisplayShortcuts (class DisplayShortcuts)
A newline-separated list of display expressions to be included in the
@samp{New Display} menu for Bash.  See the description of
@samp{dbxDisplayShortcuts}, above.
@end defvr

@defvr Resource pydbDisplayShortcuts (class DisplayShortcuts)
A newline-separated list of display expressions to be included in the
@samp{New Display} menu for @PYDB{}.  See the description of
@samp{dbxDisplayShortcuts}, above.
@end defvr

@defvr Resource xdbDisplayShortcuts (class DisplayShortcuts)
A newline-separated list of display expressions to be included in the
@samp{New Display} menu for @XDB{}.  See the description of
@samp{dbxDisplayShortcuts}, above.
@end defvr




@node Customizing Displays
@subsection Customizing Displays

@cindex Display, customizing

@menu
* Using Data Themes::           
* Applying Data Themes to Several Values::  
* Editing Themes::              
* Writing Data Themes::         
* Display Resources::           
* VSL Resources::               
@end menu

@node Using Data Themes
@subsubsection Using Data Themes

@cindex Theme, Data
@cindex Data Theme

@DDD{} provides a simple method to customize displays.  @DDD{} comes
with a number of @emph{visual modifiers}, called @emph{data themes}.

Each theme modifies a particular aspect of a data display.  It can be
applied to individual displays or to a number of displays.  The themes
installed with @DDD{} include:

@table @samp
@item Small Titles
@lbindex Small Titles
If enabled, display titles in a smaller font.
@item Small Values
@lbindex Small Values
Apply this theme to display values in a smaller font.
@item Tiny Values
@lbindex Tiny Values
If enabled, display values in a tiny font.
This could be combined with a pattern like @code{*\[*\]} to make
all array members tiny.
Apply this theme to display values in a tiny font.
@item Suppress Values
@lbindex Suppress Values
If enabled, the given value will be suppressed.  This should be
combined with a pattern like @code{*->X} to suppress all members named
`X'.  Apply this theme to display values not at all.
@item Red Background
@lbindex Red Background
Use this with a self-defined button
associated with the command @code{graph apply red.vsl "()"}
@item Red nil pointers
@lbindex Red Background
If enabled, show nil pointers in red.
@item Green background
@lbindex Green background
Use this with a self-defined button associated with the command
@code{graph apply green.vsl "()"}.
@item Intel x86 flag bits and registers
@lbindex Intel x86 flab gits and registers
To use this theme, set up some data buttons like this:

@example
   Ddd*dataButtons: \
   graph display ($eflags & 1) != 0 // c\n\
   graph display ($eflags & 64) != 0 // z\n\
   graph display ($eflags & 128) != 0 // s\n\
   graph display ($eflags & 1024) != 0 // d\n\
   graph display ($eflags & 2048) != 0 // o\n\
   graph display $eax & 255 // al\n\
   graph display $eax >> 8 & 255 // ah\n\
   graph display $eax & 65535 // ax\n\
   graph display $ebx & 255 // bl\n\
   graph display $ebx >> 8 & 255 // bh\n\
   graph display $ebx & 65535 // bx\n\
   graph display $ecx & 255 // cl\n\
   graph display $ecx >> 8 & 255 // ch\n\
   graph display $ecx & 65535 // cx\n\
   graph display $edx & 255 // dl\n\
   graph display $edx >> 8 & 255 // dh\n\
   graph display $edx & 65535 // dx
@end example

Whenever the these displays is shown, the title will be replaced by a
more intuitive title like ``carry'', or ``zero'' for one of the flag bits
and ``al'' ``ax'', etc. for one of the registers.

@end table

Each of these themes can be applied for specific displays.

@ifnotinfo
@sp 1
@center @image{PICS/ddd-themes, 16cm}
@sp 1
@end ifnotinfo

@lbindex Theme
To apply a theme on a display,
@enumerate
@item
Press @emph{mouse button 3} on the display.
@item
Select @samp{Theme}
@item
Select the theme to apply.
@end enumerate

For instance, to display the variable @code{s} in a tiny font, click
@emph{mouse button 3} on the display of @code{s}, and select @samp{Theme
@result{} Tiny Values @result{} Apply}.

To unapply a theme, just click on @samp{Undo} (if you just applied it)
or repeat the sequence as above.


@node Applying Data Themes to Several Values
@subsubsection Applying Data Themes to Several Values

Whenever you want to apply a theme on a @emph{struct member} or an
@emph{array element,} you will be asked whether to

@itemize @bullet{}
@item 
apply the theme on the single value only, or
@item 
apply the theme on all similar values.
@end itemize

Suppose, for instance, that you don't want to see @samp{vptr} members
anymore.  Then you'd apply the theme @emph{Suppress Values} on all
similar values.

@lbindex Red Background
On the other hand, if you want to highlight one single value only, you'd
apply the theme @emph{Red Background} on only one single value.

If you find this confirmation annoying, you can define a command button
which directly applies the theme.  @xref{Defining Commands}, for details
on defining commands.

Applying and unapplying themes is associated with the following commands:

@cmindex graph apply theme
@example
graph apply theme @var{name} @var{pattern}
@end example
applies the theme @var{name} on @var{pattern}.

@cmindex graph unapply theme
@example
graph unapply theme @var{name} @var{pattern}
@end example
unapplies the theme @var{name} on @var{pattern}.

@cmindex graph toggle theme
@example
graph toggle theme @var{name} @var{pattern}
@end example
applies the theme @var{name} on @var{pattern} if it was not already
applied, and unapplies it otherwise.



@node Editing Themes
@subsubsection Editing Themes

@cindex Theme, editing
Each theme can be globally activated or not.  If a theme is activated,
it is applied to all expressions that match its @emph{pattern}.

Normally, these patterns are automatically maintained by simply
selecting the themes for the individual displays.  However, you can also
edit patterns directly.

Patterns are separated by @samp{;} and contain shell-like metacharacters:
@itemize @bullet{}
@item
@samp{*} matches any sequence of characters.
@item
@samp{?} matches any single character.
@item
@samp{[@var{set}]} matches any character in @var{set}.  Character ranges
can be expressed using @var{from}-@var{to}: @samp{[0-9a-zA-Z_]} is the
set of characters allowed in C characters.
@item
@samp{[!@var{set}]} matches any character not in @var{set}.
@item 
To suppress the special syntactic significance of any metacharacter\n\
and match the character exactly, precede it with @samp{\} (backslash).
@item
To suppress the syntactic significance of @emph{all} metacharacters,\n\
enclose the pattern in double or single quotes.\n\
@end itemize

@lbindex Themes
@lbindex Edit Themes
To edit the set of themes, invoke @samp{Data @result{} Themes}.

To apply changes you made to the themes, click on @samp{Apply}.
To revert the themes to the last saved, click on @samp{Reset}.


@node Writing Data Themes
@subsubsection Writing Data Themes

You can write your own data themes, customizing the display to match
your need.  @xref{Top,,, ddd-themes, Writing DDD Themes}, for details.



@node Display Resources
@subsubsection Display Resources

You can use these resources to control display appearance:

@defvr Resource autoCloseDataWindow (class AutoClose)
If this is @samp{on} (default) and @DDD{} is in stacked window
mode, deleting the last display automatically closes the data window.
If this is @samp{off}, the data window stays open even after deleting
the last display.
@end defvr

@defvr Resource bumpDisplays (class BumpDisplays)
If some display @var{d} changes size and this resource is @samp{on}
(default), @DDD{} assigns new positions to displays below and on
the right of @var{d} such that the distance between displays remains
constant.  If this is @samp{off}, other displays are not rearranged.
@end defvr

@defvr Resource clusterDisplays (class ClusterDisplays)
If @samp{on}, new independent data displays will automatically be
clustered.  Default is @samp{off}, meaning to leave new displays
unclustered.
@end defvr

@defvr Resource hideInactiveDisplays (class HideInactiveDisplays)
If some display gets out of scope and this resource is @samp{on}
(default), @DDD{} removes it from the data display.  If this is
@samp{off}, it is simply disabled.
@end defvr

@defvr Resource showBaseDisplayTitles (class ShowDisplayTitles)
Whether to assign titles to base (independent) displays or not.
Default is @samp{on}.
@end defvr

@defvr Resource showDependentDisplayTitles (class ShowDisplayTitles)
Whether to assign titles to dependent displays or not.  Default is
@samp{off}.
@end defvr

@defvr Resource suppressTheme (class Theme)
@flindex suppress.vsl
The theme to apply when selecting @samp{Undisp} on a data value.
Default is @file{suppress.vsl}.
@end defvr

@defvr Resource themes (class Themes)
A newline-separated list of themes.  Each theme has the format
@var{name}, tabulator character, @var{pattern}.
@end defvr



@node VSL Resources
@subsubsection VSL Resources

The following resources control the @VSL{} interpreter:

@defvr Resource vslBaseDefs (class VSLDefs)
A string with additional @VSL{} definitions that are appended to the
builtin @VSL{} library.  This resource is prepended to the @samp{vslDefs}
resource below and set in the @DDD{} application defaults file;
don't change it.
@end defvr

@defvr Resource vslDefs (class VSLDefs)
A string with additional @VSL{} definitions that are appended to the
builtin @VSL{} library.  The default value is an empty string.  This
resource can be used to override specific @VSL{} definitions that affect
the data display.  The preferred method, though, is to write a specific
data theme (@pxref{Writing Data Themes}).
@end defvr

@defvr Resource vslLibrary (class VSLLibrary)
The @VSL{} library to use.  @samp{builtin} (default) means to
use the built-in library, any other value is used as file name.
@end defvr

@defvr Resource vslPath (class VSLPath)
A colon-separated list of directories to search for @VSL{} include
files.  The following directory names are special:
@itemize @bullet
@item
The special directory name @samp{user_themes} stands for your individual
theme directory, typically @file{~/.@value{ddd}/themes/}.
@item
The special directory name @samp{@value{ddd}_themes} stands for the installed
theme directory, 
typically @file{/usr/local/share/@value{ddd}-@value{VERSION}/themes/}.
@end itemize
Default is @samp{user_themes:@value{ddd}_themes:.}, which means that @DDD{}
first searches your theme directory, followed by the system directory
and the current directory.
@end defvr

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

@example
Ddd*vslLibrary: /home/joe/ddd.vsl
Ddd*vslPath:    user_themes:.:/opt/src/ddd/ddd:/opt/src/ddd/vsllib
@end example

@VSL{} include files referenced by @file{/home/joe/ddd.vsl} are searched
first in the current directory @file{.}, then in your theme directory,
then in @file{/opt/src/ddd/ddd/}, and then in
@file{/opt/src/ddd/vsllib/}.

Instead of supplying another @VSL{} library, it is often easier to
specify some minor changes to the built-in library 
(@pxref{Writing Data Themes}).



@node Layouting the Graph
@subsection Layouting the Graph

If you have several displays at once, you may wish to arrange them
according to your personal preferences.  This section tells you how you
can do this.

@menu
* Moving Displays::             
* Scrolling Data::              
* Aligning Displays::           
* Automatic Layout::            
* Rotating the Graph::          
@end menu

@node Moving Displays
@subsubsection Moving Displays
@cindex Display, moving

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
@emph{mouse button 1} on the display title.  Moving the pointer while
holding the button causes all selected displays to move along with the
pointer.

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.

For fine-grain movements, selected displays may also be moved using the
arrow keys.  Pressing @key{Shift} and an arrow key moves displays by
single pixels.  Pressing @key{Ctrl} and arrow keys moves displays by
grid positions.

@kindex Up
@kindex Down
@kindex Left
@kindex Right


@node Scrolling Data
@subsubsection Scrolling Data
@cindex Scrolling

If the data window becomes too small to hold all displays, scroll bars
are created.  If your @DDD{} is set up to use @emph{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.

To change from scroll bars to panners, use @samp{Edit @result{} Startup
@result{} Data Scrolling} and choose either @samp{Panner} or
@samp{Scrollbars}.
@lbindex Data Scrolling

This setting is tied to the following resource:

@defvr Resource pannedGraphEditor (class PannedGraphEditor)
The control to scroll the graph.  

@itemize @bullet
@item
If this is @samp{on}, an Athena panner is used (a kind of
two-directional scrollbar).
@item
If this is @samp{off} (default), two M*tif scrollbars are used.
@end itemize

@xref{Options}, for the @option{--scrolled-graph-editor} and
@option{--panned-graph-editor} options.
@end defvr


@node Aligning Displays
@subsubsection Aligning Displays
@cindex Display, aligning on grid
@cindex Grid, aligning displays

You can align all displays on the nearest grid position by selecting
@samp{Data @result{} Align on Grid}.  This is useful for keeping edges
strictly horizontal or vertical.

@lbindex Auto-align Displays on Nearest Grid Point
You can enforce alignment by selecting @samp{Edit @result{} Preferences
@result{} Data @result{} Auto-align Displays on Nearest Grid Point}.  If
this feature is enabled, displays can be moved on grid positions only.


@node Automatic Layout
@subsubsection Automatic Layout

@lbindex Layout Graph
You can layout the entire graph as a tree by selecting @samp{Data
@result{} Layout Graph}.  The layout direction is determined from the
display placement (@pxref{Placement}) and from the last rotation
(@pxref{Rotating the Graph}).


@ifnotinfo
@sp 1
@center @image{PICS/ddd-layout, 16cm}
@sp 1
@end ifnotinfo

@cindex Edge hint
Layouting the graph may introduce @dfn{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.

@cindex Compact Layout
To enable a more compact layout, you can set the @samp{Edit @result{}
Preferences @result{} Data @result{} 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.

@cindex Automatic Layout
You can enforce layout by setting @samp{Edit @result{} Preferences
@result{} Data @result{} Automatic Layout}.  If automatic layout is
enabled, the graph is layouted after each change.


@node Rotating the Graph
@subsubsection Rotating the Graph
@cindex Graph, rotating
@cindex Rotating the graph
@lbindex Rotate Graph

You can rotate the entire graph clockwise by 90 degrees by selecting
@samp{Data @result{} Rotate Graph}.  You may need to layout the graph
after rotating it; @xref{Automatic Layout}, for details.


@node Printing the Graph
@subsection Printing the Graph
@cindex Graph, printing
@cindex Printing the Graph

@DDD{} allows for printing the graph picture on PostScript printers
or into files.  This is useful for documenting program states.

@ifnotinfo
@sp 1
@center @image{PICS/ddd-print-graph, 16cm}
@sp 1
@end ifnotinfo

@lbindex Print Graph
@lbindex Print Command
To print the graph on a PostScript printer, select @samp{File @result{}
Print Graph}.  Enter the printing command in the @samp{Print Command}
field.  Click on the @samp{OK} or the @samp{Apply} button to start
printing.

@lbindex File Name
As an alternative, you may also print the graph in a file.  Click on the
@samp{File} button and enter the file name in the @samp{File Name}
field.  Click on the @samp{Print} button to create the file.

When the graph is printed in a file, two formats are available:

@itemize @bullet
@item
@cindex PostScript, printing as
@samp{PostScript}---suitable for enclosing the graph in another
document;

@item
@cindex FIG file, printing as
@cindex IBMGL file, printing as
@cindex @TeX{} file, printing as
@cindex PIC file, printing as
@samp{FIG}---suitable for post-processing, using the @command{xfig}
graphic editor, or for conversion into other formats (among others,
@acronym{IBMGL}, @TeX{}, @acronym{PIC}), using the @command{transfig} or
@command{fig2dev} programs.
@pindex xfig
@pindex transfig
@pindex fig2dev
@end itemize

@ifnotinfo
@sp 1
@center @image{PICS/ddd-print-output, 16cm}
@sp 1
@end ifnotinfo

Please note the following @emph{caveats} related to printing graphs:

@itemize @bullet
@item
@lbindex Selected Only
If any displays were selected when invoking the @samp{Print} dialog, the
option @samp{Selected Only} is set.  This makes @DDD{} print only
the selected displays.

@item
@lbindex Color
@lbindex Orientation
@lbindex Paper Size
The @samp{Color}, @samp{Orientation}, and @samp{Paper Size} options are
meaningful for PostScript only.
@end itemize

These settings are tied to the following resources:

@defvr Resource printCommand (class PrintCommand)
The command to print a PostScript file.  Usually @samp{lp} or
@samp{lpr}.
@end defvr

@defvr Resource paperSize (class PaperSize)
The paper size used for printing, in format @samp{@var{width} x
@var{height}}.  The default is ISO A4 format, or @samp{210mm x 297mm}.
@end defvr



@node Plotting Values
@section Plotting Values
@cindex Values, plotting
@cindex Plotting values

If you have huge amounts of numerical data to examine, a picture often
says more than a thousand numbers.  Therefore, @DDD{} allows you to
draw numerical values in nice 2-D and 3-D plots.

@menu
* Plotting Arrays::             Plotting 1-D and 2-D arrays.
* Plot Appearance::             Controlling the appearance.
* Scalars and Composites::      Plotting simple values.
* Plotting Histories::          Plotting the history of a variable.
* Printing Plots::              Printing on paper.
* Entering Plotting Commands::  Raw Gnuplot commands.
* Exporting Plot Data::         Processing data outside of @DDD{}
* Animating Plots::             Visualizing dynamic behaviour.
* Customizing Plots::           All at your leisure.
@end menu

@node Plotting Arrays
@subsection Plotting Arrays
@cindex Array, plotting

Basically, @DDD{} can plot two types of numerical values:

@itemize @bullet
@item
One-dimensional arrays.  These are drawn in a 2-D @var{x}/@var{y} space,
where @var{x} denotes the array index, and @var{y} the element value.

@item
Two-dimensional arrays.  These are drawn in a 3-D
@var{x}/@var{y}/@var{z} space, where @var{x} and @var{y} denote the
array indexes, and @var{z} the element value.
@end itemize

To plot a fixed-size array, select its name by clicking @emph{mouse
button 1} on an occurrence.  The array name is copied to the argument
field.  By clicking the @samp{Plot} button, a new display is created in
the data window, followed by a new top-level window containing the value
plot.

To plot a dynamically sized array, you must use an array slice
(@pxref{Array Slices}).  In the argument field, enter

@example
@var{array}[@var{first}]@@@var{nelems}
@end example

@noindent
where @var{array} is the name of the array to display, @var{first} is
the index of the first element, and @var{nelems} is the number of
elements to display.  Then, click on @samp{Plot} to start the plot.

To plot a value, you can also enter a command at the debugger prompt:

@cmindex graph plot
@example
graph plot @var{expr}
@end example

@noindent
works like @samp{graph display @var{expr}} (and takes the same
arguments; @pxref{Creating Single Displays}), but the value is
additionally shown in the plot window.

Each time the value changes during program execution, the plot is
updated to reflect the current values.  The plot window remains active
until you close it (via @samp{File @result{} Close}) or until the
associated display is deleted.


@node Plot Appearance
@subsection Changing the Plot Appearance
@cindex Plot appearance

@pindex gnuplot
The actual drawing is not done by @DDD{} itself.  Instead,
@DDD{} relies on an external @command{gnuplot} program to create the
drawing.

@DDD{} adds a menu bar to the Gnuplot plot window that lets you
influence the appearance of the plot:

@itemize @bullet
@item
@lbindex View
@cindex Grid, in plots
The @samp{View} menu toggles optional parts of the plot, such as
border lines or a background grid.

@item
@lbindex Plot
@lbindex 3-D Lines
@cindex Plotting style
The @samp{Plot} menu changes the @dfn{plotting style}.  The @samp{3-D
Lines} option is useful for plotting two-dimensional arrays.

@item
@lbindex Scale
@cindex Scales, in plots
The @samp{Scale} menu allows you to enable logarithmic scaling and to 
enable or disable the scale tics.

@item
The @samp{Contour} menu adds contour lines to 3-D plots.
@lbindex Contour
@cindex Contour lines, in plots
@end itemize

@cindex Plot, scrolling
In a 3-D plot, you can use the scroll bars to change your view position.
The horizontal scroll bar rotates the plot around the @var{z} axis, that
is, to the left and right.  The vertical scroll bar rotates the plot
around the @var{y} axis, that is, up and down.

@ifnotinfo
@sp 1
@center @image{PICS/ddd-plots, 16cm}
@sp 1
@end ifnotinfo

You can also resize the plot window as desired.


@node Scalars and Composites
@subsection Plotting Scalars and Composites
@cindex Scalars, plotting

Besides plotting arrays, @DDD{} also allows you to plot scalars
(simple numerical values).  This works just like plotting arrays---you
select the numerical variable, click on @samp{Plot}, and here comes the
plot.  However, plotting a scalar is not very exciting.  A plot that
contains nothing but a scalar simply draws the scalar's value as a
@var{y} constant---that is, a horizontal line.

So why care about scalars at all?  @DDD{} allows you to combine
@emph{multiple values into one plot.}  The basic idea is: if you want to
plot something that is neither an array nor a scalar, @DDD{} takes all
numerical sub-values it can find and plots them all together in one
window.  For instance, you can plot all local variables by selecting
@samp{Data @result{} Display Local Variables}, followed by @samp{Plot}.
This will create a plot containing all numerical values as found in the
current local variables.  Likewise, you can plot all numeric members
contained in a structure by selecting it, followed by @samp{Plot}.

@cindex Cluster, and plotting
If you want more control about what to include in a plot and what not,
you can use @emph{display clusters} (@pxref{Clustering}).  A common
scenario is to plot a one-dimensional array together with the current
index position.  This is done in three steps:

@enumerate
@item
Display the array and the index, using @samp{Display}.

@item
Cluster both displays: select them and choose @samp{Undisp @result{}
Cluster ()}.

@item
Plot the cluster by pressing @samp{Plot}.
@end enumerate

Scalars that are displayed together with arrays can be displayed either
as vertical lines or horizontal lines.  By default, scalars are plotted
as horizontal lines.  However, if a scalar is a valid index for an array
that was previously plotted, it is shown as a vertical line.  You can
change this initial orientation by selecting the scalar display, followed
by @samp{Rotate}.


@node Plotting Histories
@subsection Plotting Display Histories
@cindex Display, plotting the history
@cindex Value, plotting the history
@cindex History, plotting

At each program stop, @DDD{} records the values of all displayed
variables, such that you can ``undo'' program execution (@pxref{Undoing
Program Execution}).  These @emph{display histories} can be plotted,
too.  The menu item @samp{Plot @result{} Plot history of ()} creates a
plot that shows all previously recorded values of the selected display.


@node Printing Plots
@subsection Printing Plots
@cindex Plot, printing
@cindex Printing plots
@lbindex Print Plot

If you want to print the plot, select @samp{File @result{} Print Plot}.
This pops up the @DDD{} printing dialog, set up for printing plots.
Just as when printing graphs, you have the choice between printing to a
printer or a file and setting up appropriate options.

The actual printing is also performed by Gnuplot, using the appropriate
driver.  Please note the following @emph{caveats} related to printing:

@itemize @bullet
@item
Creating @samp{FIG} files requires an appropriate driver built into
Gnuplot.  Your Gnuplot program may not contain such a driver.  In this
case, you will have to recompile Gnuplot, including the line
@samp{#define FIG} in the Gnuplot @samp{term.h} file.

@item
@lbindex Portrait
@lbindex Landscape
@lbindex Paper Size
The @samp{Portrait} option generates an @acronym{EPS} file useful for
inclusion in other documents.  The @samp{Landscape} option makes
@DDD{} print the plot in the size specified in the @samp{Paper
Size} option; this is useful for printing on a printer.  In
@samp{Portrait} mode, the @samp{Paper Size} option is ignored.

@item
The Gnuplot device drivers for PostScript and X11 each have their own
set of colors, such that the printed colors may differ from the
displayed colors.

@item
The @samp{Selected Only} option is set by default, such that only the
currently selected plot is printed.  (If you select multiple plots to be
printed, the respective outputs will all be concatenated, which may not
be what you desire.)
@lbindex Selected Only
@end itemize


@node Entering Plotting Commands
@subsection Entering Plotting Commands
@lbindex Command

Via @samp{File @result{} Command}, you can enter Gnuplot commands
directly.  Each command entered at the @samp{gnuplot>} prompt is passed
to Gnuplot, followed by a Gnuplot @samp{replot} command to update the
view.  This is useful for advanced Gnuplot tasks.

Here's a simple example.  The Gnuplot command 

@example
set xrange [@var{xmin}:@var{xmax}]
@end example

@noindent
sets the horizontal range that will be displayed to
@var{xmin}@dots{}@var{xmax}.  To plot only the elements 10 to 20, enter:

@example
gnuplot> @kbd{set xrange [10:20]}
gnuplot> _
@end example

@cmindex replot
After each command entered, @DDD{} adds a @command{replot} command, such
that the plot is updated automatically.

Here's a more complex example.  The following sequence of Gnuplot
commands saves the plot in @TeX{} format:

@cmindex set output
@cmindex set term
@example
gnuplot> @kbd{set output "plot.tex"} # Set the output filename
gnuplot> @kbd{set term latex}        # Set the output format
gnuplot> @kbd{set term x11}          # Show original picture again
gnuplot> _
@end example

Due to the implicit @command{replot} command, the output is automatically
written to @samp{plot.tex} after the @command{set term latex} command.

The dialog keeps track of the commands entered; use the arrow keys to
restore previous commands.  Gnuplot error messages (if any) are also
shown in the history area.

@flindex log
The interaction between @DDD{} and Gnuplot is logged in the file
@file{~/.@value{ddd}/log} (@pxref{Logging}).  The @DDD{}
@option{--trace} option logs this interaction on standard output.


@node Exporting Plot Data
@subsection Exporting Plot Data
@cindex Plot, exporting
@lbindex Save Data As
@pindex xmgr

If you want some external program to process the plot data (a
stand-alone Gnuplot program or the @command{xmgr} program, for instance),
you can save the plot data in a file, using @samp{File @result{} Save
Data As}.  This pops up a dialog that lets you choose a data file to
save the plotted data in.

The generated file starts with a few comment lines.  The actual data
follows in X/Y or X/Y/Z format.  It is the same file as processed by
Gnuplot.

@c Exporting plot data is only available if your plot includes exactly
@c one array.


@node Animating Plots
@subsection Animating Plots
@cindex Plot, animating
@cindex Animating plots

If you want to see how your data evolves in time, you can set a
breakpoint whose command sequence ends in a @command{cont} command
(@pxref{Breakpoint Commands}.  Each time this ``continue'' breakpoint is
reached, the program stops and @DDD{} updates the displayed values,
including the plots.  Then, @DDD{} executes the breakpoint command
sequence, resuming execution.

This way, you can set a ``continue'' breakpoint at some decisive point
within an array-processing algorithm and have @DDD{} display the
progress graphically.  When your program has stopped for good, you can
use @samp{Undo} and @samp{Redo} to redisplay and examine previous
program states.  @xref{Undoing Program Execution}, for details.



@node Customizing Plots
@subsection Customizing Plots

You can customize the Gnuplot program to invoke, as well as a number of
basic settings.


@menu
* Gnuplot Invocation::          
* Gnuplot Settings::            
@end menu

@node Gnuplot Invocation
@subsubsection Gnuplot Invocation

@lbindex Plot
Using @samp{Edit @result{} Preferences @result{} Helpers @result{}
Plot}, you can choose the Gnuplot program to invoke.  This is tied to
the following resource:

@defvr Resource plotCommand (class PlotCommand)
The name of a Gnuplot executable.  Default is @samp{gnuplot},
followed by some options to set up colors and the initial geometry.
@end defvr

@lbindex Plot Window
Using @samp{Edit @result{} Preferences @result{} Helpers @result{} Plot
Window}, you can choose whether to use the Gnuplot plot window
(@samp{External}) or to use the plot window supplied by @DDD{}
(@samp{builtin}).  This is tied to the following resource:

@defvr Resource plotTermType (class PlotTermType)
The Gnuplot terminal type.  Can have one of two values:
@itemize @bullet
@item
@cmindex mwm
If this is @samp{x11}, @DDD{} ``swallows'' the @emph{external}
Gnuplot output window into its own user interface.  Some window
managers, notably @command{mwm}, have trouble with swallowing techniques.
@item
Setting this resource to @samp{xlib} (default) makes @DDD{}
provide a @emph{builtin plot window} instead.  In this mode, plots work
well with any window manager, but are less customizable (Gnuplot
resources are not understood).
@end itemize
@end defvr

You can further control interaction with the external plot window:

@defvr Resource plotWindowClass (class PlotWindowClass)
The class of the Gnuplot output window.  When invoking Gnuplot,
@DDD{} waits for a window with this class and incorporates it into
its own user interface (unless @samp{plotTermType} is @samp{xlib}; see
above).  Default is @samp{Gnuplot}.
@end defvr

@defvr Resource plotWindowDelay (class WindowDelay)
The time (in ms) to wait for the creation of the Gnuplot window.  Before
this delay, @DDD{} looks at each newly created window to see
whether this is the plot window to swallow.  This is cheap, but
unfortunately, some window managers do not pass the creation event to
@DDD{}.  If this delay has passed, and @DDD{} has not found
the plot window, @DDD{} searches @emph{all} existing windows, which
is pretty expensive.  Default time is @code{2000}.
@end defvr


@node Gnuplot Settings
@subsubsection Gnuplot Settings

To change Gnuplot settings, use these resources:

@defvr Resource plotInitCommands (class PlotInitCommands)
The initial Gnuplot commands issued by @DDD{}.  Default is:

@example
set parametric
set urange [0:1]
set vrange [0:1]
set trange [0:1]
@end example

The @samp{parametric} setting is required to make Gnuplot understand the
data files as generated @DDD{}.  The range commands are used to
plot scalars.
@end defvr

See the Gnuplot documentation for additional commands.


@defvr Resource plot2dSettings (class PlotSettings)
Additional initial settings for 2-D plots.  Default is @samp{set
noborder}.  Feel free to customize these settings as desired.
@end defvr

@defvr Resource plot3dSettings (class PlotSettings)
Additional initial settings for 3-D plots.  Default is @samp{set
border}.  Feel free to customize these settings as desired.
@end defvr



@node Examining Memory
@section Examining Memory
@cindex Examining memory contents
@cindex Memory, examining

@lbindex Memory
Using @GDB{} or @DBX{}, you can examine memory in any of several
formats, independently of your program's data types.  The item
@samp{Data @result{} Memory} pops up a panel where you can choose the
format to be shown.

@ifnotinfo
@sp 1
@center @image{PICS/ddd-examine, 16cm}
@sp 1
@end ifnotinfo

In the panel, you can enter

@itemize @bullet
@item
a @dfn{repeat count}, a decimal integer that specifies how much memory
(counting by units) to display

@item
a @dfn{display format}---one of

@table @samp
@item octal
Print as integer in octal

@item hex
Regard the bits of the value as an integer, and print the integer 
in hexadecimal.

@item decimal
Print as integer in signed decimal.

@item unsigned
Print as integer in unsigned decimal.

@item binary
Print as integer in binary.

@item float
Regard the bits of the value as a floating point number and print
using typical floating point syntax.

@item address
Print as an address, both absolute in hexadecimal and as an offset
from the nearest preceding symbol.

@item instruction
Print as machine instructions.  The unit size is ignored for this
display format.

@item char
Regard as an integer and print it as a character constant.

@item string
Print as null-terminated string.  The unit size is ignored for this
display format.
@end table

@item
a @dfn{unit size}---one of

@table @samp
@item bytes
Bytes.

@item halfwords
Halfwords (two bytes).

@item words
Words (four bytes).

@item giants
Giant words (eight bytes).
@end table

@item
an @dfn{address}---the starting display address.  The expression need
not have a pointer value (though it may); it is always interpreted as an
integer address of a byte of memory.
@end itemize

There are two ways to examine the values:

@itemize @bullet
@item
You can dump the memory in the debugger console (using @samp{Print}).
If you repeat the resulting @samp{x} command by pressing @key{Return} in
the debugger console (@pxref{Command History}), the following area of
memory is shown.

@item
You can also display the memory dump in the data window (using
@samp{Display}).  If you choose to display the values, the values will
be updated automatically each time the program stop.
@end itemize


@node Machine-Level Debugging
@chapter Machine-Level Debugging

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.

@menu
* Machine Code::                Examining machine code.
* Machine Code Execution::      Stepping across instructions.
* Registers::                   Examining registers.
* Customizing Machine Code::    Settings.
@end menu

@node Machine Code
@section Examining Machine Code
@cindex Machine code, examining

To enable machine-level support, select @samp{Source @result{} Display
Machine Code}.  With machine code enabled, an additional @emph{machine
code window} shows up, displaying the machine code of the current
function.@footnote{The machine code window is available with @GDB{} and
some @DBX{} variants only.}  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.

@ifnotinfo
@sp 1
@center @image{PICS/ddd-code, 16cm}
@sp 1
@end ifnotinfo

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 @samp{Break} or @samp{Clear} button; the usual popup menus are also
available.  Breakpoints and the current execution position are displayed
simultaneously in both source and machine code.

The @samp{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 @samp{Lookup} to see the
corresponding code in the other window.

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

You can customize various aspects of the disassembling window.
@xref{Customizing Machine Code}, for details.


@node Machine Code Execution
@section Machine Code Execution
@cindex Machine code, executing

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:

@lbindex Stepi
@lbindex Step Instruction
@cindex Instruction, stepping
To execute just one machine instruction, click on the @samp{Stepi}
button or select @samp{Program @result{} Step Instruction}.

@lbindex Nexti
@lbindex Next Instruction
To continue to the next instruction in the current function, click on
the @samp{Nexti} button select @samp{Program @result{} Next
Instruction}..  This is similar to @samp{Stepi}, but any subroutine
calls are executed without stopping.

@cindex Program counter, displaying
Using @GDB{}, it is often useful to do 

@example
graph display /i $pc
@end example

@noindent
when stepping by machine instructions.  This makes @DDD{}
automatically display the next instruction to be executed, each time
your program stops.


@node Registers
@section Examining Registers
@cindex Registers, examining

@lbindex Registers
@DDD{} provides a @emph{register window} showing the machine
register values after each program stop.  To enable the register window,
select @samp{Status @result{} Registers}.@footnote{The machine code
window is available with @GDB{} and some @DBX{} variants only.}

@ifnotinfo
@sp 1
@center @image{PICS/ddd-registers, 16cm}
@sp 1
@end ifnotinfo

By selecting one of the registers, its name is copied to the argument
field.  You can use it as value for @samp{Display}, for instance, to
have its value displayed in the data window.


@node Customizing Machine Code
@section Customizing Machine Code

Enabling machine code via @samp{Source @result{} Display Machine Code}
(@pxref{Machine Code}) toggles the following resource:

@defvr Resource disassemble (class Disassemble)
If this is @samp{on}, the source code is automatically disassembled.
The default is @samp{off}.  @xref{Options}, for the @option{--disassemble}
and @option{--no-disassemble} options.
@end defvr

@lbindex Cache Machine Code
You can keep disassembled code in memory, using @samp{Edit @result{}
Preferences @result{} Source @result{} Cache Machine Code}:

@defvr Resource cacheMachineCode (class CacheMachineCode)
Whether to cache disassembled machine code (@samp{on}, default) or
not (@samp{off}).  Caching machine code requires more memory, but
makes @DDD{} run faster.
@end defvr

@lbindex Machine Code Indentation
You can control the indentation of machine code, using @samp{Edit
@result{} Preferences @result{} Source @result{} Machine Code
Indentation}:

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

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

@defvr Resource maxDisassemble (class MaxDisassemble)
Maximum number of bytes to disassemble (default: @code{256}).  If this
is zero, the entire current function is disassembled.
@end defvr




@node Changing the Program
@chapter Changing the Program

@DDD{} offers some basic facilities to edit and recompile the
source code, as well as patching executables and core files.

@menu
* Editing Source Code::         You can invoke a source editor from @DDD{}.
* Recompiling::                 Invoking @code{make} from within @DDD{}.
* Patching::                    Changing source and object code.
@end menu

@node Editing Source Code
@section Editing Source Code
@cindex Editing source code
@cindex Source code, editing

@lbindex Edit
@lbindex Edit Source
In @DDD{} itself, you cannot change the source file currently
displayed.  Instead, @DDD{} allows you to invoke a @emph{text
editor}.  To invoke a text editor for the current source file, select
the @samp{Edit} button or @samp{Source @result{} Edit Source}.

@lbindex Edit Sources
By default, @DDD{} tries a number of common editors.  You can
customize @DDD{} to use your favorite editor; @xref{Customizing
Editing}, for details.

After the editor has exited, the source code shown is automatically
updated.

@cindex Reloading source code
@cindex Source code, reloading
@lbindex Reload Source
If you have @DDD{} and an editor running in parallel, you can also
update the source code manually via @samp{Source @result{} Reload
Source}.  This reloads the source code shown from the source file.
Since @DDD{} automatically reloads the source code if the debugged
program has been recompiled, this should seldom be necessary.


@menu
* Customizing Editing::         
* In-Place Editing::            
@end menu

@node Customizing Editing
@subsection Customizing Editing

You can customize the editor to be used via @samp{Edit @result{}
Preferences @result{} Helpers @result{} Edit Sources}.  This is tied to
the following resource:

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

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

@pindex gnuclient
@pindex gnuserv
@pindex xemacs
This @file{~/.@value{ddd}/init} setting invokes an editing session
for an XEmacs editor running @command{gnuserv}:

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

@pindex emacsclient
@pindex emacsserver
@pindex emacs
This @file{~/.@value{ddd}/init} setting invokes an editing session for an
Emacs editor running @command{emacsserver}:

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


@node In-Place Editing
@subsection In-Place Editing

This resource is experimental:

@defvr Resource sourceEditing (class SourceEditing)
If this is @samp{on}, the displayed source code becomes editable.
This is an experimental feature; Default is @samp{off}.
@end defvr


@node Recompiling
@section Recompiling
@cindex Recompiling
@cindex Source code, recompiling
@pindex make
@lbindex Make
@cindex Make, invoking

To recompile the source code using @command{make}, you can select
@samp{File @result{} Make}.  This pops up a dialog where you can enter a
@emph{Make Target}---typically the name of the executable.  Clicking on
the @samp{Make} button invokes the @command{make} program with the given
target.

The @samp{Make} button on the command tool re-invokes @command{make}
with the most recently given arguments.


@node Patching
@section Patching
@cindex Patching
@cindex Program, patching
@cindex Emergency repairs
@cindex Debugging flags
Using @GDB{}, you can open your program's executable code (and the core
file) for both reading and writing.  This allows alterations to machine
code, such that you can intentionally patch your program's binary.  For
example, you might want to turn on internal debugging flags, or even to
make emergency repairs.

Note that depending on your operating system, special preparation steps,
such as setting permissions, may be needed before you can change
executable files.

@lbindex Writing into executable and core files
To patch the binary, enable @samp{Edit @result{} @GDB{} Settings @result{}
Writing into executable and core files}.  This makes @GDB{} open executable
and core files for both reading and writing.  If you have already loaded
a file, you must load it again (using @samp{Edit @result{} Open File} or
@samp{Edit @result{} Open Core}), for your new setting to take effect.

Be sure to turn off @samp{Writing into executable and core files} as
soon as possible, to prevent accidental alterations to machine code.


@node Commands
@chapter The Command-Line Interface

All the buttons you click within @DDD{} get eventually translated
into some debugger command, shown in the debugger console.  You can also
type in and edit these commands directly.

@menu
* Entering Commands::           Direct interaction with the inferior debugger.
* TTY mode::                    Controlling @DDD{} from a terminal.
* Integrating @DDD{}::          @DDD{} and your programming environment.
* Defining Buttons::            Add your own @DDD{} buttons.
* Defining Commands::           Add your own @DDD{} commands.
@end menu

@node Entering Commands
@section Entering Commands

In the @emph{debugger console}, you can interact with the command
interface of the inferior debugger.  Enter commands at the
@emph{debugger prompt}---that is, 
@samp{(gdb)} for @GDB{},
@samp{bashdb<>} for Bash,
@samp{(dbx)} for @DBX{}, 
@samp{>} @samp{@var{thread}[@var{depth}]} for @JDB{},
@samp{(ladebug)} for Ladebug, 
@samp{mdb<>} for the GNU Make debugger, 
@samp{DB<>} for Perl, 
@samp{(Pydb)} for @PYDB{}, 
or @samp{>} for @XDB{}.
You can use arbitrary debugger commands; use the
@key{Return} key to enter them.

@menu
* Command Completion::          Using the @key{TAB} key.
* Command History::             Repeating previous commands.
* Typing in the Source Window::  
@end menu

@node Command Completion
@subsection Command Completion
@cindex Completion of commands
@cindex Command completion

When using @GDB{} or Perl, you can use the @key{TAB} key for
@emph{completing} commands and arguments.  This works in the debugger
console as well as in all other text windows.

@GDB{} can fill in the rest of a word in a command for you, if there is
only one possibility; it can also show you what the valid possibilities
are for the next word in a command, at any time.  This works for @GDB{}
commands, @GDB{} subcommands, and the names of symbols in your program.

Press the @key{TAB} key whenever you want @GDB{} to fill out the rest
of a word.  If there is only one possibility, @GDB{} fills in the
word, and waits for you to finish the command (or press @key{RET} to
enter it).  For example, if you type
@example
(gdb) @kbd{info bre_@key{TAB}}
@end example

@noindent
@GDB{} fills in the rest of the word @samp{breakpoints}, since that is
the only @command{info} subcommand beginning with @samp{bre}:

@example
(gdb) @kbd{info breakpoints}
@end example

@noindent
You can either press @key{RET} at this point, to run the @command{info
breakpoints} command, or backspace and enter something else, if
@samp{breakpoints} does not look like the command you expected.  (If you
were sure you wanted @command{info breakpoints} in the first place, you
might as well just type @key{RET} immediately after @samp{info bre}, to
exploit command abbreviations rather than command completion).

If there is more than one possibility for the next word when you press
@key{TAB}, @DDD{} sounds a bell.  You can either supply more
characters and try again, or just press @key{TAB} a second time; @GDB{}
displays all the possible completions for that word.  For example, you
might want to set a breakpoint on a subroutine whose name begins with
@samp{make_}, but when you type @kbd{b make_@key{TAB}}, @DDD{} just
sounds the bell.  Typing @key{TAB} again displays all the function names
in your program that begin with those characters.  If you type @key{TAB} 
again, you cycle through the list of completions, for example:

@example
(gdb) @kbd{b make}_ @key{TAB}
@exdent @DDD{} sounds bell; press @key{TAB} again, to see:
make_a_section_from_file     make_environ               
make_abs_section             make_function_type         
make_blockvector             make_pointer_type          
make_cleanup                 make_reference_type        
make_command                 make_symbol_completion_list
(gdb) @kbd{b make}_ @key{TAB}
@exdent @DDD{} presents one expansion after the other:
(gdb) b make_a_section_from_file @key{TAB}
(gdb) b make_abs_section @key{TAB}
(gdb) b make_blockvector @key{TAB}
@end example

@noindent
After displaying the available possibilities, @GDB{} copies your partial
input (@samp{b make_} in the example) so you can finish the command---by 
pressing @key{TAB} again, or by entering the remainder manually.

@cindex Quotes in commands
@cindex Completion of quoted strings
Sometimes the string you need, while logically a ``word'', may contain
parentheses or other characters that @GDB{} normally excludes from its
notion of a word.  To permit word completion to work in this situation,
you may enclose words in @code{'} (single quote marks) in @GDB{} commands.

The most likely situation where you might need this is in typing the
name of a C++ function.  This is because C++ allows function overloading
(multiple definitions of the same function, distinguished by argument
type).  For example, when you want to set a breakpoint you may need to
distinguish whether you mean the version of @code{name} that takes an
@code{int} parameter, @code{name(int)}, or the version that takes a
@code{float} parameter, @code{name(float)}.  To use the word-completion
facilities in this situation, type a single quote @code{'} at the
beginning of the function name.  This alerts @GDB{} that it may need to
consider more information than usual when you press @key{TAB} to request
word completion:

@example
(gdb) @kbd{b 'bubble(}_@key{TAB}
bubble(double,double)    bubble(int,int)
(gdb) @kbd{b 'bubble(}_
@end example

In some cases, @DDD{} can tell that completing a name requires
using quotes.  When this happens, @DDD{} inserts the quote for you
(while completing as much as it can) if you do not type the quote in the
first place:

@example
(gdb) @kbd{b bub}_@key{TAB}
@exdent @DDD{} alters your input line to the following, and rings a bell:
(gdb) @kbd{b 'bubble(}_
@end example

@noindent
In general, @DDD{} can tell that a quote is needed (and inserts it)
if you have not yet started typing the argument list when you ask for
completion on an overloaded symbol.

If you prefer to use the @key{TAB} key for switching between items,
unset @samp{Edit @result{} Preferences @result{} General @result{} TAB
Key completes in All Windows}.  This is useful if you have
pointer-driven keyboard focus (see below) and no special usage for the
@key{TAB} key.  If the option is set, the @key{TAB} key completes in the
debugger console only.  

This option is tied to the following resource:

@defvr Resource globalTabCompletion (class GlobalTabCompletion)
If this is @samp{on} (default), the @key{TAB} key completes arguments in
all windows.  If this is @samp{off}, the @key{TAB} key completes
arguments in the debugger console only.
@end defvr



@node Command History
@subsection Command History

@cindex Command, repeating
@cindex Command, searching
@cindex Command history
@cindex Searching commands
@kindex Up
@kindex Down
@kindex Return
You can @emph{repeat} previous and next commands by pressing the
@key{Up} and @key{Down} arrow keys, respectively.  This presents you
previous and later commands on the command line; use @key{Return} to
apply the current command.

If you enter an empty line (just use @key{Return} at the debugger
prompt), the last command is repeated as well.

@samp{Commands @result{} Command History} shows the command history.

@ifnotinfo
@sp 1
@center @image{PICS/ddd-history, 16cm}
@sp 1
@end ifnotinfo

@kindex Ctrl+B
@kindex Ctrl+F
@kindex ESC
You can @emph{search} for previous commands by pressing @key{Ctrl+B}.
This invokes @emph{incremental search mode,} where you can enter a
string to be searched in previous commands.  Press @key{Ctrl+B} again to
repeat the search, or @key{Ctrl+F} to search in the reverse direction.
To return to normal mode, press @key{ESC}, or use any cursor command.

The command history is automatically saved when exiting @DDD{}.
You can turn off this feature by setting the following resource to
@samp{off}:

@defvr Resource saveHistoryOnExit (class SaveOnExit)
If @samp{on} (default), the command history is automatically saved
when @DDD{} exits.
@end defvr

@c FIXME: more on history


@node Typing in the Source Window
@subsection Typing in the Source Window

@cindex Source file, typing into
As a special convenience, anything you type into the source window is
automatically forwarded to the debugger console.  Thus, you don't have
to change the keyboard focus explicitly in order to enter commands.

You can change this behaviour using the following resource:

@defvr Resource consoleHasFocus (class ConsoleHasFocus)
If @samp{on} (default), all keyboard events in the source window are
automatically forwarded to the debugger console.  If @samp{off},
keyboard events are not forwarded.  If @samp{auto}, keyboard events
forwarded only if the debugger console is open.
@end defvr




@node TTY mode
@section Entering Commands at the TTY
@cindex @acronym{TTY} interface

Rather than entering commands at the debugger console, you may prefer to
enter commands at the terminal window @DDD{} was invoked from.

When @DDD{} is invoked using the @option{--tty} option, it enables its
@emph{@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.

By default, the debugger console remains closed if @DDD{} is
invoked using the @option{--tty} option.  Use @samp{View @result{}
Debugger Console} to open it.


@cindex Readline
@DDD{} can be configured to use the @samp{readline} library for reading
in commands from standard input.  This @GNU{} library provides
consistent behavior for programs which provide a command line interface
to the user.  Advantages are @GNU{} Emacs-style or @dfn{vi}-style inline
editing of commands, @command{csh}-like history substitution, and a
storage and recall of command history across debugging sessions.
@xref{Command Line Editing, Command Line Editing, Command Line Editing,
gdb, Debugging with @GDB{}}, for details on command-line editing via the
@TTY{} interface.



@node Integrating @DDD{}
@section Integrating @value{DDD}
@cindex Integrating @DDD{}

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

To have @DDD{} run as an inferior debugger in other front-ends, the
general idea is to set up your debugger front-end such that
@samp{@value{ddd} --tty} is invoked instead of the inferior debugger.
When @DDD{} is invoked using the @option{--tty} option, it enables its
@emph{@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{} @option{-fullname}
option to have @GDB{} report source code positions, the @option{--tty}
option is not required.  @DDD{} recognizes the @option{-fullname}
option, finds that it has been invoked from a debugger front-end and
automatically enables the @TTY{} interface.

If @DDD{} is invoked with the @option{-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 @samp{View} menu to re-enable these
windows.


@subsection Using @value{DDD} with Emacs
@cindex Emacs, integrating @DDD{}
@pindex emacs
To integrate @DDD{} with Emacs, use @kbd{M-x gdb} or @kbd{M-x dbx}
in Emacs to start a debugging session.  At the prompt, enter
@command{@value{ddd} --tty} (followed by @option{--dbx} or
@option{--gdb}, if required), and the name of the program to be
debugged.  Proceed as usual.


@subsection Using @value{DDD} with XEmacs
@cindex XEmacs, integrating @DDD{}
@pindex xemacs
@flindex .emacs
To integrate @DDD{} with XEmacs, set the variable
@code{gdb-command-name} to @samp{"ddd"}, by inserting the following line
in your @file{~/.emacs} file:

@example
(setq gdb-command-name "@value{ddd}")
@end example

You can also evaluate this expression by pressing @key{ESC} @key{:} and
entering it directly (@key{ESC} @key{ESC} for XEmacs 19.13 and earlier).

To start a @DDD{} debugging session in XEmacs, use @samp{M-x gdb} or
@samp{M-x gdbsrc}.  Proceed as usual.



@subsection Using @value{DDD} with @acronym{XXGDB}
@cindex @acronym{XXGDB}, integrating @DDD{}
@pindex xxgdb
To integrate @DDD{} with @acronym{XXGDB}, invoke @command{xxgdb} as

@example
xxgdb -db_name @value{ddd} -db_prompt '(gdb) '
@end example


@node Defining Buttons
@section Defining Buttons
@cindex Buttons, defining

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

@cindex Button editor
To define individual buttons, use the @emph{Button Editor}, invoked via
@samp{Commands @result{} Edit Buttons}.  The button editor displays a
text, where each line contains the command for exactly one button.
Clicking on @samp{OK} creates the appropriate buttons from the text.  If
the text is empty (the default), no button is created.

@lbindex Edit Buttons
As a simple example, assume you want to create a @samp{print i}
button.  Invoke @samp{Commands @result{} Edit Buttons} and enter a line
saying @samp{print i} in the button editor.  Then click on
@samp{OK}.  A button named @samp{Print i} will now appear below the
debugger console---try it!  To remove the button, reopen the button
editor, clear the @samp{print i} line and press @samp{OK} again.

If a button command contains @samp{()}, the string @samp{()} will
automatically be replaced by the contents of the argument field.  For
instance, a button named @samp{return ()} will execute the @GDB{}
@samp{return} command with the current content of the argument field as
argument.

@lbindex Enable supported buttons only
By default, @DDD{} disables buttons whose commands are not
supported by the inferior debugger.  To enable such buttons, unset the
@samp{Enable supported buttons only} toggle in the button editor.

@ifnotinfo
@sp 1
@center @image{PICS/ddd-button-editor, 16cm}
@sp 1
@end ifnotinfo

@DDD{} also allows you to specify control sequences and special
labels for user-defined buttons.  @xref{Customizing Buttons}, for
details.


@menu
* Customizing Buttons::         Adding your own command buttons.
@end menu

@node Customizing Buttons
@subsection Customizing Buttons

@DDD{} allows defining additional command buttons; @xref{Defining
Buttons}, for doing this interactively.  This section describes the
resources that control user-defined buttons.

@defvr Resource 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:
@itemize @bullet
@item
Commands ending with @code{@dots{}} insert their name, followed by a
space, in the debugger console.

@item
Commands ending with a control character (that is, @samp{^} followed
by a letter or @samp{?}) insert the given control character.

@item
The string @samp{()} is replaced by the current contents 
of the argument field @samp{()}.

@item
The string specified in the @samp{labelDelimiter} resource (usually
@samp{//}) separates the command name from the button label.  If no
button label is specified, the capitalized command will be used as
button label.
@end itemize

The following button names are reserved:

@table @samp
@item Apply
Send the given command to the debugger.

@item Back
Lookup previously selected source position.

@item Clear
Clear current command

@item Complete
Complete current command.

@item Edit
Edit current source file.

@item Forward
Lookup next selected source position.

@item Make
Invoke the @samp{make} program, using the most recently given arguments.

@item Next
Show next command

@item No
Answer current debugger prompt with @samp{no}.  This button is
visible only if the debugger asks a yes/no question.

@item Prev
Show previous command

@item Reload
Reload source file.

@item Yes
Answer current debugger prompt with @samp{yes}.  This button is
visible only if the debugger asks a yes/no question.
@end table

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

Here are some examples to insert into your @file{~/.@value{ddd}/init} file.
These are the settings of @DDD{} 1.x:
@example
@value{Ddd}*consoleButtons: Yes\nNo\nbreak^C
@end example

This setting creates some more buttons:
@example
  @value{Ddd}*consoleButtons: \
  Yes\nNo\nrun\nClear\nPrev\nNext\nApply\nbreak^C
@end example

See also the @samp{dataButtons}, @samp{sourceButtons} and
@samp{toolButtons} resources.
@end defvr

@defvr Resource 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
@samp{consoleButtons} resource, above, for details on button syntax.

The default resource value is empty---no source buttons are
created.
@end defvr


@defvr Resource 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
@samp{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 @file{~/.@value{ddd}/init} file.
These are the settings of @DDD{} 1.x:

@example
@value{Ddd}*sourceButtons: \
  run\nstep\nnext\nstepi\nnexti\ncont\n\
  finish\nkill\nup\ndown\n\
  Back\nForward\nEdit\ninterrupt^C
@end example

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

@example
  @value{Ddd}*sourceButtons: \
  print *()\ngraph display *()\nprint /x ()\n\
  whatis ()\nptype ()\nwatch ()\nuntil\nshell
@end example

An even more professional setting uses customized button labels.

@example
  @value{Ddd}*sourceButtons: \
  print *(()) // Print *()\n\
  graph display *(()) // Display *()\n\
  print /x ()\n\
  whatis () // What is ()\n\
  ptype ()\n\
  watch ()\n\
  until\n\
  shell
@end example

See also the @samp{consoleButtons} and @samp{dataButtons} resources,
above, and the @samp{toolButtons} resource, below.
@end defvr

@defvr Resource toolButtons (class Buttons)
A newline-separated list of buttons to be included in the command tool
or the command tool bar (@pxref{Disabling the Command Tool}).  Each
button issues the command given by its name.  @xref{Defining Buttons},
for details on button syntax.

The default resource value is

@example
Ddd*toolButtons: \
run\nbreak^C\nstep\nstepi\nnext\nnexti\n\
until\nfinish\ncont\n\kill\n\
up\ndown\nBack\nForward\nEdit\nMake
@end example

For each button, its location in the command tool must be specified
using @samp{XmForm} constraint resources.  See the @samp{Ddd}
application defaults file for instructions.

If the @samp{toolButtons} resource value is empty, the command tool is
not created.
@end defvr


The following resources set up button details:

@defvr Resource labelDelimiter (class LabelDelimiter)
The string used to separate labels from commands and shortcuts.
Default is @samp{//}.
@end defvr

@defvr Resource verifyButtons (class VerifyButtons)
If @samp{on} (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 @samp{off}, no checking is
done: all commands are accepted ``as is''.
@end defvr




@node Defining Commands
@section Defining Commands
@cindex Command, defining
@cindex Command, user-defined
@cindex User-defined command

Aside from breakpoint commands (@pxref{Breakpoint Commands}),
@DDD{} also allows you to define user-defined commands.  A
@emph{user-defined command} is a sequence of commands to which you
assign a new name as a command.  This new command can be entered at the
debugger prompt or invoked via a button.

@menu
* GDB Simple Commands::         
* GDB Argument Commands::       
* Commands with Other Debuggers::  
@end menu

@node GDB Simple Commands
@subsection Defining Simple Commands using GDB
@cindex Command, defining in @GDB{}

Aside from breakpoint commands (see @samp{Breakpoint commands},
above), @DDD{} also allows you to store sequences of commands
as a user-defined @GDB{} command.  A @emph{user-defined command}
is a sequence of @GDB{} commands to which you assign a new name
as a command.  Using @DDD{}, this is done via the @emph{Command
Editor}, invoked via @samp{Commands @result{} Define Command}.

A @GDB{} command is created in five steps:

@enumerate
@item
@lbindex Command
Enter the name of the command in the @samp{Command} field.  Use the
drop-down list on the right to select from already defined commands.

@item
@lbindex Record
@cindex Recording commands
@cindex Command, recording
Click on @samp{Record} to begin the recording of the command sequence.

@item
Now interact with @DDD{}.  While recording, @DDD{} does not
execute commands, but simply records them to be executed when the
breakpoint is hit.  The recorded debugger commands are shown in the
debugger console.

@item
@lbindex End
To stop the recording, click on @samp{End} or enter @samp{end} at
the @GDB{} prompt.  To @emph{cancel} the recording, click on
@samp{Interrupt} or press @key{ESC}.

@item
@lbindex Edit >>
@lbindex Edit <<
Click on @samp{Edit >>} to edit the recorded commands.
When done with editing, click on @samp{Edit <<} to close the
commands editor.
@end enumerate

@lbindex Execute
After the command is defined, you can enter it at the @GDB{} prompt.  You
may also click on @samp{Execute} to test the given user-defined command.

@lbindex Button
For convenience, you can assign a button to the defined command.
Enabling one of the @samp{Button} locations will add a button with the
given command to the specified location.  If you want to edit the
button, select @samp{Commands @result{} Edit Buttons}.  @xref{Defining
Buttons}, for a discussion.

@ifnotinfo
@sp 1
@center @image{PICS/ddd-define-command, 16cm}
@sp 1
@end ifnotinfo

When user-defined @GDB{} commands are executed, the commands of the
definition are not printed.  An error in any command stops execution of
the user-defined command.@footnote{If you use @DDD{} commands
within command definitions, or if you include debugger commands that
resume execution, these commands will be realized transparently as
@dfn{auto-commands}---that is, they won't be executed directly by the
inferior debugger, but result in a command string being sent to
@DDD{}.  This command string is then interpreted by @DDD{} and
sent back to the inferior debugger, possibly prefixed by some other
commands such that @DDD{} can update its state.  @xref{Commands
with Other Debuggers}, for a discussion.}

If used interactively, commands that would ask for confirmation
proceed without asking when used inside a user-defined command.  Many
@GDB{} commands that normally print messages to say what they are
doing omit the messages when used in a user-defined command.

Command definitions are saved across @DDD{} sessions.


@node GDB Argument Commands
@subsection Defining Argument Commands using GDB
@cindex Command, argument

@lbindex ()
If you want to pass arguments to user-defined commands, you can enable 
the @samp{()} toggle button in the Command Editor.  Enabling
@samp{()} has two effects:

@itemize @bullet
@item
While recording commands, all references to the argument field are taken
@emph{symbolically} instead of literally.  The argument field value is
frozen to @samp{$arg0}, which is how @GDB{} denotes the argument of a
user-defined command.  When @GDB{} executes the command, it will replace
@samp{$arg0} by the current command argument.

@item
When assigning a button to the command, the command will be suffixed by
the current contents of the argument field.
@end itemize

While defining a command, you can toggle the @samp{()} button as you
wish to switch between using the argument field symbolically and
literally.

@cmindex contuntil
As an example, let us define a command @command{contuntil} that will set a
breakpoint in the given argument and continue execution.

@enumerate
@item
Enter @samp{contuntil} in the @samp{Command} field.

@item
Enable the @samp{()} toggle button.

@item
Now click on @samp{Record} to start recording.  Note that the
contents of the argument field change to @samp{$arg0}.

@item
Click on @samp{Break at ()} to create a breakpoint.  Note that the
recorded breakpoint command refers to @samp{$arg0}.

@item
Click on @samp{Cont} to continue execution.

@item
Click on @samp{End} to end recording.  Note that the argument field
is restored to its original value.

@item
Finally, click on one of the @samp{Button} locations.  This creates a 
@samp{Contuntil ()} button where @samp{()} will be replaced by the
current contents of the argument field---and thus passed to the
@samp{contuntil} command.

@item
You can now either use the @samp{Contuntil ()} button or enter a
@samp{contuntil} command at the @GDB{} prompt.  (If you plan to
use the command frequently, you may wish to define a @samp{cu}
command, which again calls @samp{contuntil} with its argument.  This
is a nice exercise.)
@end enumerate

There is a little drawback with argument commands: a user-defined
command in @GDB{} has no means to access the argument list as a whole; only
the first argument (up to whitespace) is processed.  This may change in
future @GDB{} releases.


@node Commands with Other Debuggers
@subsection Defining Commands using Other Debuggers
@cindex Command, defining with other debuggers

If your inferior 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:

@itemize @bullet
@item
In contrast to the well-documented commands of the inferior debugger,
@DDD{} does not know what a user-defined command does.  This may
lead to inconsistencies between @DDD{} and the inferior debugger.
For instance, if your the user-defined command @samp{bp} sets a
breakpoint, @DDD{} may not display it immediately, because
@DDD{} does not know that @samp{bp} changes the breakpoint state.

@item
You cannot use @DDD{} @samp{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.
@end itemize

@cindex Auto-command
@cindex Command, auto
As a solution, @DDD{} provides a simple facility called
@dfn{auto-commands}.  If @DDD{} receives any output from the
inferior debugger in the form @samp{@var{prefix} @var{command}}, it will
interpret @var{command} as if it had been entered at the debugger
prompt.  @var{prefix} is a user-defined string, for example
@samp{@value{ddd}: }.

@cmindex gd
Suppose you want to define a command @command{gd} that serves as
abbreviation for @command{graph display}.  All the command @command{gd} has
to do is to issue a string

@example
@value{ddd}: graph display @var{argument}
@end example

where @var{argument} is the argument given to @command{gd}.  Using
@GDB{}, this can be achieved using the @command{echo} command.  In
your @file{~/.gdbinit} file, insert the lines

@example
define gd
  echo @value{ddd}: graph display $arg0\n
end
@end example

To complete the setting, you must also set the @samp{autoCommandPrefix}
resource to the @samp{@value{ddd}: } prefix you gave in your command.
In @file{~/.@value{ddd}/init}, write:

@example
Ddd*autoCommandPrefix: @value{ddd}:\ 
@end example

@noindent
(Be sure to leave a space after the trailing backslash.)

Entering @command{gd foo} will now have the same effect as entering
@command{graph display foo} at the debugger prompt.

Please note: In your commands, you should choose some other prefix than
@samp{@value{ddd}: }.  This is because auto-commands raise a security
problem, since arbitrary commands can be executed.  Just imagine some
malicious program issuing a string like @samp{@var{prefix} shell rm -fr
~} when being debugged!  As a consequence, be sure to choose your own
@var{prefix}; it must be at least three characters long.





@node Application Defaults
@appendix Application Defaults

@flindex Ddd
Like any good X citizen, @DDD{} comes with a large
application-defaults file named @file{Ddd}.  This appendix documents the
actions and images referenced in @file{Ddd}, such that you can easily
modify them.

@menu
* Actions::                     All actions used in translation tables.
* Images::                      All images used in resources,
@end menu

@node Actions
@section Actions

The following @DDD{} actions may be used in translation tables.

@menu
* General Actions::             
* Data Display Actions::        
* Debugger Console Actions::    
* Source Window Actions::       
@end menu

@node General Actions
@subsection General Actions


@deffn Action ddd-get-focus ()
Assign focus to the element that just received input.
@end deffn

@deffn Action ddd-next-tab-group ()
Assign focus to the next tab group.
@end deffn

@deffn Action ddd-prev-tab-group ()
Assign focus to the previous tab group.
@end deffn

@deffn Action ddd-previous-tab-group ()
Assign focus to the previous tab group.
@end deffn


@node Data Display Actions
@subsection Data Display Actions

These actions are used in the @DDD{} graph editor.

@deffn Action end ()
End the action initiated by @code{select}.  Bound to a button up event.
@end deffn

@deffn Action extend ()
Extend the current selection.  Bound to a button down event.
@end deffn

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

@deffn Action follow ()
Continue the action initiated by @code{select}.  Bound to a pointer
motion event.
@end deffn

@deffn Action graph-select ()
Equivalent to @code{select}, but also updates the current argument.
@end deffn

@deffn Action graph-select-or-move ()
Equivalent to @code{select-or-move}, but also updates the current argument.
@end deffn

@deffn Action graph-extend ()
Equivalent to @code{extend}, but also updates the current argument.
@end deffn

@deffn Action graph-extend-or-move ()
Equivalent to @code{extend-or-move}, but also updates the current argument.
@end deffn

@deffn Action graph-toggle ()
Equivalent to @code{toggle}, but also updates the current argument.
@end deffn

@deffn Action graph-toggle-or-move ()
Equivalent to @code{toggle-or-move}, but also updates the current argument.
@end deffn

@deffn Action graph-popup-menu ([@code{graph}|@code{node}|@code{shortcut}])
Pops up a menu.  @code{graph} pops up a menu with global graph
operations, @code{node} pops up a menu with node operations, and
@code{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 @key{Shift} key pressed, behaves like
@code{shortcut}; when pointing on a without the @key{Shift} key pressed,
behaves like @code{node}; otherwise, behaves as if @code{graph} was
given.
@end deffn

@deffn Action graph-dereference ()
Dereference the selected display.
@end deffn

@deffn Action graph-detail ()
Show or hide detail of the selected display.
@end deffn

@deffn Action graph-rotate ()
Rotate the selected display.
@end deffn

@deffn Action graph-dependent ()
Pop up a dialog to create a dependent display.
@end deffn

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

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

@deffn Action move-selected (x-offset, y-offset)
Move all selected nodes in the direction given by @var{x-offset} and
@var{y-offset}.  @var{x-offset} and @var{y-offset} is either given as a
numeric pixel value, or as @samp{+grid}, or @option{-grid}, meaning the
current grid size.
@end deffn

@deffn Action normalize ()
Place all nodes on their positions and redraw the graph.
@end deffn

@deffn Action rotate ([[@code{+}|@code{-}]degrees])
Rotate the graph around @var{degrees} degrees.  
@var{degrees} must be a multiple of 90.  Default is @code{+90}.
@end deffn

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

@deffn Action select-all ()
Select all nodes in the graph.
@end deffn

@deffn Action select-first ()
Select the first node in the graph.
@end deffn

@deffn Action select-next ()
Select the next node in the graph.
@end deffn

@deffn Action 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.
@end deffn

@deffn Action select-prev ()
Select the previous node in the graph.
@end deffn

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

@deffn Action snap-to-grid ()
Place all nodes on the nearest grid position.
@end deffn

@deffn Action 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.
@end deffn

@deffn Action 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.
@end deffn

@deffn Action unselect-all ()
Clear the selection.
@end deffn


@node Debugger Console Actions
@subsection Debugger Console Actions


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

@deffn Action gdb-backward-character ()
Move one character to the left.  Bound to @code{Left}.
@end deffn

@deffn Action gdb-beginning-of-line ()
Move cursor to the beginning of the current line, after the prompt.
Bound to @code{HOME}.
@end deffn

@deffn Action gdb-control (control-character)
Send the given @var{control-character} to the inferior debugger.
@var{control-character} must be specified in the form @samp{^@var{X}},
where @var{X} is an upper-case letter, or @samp{?}.
@end deffn

@deffn Action gdb-command (command)
Execute @var{command} in the debugger console.  The following
replacements are performed on @var{command}:

@itemize @bullet
@item
If @var{command} has the form @samp{@var{name}@dots{}}, insert @var{name},
followed by a space, in the debugger console.

@item
All occurrences of @samp{()} are replaced by the current contents of
the argument field @samp{()}.

@end itemize
@end deffn

@deffn Action gdb-complete-arg (command)
Complete current argument as if @var{command} was prepended.
Bound to @key{Ctrl+T}.
@end deffn

@deffn Action gdb-complete-command ()
Complete current command line in the debugger console.
Bound to @key{TAB}.
@end deffn

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

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

@deffn Action gdb-end-of-line ()
Move cursor to the end of the current line.  Bound to @code{End}.
@end deffn

@deffn Action gdb-forward-character ()
Move one character to the right.  Bound to @code{Right}.
@end deffn

@deffn Action gdb-insert-graph-arg ()
Insert the contents of the data display argument field @samp{()}.
@end deffn

@deffn Action gdb-insert-source-arg ()
Insert the contents of the source argument field @samp{()}.
@end deffn

@deffn Action gdb-interrupt ()
If @DDD{} is in incremental search mode, exit it; otherwise
call @code{gdb-control(^C)}.
@end deffn

@deffn Action gdb-isearch-prev ()
Enter reverse incremental search mode.  Bound to @key{Ctrl+B}.
@end deffn

@deffn Action gdb-isearch-next ()
Enter incremental search mode.  Bound to @key{Ctrl+F}.
@end deffn

@deffn Action gdb-isearch-exit ()
Exit incremental search mode.  Bound to @key{ESC}.
@end deffn

@deffn Action gdb-next-history ()
Recall next command from history.  Bound to @code{Down}.
@end deffn

@deffn Action gdb-prev-history ()
Recall previous command from history.  Bound to @code{Up}.
@end deffn

@deffn Action gdb-previous-history ()
Recall previous command from history.  Bound to @code{Up}.
@end deffn

@deffn Action gdb-process ([action [, args@dots{}]])
Process the given event in the debugger console.  Bound to key events
in the source and data window.  If this action is bound to the source
window, and the source window is editable, perform
@code{@var{action}(@var{args}@dots{})} on the source window instead; if
@var{action} is not given, perform @samp{self-insert()}.
@end deffn

@deffn Action gdb-select-all ()
If the @samp{selectAllBindings} resource is set to @code{Motif},
perform @samp{beginning-of-line}.  Otherwise, perform @samp{select-all}.
Bound to @key{Ctrl+A}.
@end deffn

@deffn Action gdb-set-line (value)
Set the current line to @var{value}.  Bound to @key{Ctrl+U}.
@end deffn


@node Source Window Actions
@subsection Source Window Actions


These actions are used in the source and code windows.

@deffn Action source-delete-glyph ()
Delete the breakpoint related to the glyph at cursor position.
@end deffn


@deffn Action source-double-click ([text-action [, line-action [, function-action]]])
The double-click action in the source window.

@itemize @bullet{}
@item
If this action is taken on a breakpoint glyph, edit the breakpoint
properties.
@item
If this action is taken in the breakpoint area, invoke
@samp{gdb-command(@var{line-action})}.  If @var{line-action} is not
given, it defaults to @samp{break ()}.
@item
If this action is taken in the source text, and the next character
following the current selection is @samp{(}, invoke
@samp{gdb-command(@var{function-action})}.  If @var{function-action}
is not given, it defaults to @samp{list ()}.
@item
Otherwise, invoke @samp{gdb-command(@var{text-action})}.  If
@var{text-action} is not given, it defaults to @samp{graph display ()}.
@end itemize
@end deffn

@deffn Action source-drag-glyph ()
Initiate a drag on the glyph at cursor position.
@end deffn

@deffn Action source-drop-glyph ([action])
Drop the dragged glyph at cursor position.  @var{action} is either
@samp{move}, meaning to move the dragged glyph, or @samp{copy},
meaning to copy the dragged glyph.  If no @var{action} is given,
@samp{move} is assumed.
@end deffn

@deffn Action source-end-select-word ()
End selecting a word.
@end deffn

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

@deffn Action source-popup-menu ()
Pop up a menu, depending on the location.
@end deffn

@deffn Action source-set-arg ()
Set the argument field to the current selection.  Typically bound to
some selection operation.
@end deffn

@deffn Action source-start-select-word ()
Start selecting a word.
@end deffn

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



@node Images
@section Images

@DDD{} installs a number of images that may be used as pixmap
resources, simply by giving a symbolic name.  For button images,
three variants are installed as well:

@itemize @bullet
@item
The suffix @option{-hi} indicates a highlighted variant (Button is entered).
@item
The suffix @option{-arm} indicates an armed variant (Button is pushed).
@item
The suffix @option{-xx} indicates a disabled (insensitive) variant.
@end itemize

@defvr Image break_at
@samp{Break at ()} button.
@end defvr

@defvr Image clear_at
@samp{Clear at ()} button.
@end defvr

@defvr Image ddd
@DDD{} icon.
@end defvr

@defvr Image delete
@samp{Delete ()} button.
@end defvr

@defvr Image disable
@samp{Disable} button.
@end defvr

@defvr Image dispref
@samp{Display * ()} button.
@end defvr

@defvr Image display
@samp{Display ()} button.
@end defvr

@defvr Image drag_arrow
The execution pointer (being dragged).
@end defvr

@defvr Image drag_cond
A conditional breakpoint (being dragged).
@end defvr

@defvr Image drag_stop
A breakpoint (being dragged).
@end defvr

@defvr Image drag_temp
A temporary breakpoint (being dragged).
@end defvr

@defvr Image enable
@samp{Enable} button.
@end defvr

@defvr Image find_forward
@samp{Find>> ()} button.
@end defvr

@defvr Image find_backward
@samp{Find<< ()} button.
@end defvr

@defvr Image grey_arrow
The execution pointer (not in lowest frame).
@end defvr

@defvr Image grey_cond
A conditional breakpoint (disabled).
@end defvr

@defvr Image grey_stop
A breakpoint (disabled).
@end defvr

@defvr Image grey_temp
A temporary breakpoint (disabled).
@end defvr

@defvr Image hide
@samp{Hide ()} button.
@end defvr

@defvr Image lookup
@samp{Lookup ()} button.
@end defvr

@defvr Image maketemp
@samp{Make Temporary} button.
@end defvr

@defvr Image new_break
@samp{New Breakpoint} button.
@end defvr

@defvr Image new_display
@samp{New Display} button.
@end defvr

@defvr Image new_watch
@samp{New Watchpoint} button.
@end defvr

@defvr Image plain_arrow
The execution pointer.
@end defvr

@defvr Image plain_cond
A conditional breakpoint (enabled).
@end defvr

@defvr Image plain_stop
A breakpoint (enabled).
@end defvr

@defvr Image plain_temp
A temporary breakpoint (enabled).
@end defvr

@defvr Image print
@samp{Print ()} button.
@end defvr

@defvr Image properties
@samp{Properties} button.
@end defvr

@defvr Image rotate
@samp{Rotate ()} button.
@end defvr

@defvr Image set
@samp{Set ()} button.
@end defvr

@defvr Image show
@samp{Show ()} button.
@end defvr

@defvr Image signal_arrow
The execution pointer (stopped by signal).
@end defvr

@defvr Image undisplay
@samp{Undisplay ()} button.
@end defvr

@defvr Image unwatch
@samp{Unwatch ()} button.
@end defvr

@defvr Image watch
@samp{Watch ()} button.
@end defvr



@node Bugs
@appendix Bugs and How To Report Them

Sometimes you will encounter a bug in @DDD{}.  Although we cannot
promise we can or will fix the bug, and we might not even agree that it
is a bug, we want to hear about bugs you encounter in case we do want to
fix them.

To make it possible for us to fix a bug, you must report it.  In order
to do so effectively, you must know when and how to do it.

@menu
* Where to Send Bug Reports::   Our e-mail address.
* Is it a @DDD{} Bug?::         @DDD{} may not be at fault.
* How to Report Bugs::          Report all the facts.
* Bug Reports::                 Include all configuration information.
* Diagnostics::                 Maintaining @DDD{}
@end menu

@node Where to Send Bug Reports
@section Where to Send Bug Reports

Send bug reports for @DDD{} via electronic mail to

@example
@email{bug-ddd@@gnu.org}
@end example


@node Is it a @DDD{} Bug?
@section Is it a @value{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 M*tif installations, for instance, or
bugs in the X server or M*tif itself.  Running @DDD{} as

@example
$ @kbd{@value{ddd} --check-configuration}
@end example

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

@example
$ @kbd{@value{ddd} --trace}
@end example

This shows the interaction between @DDD{} and the inferior debugger
on standard error while @DDD{} is running.  (If @option{--trace} is
not given, this interaction is logged in the file
@file{~/.@value{ddd}/log}; @pxref{Logging}) Compare the debugger output
to the output of @DDD{} and determine which one is wrong.


@node How to Report Bugs
@section How to Report Bugs


Here are some guidelines for bug reports:

@itemize @bullet
@item
The fundamental principle of reporting bugs usefully is this:
@strong{report all the facts}.  If you are not sure whether to state a
fact or leave it out, state it!

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

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

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

@item
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.
@end itemize


@node Bug Reports
@section What to Include in a Bug Report

To enable us to fix a @DDD{} bug, you @emph{must} include the
following information:

@itemize @bullet
@item
Your @DDD{} configuration.  Invoke @DDD{} as

@example
$ @kbd{@value{ddd} --configuration}
@end example

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.

@item
The debugger you are using and its version (e.g., @samp{gdb-4.17} or
@samp{dbx as shipped with Solaris 2.6}).

@item
The compiler you used to compile @DDD{} and its version (e.g.,
@samp{gcc-2.8.1}).

@item
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``.

@item
A @emph{log file} showing the interaction between @DDD{} and the
inferior debugger.  By default, this interaction is logged in the file
@file{~/.@value{ddd}/log}.  Include all trace output from the
@DDD{} invocation up to the first bug occurrence; insert own
comments where necessary.

@item
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, @emph{never} by line number.
@end itemize

Be sure to include this information in @emph{every} single bug report.


@node Diagnostics
@section Getting Diagnostics

@menu
* Logging::                     @DDD{} logs all interactions.
* Debugging @DDD{}::            Facilities to debug @DDD{}.
* Customizing Diagnostics::     All diagnostics resources.
@end menu

@node Logging
@subsection Logging

@cindex Logging
@flindex log
If things go wrong, the first and most important information source is
the @dfn{@DDD{} log file}.  This file, created in
@file{~/.@value{ddd}/log} (@file{~} stands for your home directory),
records the following information:

@itemize @bullet{}
@item
Your @DDD{} configuration (at the top)

@item
All programs invoked by @DDD{}, shown as 
@samp{$ @kbd{@var{program} @var{args}@dots{}}}

@item
All @DDD{} messages, shown as @samp{#  @var{message}}.

@item
All information sent from @DDD{} to the inferior debugger,
shown as @option{-> @var{text}}.

@item
All information sent from the inferior debugger standard output to
@DDD{}, shown as @samp{<- @var{text}}.

@item
All information sent from the inferior debugger standard error to
@DDD{}, shown as @samp{<= @var{text}}.@footnote{Since the inferior
debugger is invoked through a virtual @TTY{}, standard error is
normally redirected to standard output, so @DDD{} never receives
standard error from the inferior debugger.}

@item
All information sent from @DDD{} to Gnuplot,
shown as @samp{>> @var{text}}.

@item
All information sent from Gnuplot standard output to
@DDD{}, shown as @samp{<< @var{text}}.

@item
All information sent from Gnuplot standard error to
@DDD{}, shown as @samp{<= @var{text}}.

@item
If @DDD{} crashes, a @GDB{} backtrace of the @DDD{} core dump
is included at the end.
@end itemize

This information, all in one place, should give you (and anyone
maintaining @DDD{}) a first insight of what's going wrong.


@menu
* Disabling Logging::           
@end menu

@node Disabling Logging
@subsubsection Disabling Logging

@cindex Logging, disabling
The log files created by @DDD{} can become quite large, so you
might want to turn off logging.  There is no explicit @DDD{}
feature that allows you to do that.  However, you can easily create a
@emph{symbolic link} from @file{~/.@value{ddd}/log} to @samp{/dev/null},
such that logging information is lost.  Enter the following commands at
the shell prompt:

@example
$ @kbd{cd}
$ @kbd{rm .@value{ddd}/log}
$ @kbd{ln -s /dev/null .@value{ddd}/log}
$ _
@end example

Be aware, though, that having logging turned off makes diagnostics much
more difficult; in case of trouble, it may be hard to reproduce the
error.



@node Debugging @DDD{}
@subsection Debugging @value{DDD}

@cindex Debugging @DDD{}
As long as @DDD{} is compiled with @option{-g} (@pxref{Compiling for
Debugging}), you can invoke a debugger on @DDD{}---even @DDD{}
itself, if you wish.  From within @DDD{}, a special
@samp{Maintenance} menu is provided that invokes @GDB{} on the running
@DDD{} process.  @xref{Maintenance Menu}, for details.

@flindex .gdbinit
The @DDD{} distribution comes with a @file{.gdbinit} file that is
suitable for debugging @DDD{}.  Among others, this defines a
@samp{ddd} command that sets up an environment for debugging @DDD{}
and a @samp{string} command that lets you print the contents of
@DDD{} @samp{string} variables; just use @samp{print @var{var}}
followed by @samp{string}.

@cindex SIGUSR1 signal
You can cause @DDD{} to dump core at any time by sending it a
@code{SIGUSR1} signal.  @DDD{} resumes execution while you can examine
the core file with @GDB{}.

@enindex DDD_NO_SIGNAL_HANDLERS
When debugging @DDD{}, it can be useful to make @DDD{} not
catch fatal errors.  This can be achieved by setting the environment
variable @env{DDD_NO_SIGNAL_HANDLERS} before invoking
@DDD{}.



@node Customizing Diagnostics
@subsection Customizing Diagnostics

You can use these additional resources to obtain diagnostics about
@DDD{}.  Most of them are tied to a particular invocation option.

@defvr Resource 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.
@end defvr

@defvr Resource checkConfiguration (class CheckConfiguration)
If @samp{on}, check the @DDD{} environment (in particular, the
X configuration), report any possible problem causes and exit.
@xref{Options}, for the @option{--check-configuration} option.
@end defvr

@defvr Resource dddinitVersion (class Version)
The version of the @DDD{} executable that last wrote the
@file{~/.@value{ddd}/init} file.  If this string does not match the
version of the current @DDD{} executable, @DDD{} issues
a warning.
@end defvr

@defvr Resource debugCoreDumps (class DebugCoreDumps)
If @samp{on}, @DDD{} invokes a debugger on itself when receiving a
fatal signal.  @xref{Maintenance Menu}, for setting this resource.
@end defvr

@defvr Resource dumpCore (class DumpCore)
If @samp{on} (default), @DDD{} dumps core when receiving a
fatal signal.  @xref{Maintenance Menu}, for setting this resource.
@end defvr

@defvr Resource maintenance (class Maintenance)
If @samp{on}, enables the top-level @samp{Maintenance} menu
(@pxref{Maintenance Menu}) with additional options.  @xref{Options}, for
the @option{--maintenance} option.
@end defvr

@defvr Resource showConfiguration (class ShowConfiguration)
If @samp{on}, show the @DDD{} configuration on standard output and
exit.  @xref{Options}, for the @option{--configuration} option.
@end defvr

@defvr Resource showFonts (class ShowFonts)
If @samp{on}, show the @DDD{} font definitions on standard output
and exit.  @xref{Options}, for the @option{--fonts} option.
@end defvr

@defvr Resource showInvocation (class ShowInvocation)
If @samp{on}, show the @DDD{} invocation options on standard
output and exit.  @xref{Options}, for the @option{--help} option.
@end defvr

@defvr Resource showLicense (class ShowLicense)
If @samp{on}, show the @DDD{} license on standard output and
exit.  @xref{Options}, for the @option{--license} option.
@end defvr

@defvr Resource showManual (class ShowManual)
If @samp{on}, 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 (@command{$PAGER}, @command{less} or @command{more}).
@xref{Options}, for the @option{--manual} option.
@enindex PAGER
@pindex less
@pindex more
@end defvr

@defvr Resource showNews (class ShowNews)
If @samp{on}, show the @DDD{} news on standard output and
exit.  @xref{Options}, for the @option{--news} option.
@end defvr

@defvr Resource showVersion (class ShowVersion)
If @samp{on}, show the @DDD{} version on standard output and
exit.  @xref{Options}, for the @option{--version} option.
@end defvr

@defvr Resource suppressWarnings (class SuppressWarnings)
If @samp{on}, X warnings are suppressed.  This is sometimes useful for
executables that were built on a machine with a different X or M*tif
configuration.  By default, this is @samp{off}.  @xref{X Warnings}, for
details.
@end defvr

@defvr Resource trace (class Trace)
If @samp{on}, show the dialog between @DDD{} and the inferior debugger
on standard output.  Default is @samp{off}.  @xref{Options}, for the
@option{--trace} option.
@end defvr


@node Configuration Notes
@appendix Configuration Notes

@menu
* GDB::                         Using @DDD{} with @GDB{}
* Bash::                        Using @DDD{} with Bash
* DBX::                         Using @DDD{} with @DBX{}
* Ladebug::                     Using @DDD{} with Ladebug
* JDB::                         Using @DDD{} with @JDB{}
* Make::                        Using @DDD{} with GNU Make
* Perl::                        Using @DDD{} with Perl
* Python::                      Using @DDD{} with Python
* XDB::                         Using @DDD{} with @XDB{}
* LessTif::                     Using @DDD{} with LessTif
@end menu

@node GDB
@section Using @value{DDD} with GDB

Some @GDB{} settings are essential for @DDD{} to work correctly.
These settings with their correct values are:
@example
set height 0
set width 0
set verbose off
set annotate 1
set prompt (gdb) 
@end example

@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 @samp{display /x $pc} command to ensure the
program counter value is updated correctly at each stop.  You may also
enter the command in @file{~/.gdbinit} or (better yet) upgrade to the
most recent @GDB{} version.

@ifinfo
Further information is available on the following @GDB{} variants:
@end ifinfo

@menu
* WDB::                         Using @value{DDD} with WDB
* WindRiver GDB::               Using @value{DDD} with WindRiver GDB (Tornado)
@end menu

@node WDB
@subsection Using @value{DDD} with WDB
@cindex WDB
@cindex WildeBeest

HP's WildeBeest (@WDB{}) is essentially a variant of @GDB{}.  To start
@DDD{} with @WDB{} as inferior debugger, use

@cindex @acronym{WDB}, invoking @DDD{} with
@example
@value{ddd} --wdb @var{program}
@end example

@xref{GDB}, for further configuration notes.


@node WindRiver GDB
@subsection Using @value{DDD} with WindRiver GDB (Tornado)
@cindex WindRiver GDB
@cindex Tornado

@DDD{} now supports WindRiver's version of @GDB{}.@footnote{This section
was contributed by Gary Cliff from Computing Devices Canada
Ltd., @email{gary.cliff@@cdott.com}.}
@DDD{} can be integrated into the @samp{Launch} window by placing the
@file{launch.tcl} script (see below) into the the directory
@file{~/.wind}.

Currently, @DDD{} only supports the PowerPC and has been only tested on
a Solaris 2.6 host.

@DDD{} launches the version of @GDB{} that is either in the current
path, or the one specified on the command line using the
@samp{--debugger} command.

Normally, the Tornado environment is set up by sourcing a script file
which, among other things, sets up the PATH variable.

It is suggested that a soft link for the version of @GDB{} used for the
target (i.e. @file{gdbppc}) be made in the same directory:

@example
bin>@kbd{ls -l gdb*}
39 Mar  6 16:14 gdb -> /usr/wind/host/sun4-solaris2/bin/gdbppc*
1619212 Mar 11  1997 gdbppc*
bin>_
@end example

This way @DDD{} will start the correct version of @GDB{} automatically.

It is also suggested that you use @DDD{}'s execution window to
facilitate parsing of @GDB{} output.  @xref{Debugger Communication}, for
details.

Tornado reads the default TCL scripts first, then the ones in the users
@file{.wind} directory.  The following procedures can be cut and pasted into
the user's @file{launch.tcl} file:

@noindent
@smallexample
@cartouche
# Launch.tcl - Launch application Tcl user customization file.
#

######
#
# setupDDD - sets up DDD for use by the launcher
#
# This routine adds the DDD to the application bar
#
# SYNOPSIS:
# setupDDD
#
# PARAMETERS: N/A
#
# RETURNS: N/A
#
# ERRORS: N/A
#

proc setupDDD @{@} @{
    # Add to the default application bar
    objectCreate app ddd DDD @{launchDDD@}
@}
@end cartouche

@cartouche
######
#
# launchDDD - launch the DDD debugger
#
# SYNOPSIS:
# launchDDD
#
# PARAMETERS: N/A
#
# RETURNS: N/A
#
# ERRORS: N/A
#

proc launchDDD @{@} @{

    global tgtsvr_selected
    global tgtsvr_cpuid

    if @{$tgtsvr_selected == "" || $tgtsvr_cpuid == 0@} @{
        noticePost error "Select an attached target first."
        return
    @}

    set startFileName /tmp/dddstartup.[pid]

    if [catch @{open $startFileName w@} file] @{
         # couldn't create a startup file.  Oh, well.
         exec ddd --gdb &
    @} 
    else 
    @{
         # write out a little /tmp file that attaches to the 
         # selected target server and then deletes itself.
         puts $file "set wtx-tool-name ddd"
         puts $file "target wtx $tgtsvr_selected"
         puts $file "tcl exec rm $startFileName"
         close $file
         exec ddd --gdb --command=$startFileName &
    @}
@}
@end cartouche

@cartouche
######
#
# Launch.tcl - Initialization
#
# The user's resource file sourced from the initial Launch.tcl
#

# Add DDD to the laucher
  setupDDD
@end cartouche
@end smallexample

In order for @DDD{} to automatically display the source of a previously
loaded file, the entry point must be named either @samp{vxworks_main} or
@samp{main_vxworks}.

@xref{GDB}, for further configuration notes.


@node Bash
@section Using @value{DDD} with Bash

@BASH{} support is rather new. As a programming language, @BASH{} is
not feature rich: there are no record structures or hash tables (yet),
no pointers, package variable scoping or methods. So much of the data
display and visualization features of @value{DDD} are disabled.

As with any scripting or interpreted language like Perl, stepping
a machine-language instructions (commands Stepi/Nexti) doesn't exist. 

Some @BASH{} settings are essential for @DDD{} to work correctly.
These settings with their correct values are:

@example
set annotate 1
set prompt set prompt bashdb$_Dbg_less$_Dbg_greater$_Dbg_space
@end example

@DDD{} sets these values automatically when invoking @BASH{}; if these
values are changed, there may be some malfunctions.

Pay special attention when the prompt has extra angle brackets (a
nested shell) or has any parenthesis (is in a subshell). Quitting may
merely exit out of one of these nested (sub)shells rather than leave
the program.

@node DBX
@section Using @value{DDD} with DBX

When used for debugging Pascal-like programs, @DDD{} does not
infer correct array subscripts and always starts to count with 1.

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 @DBX{}
@samp{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.

@node Ladebug
@section Using @value{DDD} with Ladebug

All @DBX{} limitations (@pxref{DBX}) apply to Ladebug as well.


@node JDB
@section Using @value{DDD} with JDB

There is no automatic data display in @JDB{}.  As a workaround,
@DDD{} uses the @samp{dump} 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.

In @JDB{} 1.1, the @samp{dump} and @samp{print} commands do not support
expression evaluation.  Hence, you cannot display arbitrary expressions.

Parsing of @JDB{} output is quite CPU-intensive, due to the
recognition of asynchronous prompts (any thread may output anything at
any time, including prompts).  Hence, a program producing much console
output is likely to slow down @DDD{} considerably.  In such a
case, have the program run with @option{-debug} in a separate window and
attach @JDB{} to it using the @option{-passwd} option.

@node Make
@section Using @value{DDD} with GNU Make

GNU Make support is rather new. As a programming language, GNU Make is
a bit of a stretch for @value{DDD}. There are no record structures or
hash tables, no pointers. Well, actually this does exist, but the
records, pointers and hash tables are fixed into the system.  There
are Makefile variables, ``targets'' (which sometimes refer to files),
dependencies, and commands. There is sort of an ``scope'' that for
variables too.

But much of the data display and visualization features of @value{DDD}
are disabled. However @code{info locals} does work and you can hover
over a variable and see its value.

As with any scripting or interpreted language like Perl, stepping
a machine-language instructions (commands Stepi/Nexti) doesn't exist. 

Pay special attention when the prompt has extra angle
brackets---nested invocation of GNU MAKE. Quitting may merely exit out
of one of these nested invocations rather than leave the program.

@node Perl
@section Using @value{DDD} with Perl

There is no automatic data display in Perl.  As a workaround,
@DDD{} uses the @samp{x} 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.


@node Python
@section Using @value{DDD} with Python

In short, make sure you use a newer version of @PYDB{}, one from
@uref{http://bashdb.sourceforge.net/pydb}. Older versions that had
been supplied with @DDD{} will no longer work.

History: Up to around 1999 there was parallel development that went on
between @DDD{}'s Python debugger @PYDB{} and the stock python debugger
@code{pdb}. These were not necessarily @emph{competing} efforts, just
parallel. In fact the same person worked a little bit on both.

One feature that @PYDB{} supported that wasn't in @code{pdb} was @GDB{}'s
@code{display} command.

After 1999, maintaining @PYDB{} more or less fell into disuse and @code{pdb}
sort of inched ahead with bug fixes and redisigned interaces. Around
the beginning of 2006, new work was started to enhance pdb and to make
it more like @GDB{}. Since @DDD{} already understands a large set of
@GDB{} commands, many of these enhancements were immediately
realizable by @DDD{}. These things include command completion,
restarting the debugger, and using set/show/info commands.

With the blessing of the original author of @PYDB{}, the new effort
took over the name of the old one, Although it did not actually start
out from the @PYDB{} base but from pdb adding the old @PYDB{}
features.

@node XDB
@section Using @value{DDD} with XDB

There is no automatic data display in @XDB{}.  As a workaround,
@DDD{} uses the @samp{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.

@node LessTif
@section Using @value{DDD} with LessTif

@DDD{} includes a number of hacks that make @DDD{} run with
@emph{LessTif,} a free M*tif library without loss of functionality.
Since a @DDD{} binary may be dynamically bound and used with either an
OSF/Motif or LessTif library, these @emph{lesstif hacks} can be enabled
and disabled at run time.

Whether the @emph{lesstif hacks} are included at run-time depends on the
setting of the @samp{lessTifVersion} resource:

@defvr Resource lessTifVersion (class LessTifVersion)
Indicates the LessTif version @DDD{} is running against.  For
LessTif version @var{x.y}, the value is @var{x} multiplied by 1000 plus
@var{y}---for instance, the value @code{79} stands for LessTif 0.79 and
the value @code{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 @samp{LessTifVersion} macro in @file{<Xm/Xm.h>}.  If
@DDD{} was compiled against OSF/Motif, the default value is
@code{1000}, disabling all LessTif-specific hacks.
@end defvr

To set the @samp{lessTifVersion} resource at @DDD{} invocation and
to specify the version number of the LessTif library, you can also use
the option @option{--lesstif-version} @var{version}.

The default value of the @samp{lessTifVersion} resource is derived from
the LessTif library @DDD{} was compiled against (or @code{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:
@itemize @bullet{}
@item
Your @DDD{} binary was compiled against OSF/Motif, but you use
a LessTif 0.88 dynamic library instead.  Invoke @DDD{} with
@option{--lesstif-version 88}.
@item
Your @DDD{} binary was compiled against LessTif, but you use
a OSF/Motif dynamic library instead.    Invoke @DDD{} with
@option{--lesstif-version 1000}.
@item
Your @DDD{} binary was compiled against LessTif 0.85, and you
have upgraded to LessTif 0.90.  Invoke @DDD{} with
@option{--lesstif-version 90}.
@end itemize

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

In the @DDD{} source, LessTif-specific hacks are controlled by
the string @samp{lesstif_version}.



@node Dirty Tricks
@appendix Dirty Tricks

Do you miss anything in this manual?  Do you have any material that
should be added?  Please send any contributions to @email{ddd@@gnu.org}.

   


@node Extending
@appendix Extending @value{DDD}

If you have any contributions to be incorporated into @DDD{},
please send them to @email{ddd@@gnu.org}.  For suggestions on what might
be done, see the file @samp{TODO} in the @DDD{} distribution.



@node FAQ
@appendix Frequently Answered Questions

See @uref{http://www.gnu.org/software/ddd/, the @DDD{} @WWW{} page} for
frequently answered questions not covered in this manual.


@node License
@appendix GNU General Public License

@cindex License
@include gpl.texinfo


@node Help and Assistance
@appendix Help and Assistance

@cindex Mailing list
@cindex Help
@cindex Assistance
We have set up a @emph{mailing list} for general @DDD{}
discussions.  If you need help and assistance for solving a @DDD{}
problem, you find the right people here.

Send message to all receivers of the mailing list to:

@example
@email{ddd@@gnu.org}
@end example

This mailing list is also the place where new @DDD{} releases are
announced.  If you want to subscribe the list, or get more information,
send a mail to

@example
@email{ddd-request@@gnu.org}
@end example

See also @uref{http://www.gnu.org/software/ddd/, the @DDD{} @WWW{}
page} for recent announcements and other news related to @DDD{}.



@node Documentation License
@appendix GNU Free Documentation License

@cindex License, Documentation
@include gfdl.texinfo


@node Label Index
@unnumbered Label Index

@printindex lb


@node Key Index
@unnumbered Key Index

@printindex ky


@node Command Index
@unnumbered Command Index

@printindex cm


@node Resource Index
@unnumbered Resource Index

@printindex vr


@node File Index
@unnumbered File Index

@printindex fl


@node Concept Index
@unnumbered Concept Index
@printindex cp

@bye
