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

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

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

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

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

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

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

Editing all Breakpoints
-----------------------

   To view and edit all breakpoints at once, select `Source =>
Breakpoints'.  This will popup the "Breakpoint Editor" which displays
the state of all breakpoints.

   In the breakpoint editor, you can select individual breakpoints by
clicking on them.  Pressing <Ctrl> while clicking toggles the
selection.  To edit the properties of all selected breakpoints, click on
`Props'.

Hardware-Assisted Breakpoints
-----------------------------

   Using GDB, a few more commands related to breakpoints can be invoked
through the debugger console:

`hbreak POSITION'
     Sets a hardware-assisted breakpoint at POSITION.  This command
     requires hardware support and some target hardware may not have
     this support.  The main purpose of this is EPROM/ROM code
     debugging, so you can set a breakpoint at an instruction without
     changing the instruction.

`thbreak POS'
     Set a temporary hardware-assisted breakpoint at POS.

   See Setting breakpoints (gdb), for details.

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
"setting a watchpoint on a variable".(1)

   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.

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

   (1) Watchpoints are available in GDB and some DBX variants only.  In
XDB, a similar feature is available via XDB "assertions"; see the XDB
documentation for details.

Setting Watchpoints
-------------------

   If the variable name is visible, click with _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
`Watch' button to set a watchpoint there.

   Using GDB and JDB 1.2, you can set different types of watchpoints.
Click and hold _mouse button 1_ on the `Watch' button to get a menu.

Editing Watchpoint Properties
-----------------------------

   To change the properties of a watchpoint, enter the name of the
watched variable in the argument field.  Click and hold _mouse button
1_ on the `Watch' button and select `Watchpoint Properties'.

   The Watchpoint Properties panel has the same functionality as the
Breakpoint Properties panel (see Editing Breakpoint Properties).  As
an additional feature, you can click on `Print' to see the current
value of a watched variable.

Editing all Watchpoints
-----------------------

   To view and edit all watchpoints at once, select `Data =>
Watchpoints'.  This will popup the "Watchpoint Editor" which displays
the state of all watchpoints.

   The Watchpoint Editor has the same functionality as the Breakpoint
Editor (see Editing all Breakpoints).  As an additional feature, you
can click on `Print' to see the current value of a watched variable.

Deleting Watchpoints
--------------------

   To delete a watchpoint, enter the name of the watched variable in the
argument field and click the `Unwatch' button.

Interrupting
============

   If the program is already running (see Running), you can
interrupt it any time by clicking the `Interrupt' button or typing <ESC>
in a DDD window.(1)  Using GDB, this is equivalent to sending a
`SIGINT' (Interrupt) signal.

   `Interrupt' and <ESC> also interrupt a running debugger command,
such as printing data.

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

   (1) If <Ctrl+C> is not bound to `Copy' (see Customizing the Edit Menu),
you can also use <Ctrl+C> to interrupt the running program.

Stopping X Programs
===================

   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.

   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 `Edit => Preferences => General => Continue Automatically
when Mouse Pointer is Frozen'.

Customizing Grab Checking
-------------------------

   The grab checks are controlled by the following resources:

 - Resource: checkGrabs (class CheckGrabs)
     If this is `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.

 - 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 `5000', or 5 seconds.

 - Resource: grabAction (class grabAction)
     The action to take after having detected a grabbed mouse pointer.
     This is a list of newline-separated commands.  Default is `cont',
     meaning to continue the debuggee.  Other possible choices include
     `kill' (killing the debuggee) or `quit' (exiting DDD).

 - 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 `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 `10000', or 10 seconds.

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

Starting Program Execution
==========================

   To start execution of the debugged program, select `Program => 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 `Run' button to
start execution with the selected arguments.

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

   When you click on `Run', your program begins to execute immediately.
See 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.  See 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.

Your Program's Arguments
------------------------

   The arguments to your program are specified by the arguments of the
`run' command, as composed in `Program => Run'.

   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 `SHELL' environment variable (if it exists) specifies what shell
GDB uses.  If you do not define `SHELL', GDB uses `/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.

Your Program's Environment
--------------------------

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

   In GDB, you can use the commands `set environment' and `unset
environment' to change parts of the environment that affect your
program.  See Your program's environment (gdb),
for details.

   The following environment variables are set by DDD:

`DDD'
     Set to a string indicating the DDD version.  By testing whether
     `DDD' is set, a debuggee (or inferior debugger) can determine
     whether it was invoked by DDD.

`TERM'
     Set to `dumb', the DDD terminal type.  This is set for the
     inferior debugger only.(1)

`TERMCAP'
     Set to `' (none), the DDD terminal capabilities.

`PAGER'
     Set to `cat', the preferred DDD pager.

   The inferior debugger, in turn, might also set or unset some
environment variables.

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

   (1) If the debuggee runs in a separate execution window, the
debuggee's `TERM' value is set according to the `termType' resource;
see Customizing the Execution Window, for details.

Your Program's Working Directory
--------------------------------

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

   You can change the working directory of the inferior debugger via
`File => Change Directory' or via the `cd' command of the inferior
debugger.

Your Program's Input and Output
-------------------------------

   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 "shell redirections" with the arguments--that is,
additional arguments like `< INPUT' or `> OUTPUT'.  You can enter these
shell redirections just like other arguments (see Arguments).

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

   Program output that confuses DDD includes:

   * Primary debugger prompts (e.g. `(gdb) ', `(dbx) ' or `(ladebug) ')

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

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

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

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

   If your program outputs any of these strings, you 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 (see Using the Execution Window).

   If the inferior debugger changes the default TTY settings, for
instance through a `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:

 - Resource: lineBufferedConsole (class LineBuffered)
     If this is `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 `off', all lines are
     output as a whole.  This is faster, but results in a random
     position of the last line.

Using the Execution Window
==========================

   By default, input and output of your program go to the debugger
console.  As an alternative, DDD can also invoke an "execution window",
where the program terminal input and output is shown.(1)

   To activate the execution window, select `Program => 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.  See Debugger Communication, for details
on the `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 `/dev/tty' still refers to the
debugger console, _not_ the execution window.

   You can override the DDD stream redirection by giving alternate
redirection operations as arguments.  For instance, to have your program
read from FILE, but to write to the execution window, invoke your
program with `< FILE' as argument.  Likewise, to redirect the standard
error output to the debugger console, use `2> /dev/tty' (assuming the
inferior debugger and/or your UNIX shell support standard error
redirection).

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

   (1) The execution window is not available in JDB.

Customizing the Execution Window
--------------------------------

   You can customize the DDD execution window and use a different TTY
command.  The command is set by `Edit => Preferences => Helpers =>
Execution Window':

 - 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 `@FONT@' is replaced by the name of the fixed
     width font used by DDD.  A simple value is

          Ddd*termCommand: xterm -fn @FONT@ -e /bin/sh -c

   You can also set the terminal type:

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

   Whether the execution window is active or not, as set by `Program =>
Run in Execution Window', is saved using this resource:

 - Resource: separateExecWindow (class Separate)
     If `on', the debugged program is executed in a separate execution
     window.  If `off' (default), the debugged program is executed in
     the console window.

Attaching to a Running Process
==============================

   If the debugged program is already running in some process, you can
"attach" to this process (instead of starting a new one with `Run').(1)

   To attach DDD to a process, select `File => Attach to Process'.  You
can now choose from a list of processes.  Then, press the `Attach'
button to attach to the specified process.

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

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

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

   You can customize the list of processes shown by defining an
alternate command to list processes.  See `Edit => Preferences =>
Helpers => List Processes'; see Customizing Attaching to Processes,
for details.

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

   (1) JDB, PYDB, Perl, and Bash do not support attaching the debugger
to running processes.

Customizing Attaching to Processes
----------------------------------

   When attaching to a process (see Attaching to a Process), DDD
uses a `ps' command to get the list of processes.  This command is
defined by the `psCommand' resource.

 - Resource: psCommand (class PsCommand)
     The command to get a list of processes.  Usually `ps'.  Depending
     on your system, useful alternate values include `ps -ef' and `ps
     ux'.  The first line of the output must either contain a `PID'
     title, or each line must begin with a process ID.

     Note that the output of this command is filtered by DDD; a process
     is only shown if it can be attached to.  The DDD process itself as
     well as the process of the inferior debugger are suppressed, too.

Program Stops
=============

   After the program has been started, it runs until one of the
following happens:

   * A breakpoint is reached (see Breakpoints).

   * A watched value changes (see Watchpoints).

   * The program is interrupted (see Interrupting).

   * A signal is received (see Signals).

   * Execution completes.

   DDD shows the current program status in the debugger console.  The
current execution position is highlighted by an arrow.

   If `Edit => Preferences => General => 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.

Resuming Execution
==================

Continuing
----------

   To resume execution, at the current execution position, click on the
`Continue' button.  Any breakpoints set at the current execution
position are bypassed.

Stepping one Line
-----------------

   To execute just one source line, click on the `Step' button.  The
program is executed until control reaches a different source line, which
may be in a different function.  Then, the program is stopped and
control returns to DDD.

   _Warning_: If you use the `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 `Stepi' button (see Machine Code Execution).

   In GDB, the `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.  `Step' continues to stop if a
function that has debugging information is called within the line.

   Also, the `Step' in GDB only enters a subroutine if there is line
number information for the subroutine.  Otherwise it acts like the
`Next' button.

Continuing to the Next Line
---------------------------

   To continue to the next line in the current function, click on the
`Next' button.  This is similar to `Step', but any function calls
appearing within the line of code are executed without stopping.

   Execution stops when control reaches a different line of code at the
original stack level that was executing when you clicked on `Next'.

Continuing Until Here
---------------------

   To continue running until a specific location is reached, use the
`Continue Until Here' facility from the line popup menu.  See
Temporary Breakpoints, for a discussion.

Continuing Until a Greater Line is Reached
------------------------------------------

   To continue until a greater line in the current function is reached,
click on the `Until' button.  This is useful to avoid single stepping
through a loop more than once.

   `Until' is like `Next', except that when `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, `until' makes your program continue execution until
it exits the loop.  In contrast, clicking on `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.

   `Until' always stops your program if it attempts to exit the current
stack frame.

   `Until' works by means of single instruction stepping, and hence is
slower than continuing until a breakpoint is reached.

Continuing Until Function Returns
---------------------------------

   To continue running until the current function returns, use the
`Finish' button.  The returned value (if any) is printed.

Continuing at a 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.

   To set the execution position to the current location, use `Set
Execution Position' from the breakpoint popup menu.  This item is also
accessible by pressing and holding the `Break/Clear' button.(1)

   As a quicker alternative, you can also press _mouse button 1_ on the
arrow and drag it to a different location.(2)

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

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

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

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

   (1) JDB, PYDB, Perl, and Bash do not support altering the execution
position.

   (2) When glyphs are disabled (see Customizing Source), dragging
the execution position is not possible.  Set the execution position
explicitly instead.

Examining the Stack
===================

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

   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 "stack frame".  The stack frames are allocated
in a region of memory called the "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 "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.

Stack Frames
------------

   The call stack is divided up into contiguous pieces called "stack
frames", or "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.

   When your program is started, the stack has only one frame, that of
the function `main'.  This is called the "initial" frame or the
"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 "innermost" frame.  This
is the most recently created of all the stack frames that still exist.

   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 "frame pointer register" while
execution is going on in that frame.

   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.

Backtraces
----------

   DDD provides a "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 `Status => Backtrace'.

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

Selecting a Frame
-----------------

   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.(1)

   In the backtrace window, you can _select_ an arbitrary frame to move
from one stack frame to another.  Just click on the desired frame.

   The `Up' button selects the function that called the current
one--that is, it moves one frame up.

   The `Down' button selects the function that was called by the
current one--that is, it moves one frame down.

   You can also directly type the `up' and `down' commands at the
debugger prompt.  Typing <Ctrl+Up> and <Ctrl+Down>, respectively, will
also move you through the stack.

   `Up' and `Down' actions can be undone via `Edit => Undo'.

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

   (1) Perl does not allow changing the current stack frame.

"Undoing" Program Execution
===========================

   If you take a look at the `Edit => 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 _previously recorded states_ of your program.

   After "undoing" an execution command (via `Edit => Undo', or the
`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 _view_ on the
earlier state as recorded by DDD.

   In this so-called "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 `Undo' and `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.

   If you want to collect this information without interrupting your
program--within a loop, for instance--you can place a breakpoint with
an associated `cont' command (see Breakpoint Commands).  When the
breakpoint is hit, DDD will stop, collect the data, and execute the
`cont' command, resuming execution.  Using a later `Undo', you can step
back and look at every single loop iteration.

   To leave historic mode, you can use `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, `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

     graph history NAME

   This returns a list of all previously recorded values of the variable
NAME, using array syntax.  Note that NAME must have been displayed at
earlier program stops in order to record values.

Examining Threads
=================

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

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

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

   Using JDB, additional functionality is available:

   * Select a _thread group_ to switch between viewing all threads and
     the threads of the selected thread group;

   * Click on `Suspend' to suspend execution of the selected threads;

   * Click on `Resume' to resume execution of the selected threads.

   For more information on threads, see the JDB and GDB documentation
(see Debugging programs with multiple threads (gdb)).

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

   (1) Currently, threads are supported in GDB and JDB only.

Handling Signals
================

   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, `SIGINT' is the signal
a program gets when you type an interrupt; `SIGSEGV' is the signal a
program gets from referencing a place in memory far away from all the
areas in use; `SIGALRM' occurs when the alarm clock timer goes off
(which happens only if your program has requested an alarm).

   Some signals, including `SIGALRM', are a normal part of the
functioning of your program.  Others, such as `SIGSEGV', indicate
errors; these signals are _fatal_ (kill your program immediately) if
the program has not specified in advance some other way to handle the
signal.  `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.

   Normally, DDD is set up to ignore non-erroneous signals like
`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
`Status => Signals'.

   `Status => 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:

`Stop'
     If set, GDB should stop your program when this signal happens.
     This also implies `Print' being set.

`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 `Stop' being unset.

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

   The entry `All Signals' is special.  Changing a setting here affects
_all signals at once_--except those used by the debugger, typically
`SIGTRAP' and `SIGINT'.

   To undo any changes, use `Edit => Undo'.  The `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 `Pass' is in effect
for the signal in question _at that time_.  In other words, after GDB
reports a signal, you can change the `Pass' setting in `Status =>
Signals' to control whether your program sees that signal when you
continue.

   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 `Send' button will
resume execution where your program stopped, but immediately give it the
signal shown.

   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
`Commands => Continue Without Signal'.

   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
`File => Save Session As'.

Killing the Program
===================

   You can kill the process of the debugged program at any time using
the `Kill' button.

   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 `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 `Run', GDB notices that the file has changed, and
reads the symbol table again (while trying to preserve your current
debugger state).

Examining Data
**************

   DDD provides several means to examine data.

   * 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 "value tip")
     shows the variable value.  This is useful for quick examination of
     several simple values.

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

   * If you want to examine complex data structures, you can "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.

   * If you want to examine arrays of numeric values, you can "plot"
     them graphically in a separate plot window.  The plot is updated
     each time the program stops.  This is useful for large numeric
     arrays.

   * Using GDB or DBX, you can also "examine memory contents" in any of
     several formats, independently of your program's data types.

Showing Simple Values using Value Tips
======================================

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

   You can disable value tips via `Edit => Preferences => General =>
Automatic display of variable values as popup tips'.

   You can disable displaying variable values in the status line via
`Edit => Preferences => General => Automatic display of variable values
in the status line'.

   These customizations are tied to the following resources:

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

 - Resource: valueDocs (class Docs)
     Whether the display of variable values in the status line is
     enabled (`on', default) or not (`off').

   You can turn off value tips via `Edit => Preferences => General =>
Automatic Display of Variable Values'.

Printing Simple Values in the Debugger Console
==============================================

   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 _mouse button 1_ on its name.
The variable name is copied to the argument field.  By clicking the
`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 _mouse button 3_ on
the variable name and select the `Print' item from the popup menu.

   In GDB, the `Print' button generates a `print' command, which has
several more options.  See Examining Data (gdb), for
GDB-specific expressions, variables, and output formats.

Displaying Complex Values in the Data Window
============================================

   To explore complex data structures, you can "display" them
permanently in the _data window_.  The data window displays selected
data of your program, showing complex data structures graphically.  It
is updated each time the program stops.

Display Basics
--------------

   This section discusses how to create, manipulate, and delete
displays.  The essentials are:

   * Click on `Display' to display the variable in `()'.

   * Click on a display to select it.

   * Click on `Undisplay' to delete the selected display.

Creating Single Displays
........................

   To create a new display showing a specific variable, select the
variable by clicking _mouse button 1_ on its name.  The variable name is
copied to the argument field.  By clicking the `Display' button, a new
display is created in the data window.  The data window opens
automatically as soon as you create a display.

   As a shorter alternative, you can simply press _mouse button 3_ on
the variable name and select `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 `Display' button.

   Finally, you may also type in a command at the debugger prompt:

     graph display EXPR [clustered] [at (X, Y)]
         [dependent on DISPLAY] [[now or] when in SCOPE]

   This command creates a new display showing the value of the
expression EXPR.  The optional parts have the following meaning:

`clustered'
     If given, the new display is created in a cluster.  See
     Clustering, for a discussion.

`at (X, Y)'
     If given, the new display is created at the position (X, Y).
     Otherwise, a default position is assigned.

`dependent on DISPLAY'
     If given, an edge from the display numbered or named _display_ to
     the new display is created.  Otherwise, no edge is created.  See
     Dependent Values, for details.

`when in SCOPE'
`now or when in SCOPE'
     If `when in' is given, the display creation is "deferred" until
     execution reaches the given SCOPE (a function name, as in the
     backtrace output).

     If `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 `when in' suffix nor `now or when in' suffix is given,
     the display is created immediately.

Selecting Displays
..................

   Each display in the data window has a _title bar_ containing the
_display number_ and the displayed expression (the _display name_).
Below the title, the _display value_ is shown.

   You can select single displays by clicking on them with _mouse
button 1_.

   You can _extend_ an existing selection by pressing the <Shift> key
while selecting.  You can also _toggle_ an existing selection by
pressing the <Shift> key while selecting already selected displays.

   Single displays may also be selected by using the arrow keys <Up>,
<Down>, <Left>, and <Right>.

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

   If the <Shift> key is pressed while selecting, the existing
selection is _extended_.

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