ddd(1)                    User Commands                    ddd(1)



NAME
     ddd, xddd - the data display debugger

SYNOPSIS
     ddd  [--help] [--gdb] [--dbx] [--xdb] [--debugger name]
                                                       ----
          [--host hostname [--login username]] [--rhost hostname
                  --------          --------            --------
          [--login username]] [--vsl-library library] [--vsl-path
                   --------                  -------
          path] [--exec-window] [--no-exec-window]
          ----
          [--attach-windows] [--separate-windows]
          [--scrolled-graph-editor] [--panned-graph-editor]
          [--trace] [--nw] [--tty] [--fullname] [--version]
          [--configuration] [--check-configuration] [--manual]
          [--license] [gdb-options] [x-options] [vsl-options]
                       --- -------   - -------   --- -------
          [program [core | process-id]]
           -------  ----   ------- --

     but usually just

     ddd  program
          -------

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

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

     + Start your program, specifying anything that might  affect
       its behavior.

     + Make your program stop on specified conditions.

     + Examine what has happened, when your program has stopped.

     + Change things in your program, so you can experiment  with
       correcting the effects of one bug and go on to learn about
       another.

     "Classical" UNIX debuggers such as the  GNU  debugger  (GDB)
     provide a command-line interface and a multitude of commands
     for these and other debugging purposes.  DDD  is  a  wrapper
                                                          -------
     around  an  inferior GDB, DBX, or XDB debugger.  In addition
     to the command-line interface of the inferior debugger,  DDD
     provides a common graphical user interface to support debug-
                       --------- ---- ---------
     ging tasks.  The  DDD  graphical  data  display  allows  for
                            ---------  ----  -------
     interactive exploration of data structures.

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



DDD 2.1.1            Last change: 1 Jun 1997                    1






ddd(1)                    User Commands                    ddd(1)



       ddd program

     You can also start with both an  executable  program  and  a
     core file specified:

       ddd program core

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

       ddd program 1234

     would attach DDD to process 1234 (unless  you  also  have  a
     file named `1234'; DDD does check for a core file first).

     By default, DDD uses GDB as inferior debugger.  Use

       ddd --dbx program

     or

       ddd --xdb program

     to run DBX or XDB as inferior debugger.

     To learn more about DDD options, run

       ddd --help

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

THE DDD WINDOWS
     DDD is composed of three main windows:

     + The Data Window shows the current  data  of  the  debugged
           ---- ------
       program.

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

     + The Debugger Console accepts debugger commands  and  shows
           -------- -------
       debugger messages.

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

     Besides these main windows, there are  some  other  optional
     windows

     + The  Command  Tool  offers  buttons  for  frequently  used
            -------  ----



DDD 2.1.1            Last change: 1 Jun 1997                    2






ddd(1)                    User Commands                    ddd(1)



       commands.  It is usually placed on the source window.

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

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

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

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

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

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

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

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

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

     See the following section for details on entering commands.

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



DDD 2.1.1            Last change: 1 Jun 1997                    3






ddd(1)                    User Commands                    ddd(1)



     You can repeat previous and next commands  by  pressing  the
             ------
     `Up'  and  `Down' arrow keys, respectively.  If you enter an
     empty line, the last command is repeated as well.  The `Com-
     mand  History...'  item  in the `Commands...' menu shows the
     command history.

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

     Using GDB, you can also complete commands and  arguments  by
                             --------
     pressing  the  `TAB'  key;  pressing  the `TAB' key multiple
     times shows one possible expansion after the other.

     Here are some of the most frequently  needed  debugger  com-
     mands.

  Common GDB commands
     break [file:]function
            ----  --------
           Set a breakpoint at function (in file).
                               --------     ----

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

     where
          Display the program stack.

     print expr
           ----
           Display the value of an expression.

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

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

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

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

     quit Exit DDD.

     For full details on GDB commands, see Using GDB: A Guide  to
                                           ----- ---  - -----  --
     the  GNU  Source-Level  Debugger, by Richard M. Stallman and
     ---  ---  ------ -----  --------
     Roland H. Pesch. The same text is available  online  as  the
     gdb entry in the info program.



DDD 2.1.1            Last change: 1 Jun 1997                    4






ddd(1)                    User Commands                    ddd(1)



  Common DBX commands
     stop in function
             --------
           Set a breakpoint at function.
                               --------

     stop at line
             ----
           Set a breakpoint at line.
                               ----

     file file
          ----
           Change the current file to file.
                                      ----

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

     where
          Display the program stack.

     print expr
           ----
           Display the value of an expression.

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

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

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

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

     quit Exit DDD.

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

  Common XDB commands
     b [file:]line
        ----  ----
           Set a breakpoint at line line (in file).
                                    ----     ----

     b function
       --------
           Set a breakpoint at function.
                               --------

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

     t    Display the program stack.

     p expr
       ----
           Display the value of an expression.

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



DDD 2.1.1            Last change: 1 Jun 1997                    5






ddd(1)                    User Commands                    ddd(1)



          a breakpoint).

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

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

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

     q    Exit DDD.

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

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

     To open a program to be debugged, select `Open Program' from
     the `File' menu.

     To open a core dump for the program, select `Open Core Dump'
     from the `File' menu.

     To open an arbitrary source file, select `Open Source'  from
     the `File' menu.

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

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

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

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





DDD 2.1.1            Last change: 1 Jun 1997                    6






ddd(1)                    User Commands                    ddd(1)



     As a shorter alternative, you can  simply  press  the  right
                                                            -----
     mouse  button  on  the function name and select the `lookup'
     -----  ------
     item from the source popup menu.

     As another alternative, you can enter the function  name  in
     the  argument  field  and  click on the `Lookup()' button to
     find its definition.

     Finally, you can use the  GDB  `info  line'  command.   Type
     `help info line' at the `(gdb)' prompt for details.

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

     As an alternative, you can enter the item  in  the  argument
     field and click on one of the `Find' buttons.

     By default, DDD finds only complete words.   To  search  for
     arbitrary  substrings,  change  the value of the `Find Words
     Only' option in the `Source Options' menu.

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

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

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

     As an alternative, you can simply press the right mouse but-
                                                 ----- ----- ----
     ton  on  the  source  line number and select the `Set Break-
     ---
     point' item from the line popup menu.

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

     As yet another alternative,  you  can  select  `Edit  Break-
     points...'   in the `Source' menu, click on the `New' button
     and enter the line number.

     And finally, you can also use the GDB `break' command or the
     DBX `stop' command.  Type `help break' at the `(gdb)' prompt



DDD 2.1.1            Last change: 1 Jun 1997                    7






ddd(1)                    User Commands                    ddd(1)



     (or `help stop' at the `(dbx)' prompt) for details.  The XDB
     `b' command works as well.

     (If you find this number of alternatives confusing, be aware
     that DDD users fall into three categories, which must all be
     supported.  Novice users explore DDD and may prefer  to  use
                 ------ -----
     one  single  mouse  button.   Advanced users know how to use
                                   -------- -----
     shortcuts and prefer popup menus.  Experienced users  prefer
                                        ----------- -----
     the command line interface.)

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

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

     As a shorter alternative, you can  simply  press  the  right
                                                            -----
     mouse  button  on  the  function name and select the `break'
     -----  ------
     item from the popup menu.

     As another alternative, you can enter the function  name  in
     the argument field (possibly using name completion by press-
     ing the `TAB' key) and click on the `Break at ()' button.

     As yet another alternative, you can click on `New' from  the
     Breakpoint editor (invoked through `Edit Breakpoints...'  in
     the `Source' menu) and enter the function name.

     Finally, you can use the GDB  `break'  command  or  the  DBX
     `stop' command.  Type `help break' at the `(gdb)' prompt (or
     `help stop' at the `(dbx)' prompt) for details.  The XDB `b'
     command works as well.

  Disabling Breakpoints
     Note: DBX does not support breakpoint disabling.

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

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

     Disabled breakpoints are indicated by a grey stop  sign,  or
     ` n ', where n is the breakpoint number.
      ---         -





DDD 2.1.1            Last change: 1 Jun 1997                    8






ddd(1)                    User Commands                    ddd(1)



     Finally, you can use the GDB `disable' command.  Type  `help
     disable' at the `(gdb)' prompt for details.

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

     Temporary breakpoints are convenient  to  make  the  program
     continue  up  to a specific location: just set the temporary
     breakpoint at this location and continue execution.

     The `Continue Until Here' item from the popup  menu  sets  a
     temporary  breakpoint  on the source line number and immedi-
     ately continues execution.  In GDB, execution stops  when  a
     source line greater than the source line is reached, or when
     the current stack frame is exited.  In DBX and  XDB,  execu-
     tion stops when the temporary breakpoint is reached.

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

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

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

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

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

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

     As an alternative, you can enter `#n' in the argument field,
                                        -
     where n is the breakpoint number and click on the `Lookup()'
           -
     button to find its definition.



DDD 2.1.1            Last change: 1 Jun 1997                    9






ddd(1)                    User Commands                    ddd(1)



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

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

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

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

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

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

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

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

     To run your program again, with the same  arguments,  select
     `Run  Again' from the `Program' menu or press the `Run' but-
     ton below.  You may also enter `run', followed by  arguments
     at the debugger prompt instead.

     By default, input and output of the debugged program  go  to
     the  debugger  console.   As  an  alternative,  DDD can also



DDD 2.1.1            Last change: 1 Jun 1997                   10






ddd(1)                    User Commands                    ddd(1)



     invoke an execution window, where the program terminal input
               --------- ------
     and output is shown.  See the `Run in Execution Window' item
     in the `Options...'  menu for details.

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

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

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

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

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

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

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

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

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

     The `Up' button selects the function that called the current
     one.

     The `Down' button selects the function that  was  called  by
     the current one.

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




DDD 2.1.1            Last change: 1 Jun 1997                   11






ddd(1)                    User Commands                    ddd(1)



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

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

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

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

EXAMINING DATA
     DDD provides three means to examine data.

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

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

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

  Displaying Simple Values
     To display the value of a simple variable,  move  the  mouse



DDD 2.1.1            Last change: 1 Jun 1997                   12






ddd(1)                    User Commands                    ddd(1)



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

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

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

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

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

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

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

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

     Finally, you may also enter

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

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




DDD 2.1.1            Last change: 1 Jun 1997                   13






ddd(1)                    User Commands                    ddd(1)



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

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

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

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

  Selecting Multiple Displays
     Multiple displays are selected by pressing and  holding  the
     left  mouse  button  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 the mouse button is released.

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

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

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

     Selection of multiple display parts is not supported.

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

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

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



DDD 2.1.1            Last change: 1 Jun 1997                   14






ddd(1)                    User Commands                    ddd(1)



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

  Rotating Arrays
     Arrays can be aligned horizontally or vertically.  To change
     the  alignment  of an array, select it and then click on the
     `Rotate()' button.

     As a faster alternative, you can also press the right  mouse
                                                     -----  -----
     button on the array and select the `Rotate' menu item.
     ------

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

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

     As a faster alternative, you can also press the right  mouse
                                                     -----  -----
     button  on  the originating display part and select the `New
     ------
     Display...' menu item.

     Using dependent  displays,  you  can  investigate  the  data
     structure  of  a "tree" for example and lay it out according
     to your intuitive image of the "tree" data structure.

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

  Dereferencing Pointers
     Since so many data structures are realized  using  pointers,
     there  is a shortcut for creating dependent displays showing
     the value of a dereferenced pointer.

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

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

  Displaying Local Variables
     You can display all local  variables  at  once  by  choosing
     `Display  Local  Variables'  from the `Data' menu.  When you



DDD 2.1.1            Last change: 1 Jun 1997                   15






ddd(1)                    User Commands                    ddd(1)



     using DBX or XDB, this displays all local variables, includ-
     ing  the  arguments  of  the current function.  When you are
     using GDB, function arguments are contained  in  a  separate
     display, activated by `Display Arguments'.

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

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

       graph display `command`
                      -------

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

       graph display `where`

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

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

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

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

     To display several successive objects of the  same  type  (a
     section  of  an array, or an array of dynamically determined
     size), use the notation [FROM..TO] in  display  expressions.
                              ----  --
     FROM  and  TO  denote  the  first and last array position to
     ----       --
     display.  Thus,

       graph display argv[0..9]

     creates ten new display nodes for `argv[0]', `argv[1]', ...,
     `argv[9]'.

     Using GDB as  inferior  debugger,  you  can  use  artificial
                                                       ----------
     arrays.  Typing
     ------

       graph display argv[0] @ 10



DDD 2.1.1            Last change: 1 Jun 1997                   16






ddd(1)                    User Commands                    ddd(1)



     creates a single array display node containing `argv[0]'  up
     to `argv[9]'.  Generally, by using the `@' operator, you can
     specify the number of array elements to be displayed.

     For more details on artificial arrays, see the GDB  documen-
     tation.

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

     Note that most inferior debuggers have no support for chang-
     ing entire structures; you must change each primitive struc-
     ture member separately.

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

     When a display is deleted, its immediate ancestors and  des-
     cendants  are automatically selected, so that you can easily
     delete entire graphs.

     To delete several displays at once, select  the  `Delete...'
     item  in  the  Display  Editor  (invoked  through  the `Edit
     Displays...'  item in the `Data' menu).  Select  any  number
     of  display items in the usual way and delete them by press-
     ing `Delete'.

     As an alternative, you can also type

       graph undisplay displays...
                       --------

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

  Disabling or Enabling Displays
     Note: DBX and XDB2+2 do not support display disabling.

     Unlike a deleted  display  item,  a  disabled  display  item
              -------                     --------
     remains  in the display, but its value is not shown until it
     is enabled again.

     Displays are enabled and disabled  the  same  way  they  are
     deleted,   using   the  `Disable()'/`Enable()'  button,  the
     `Disable'/`Enable  Display'  popup   menu   item,   or   the
     `Disable'/`Enable' buttons in the Display Editor.



DDD 2.1.1            Last change: 1 Jun 1997                   17






ddd(1)                    User Commands                    ddd(1)



     As an alternative, you can also type

       graph disable display displays...
                             --------

     and

       graph enable display displays...
                            --------

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


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

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

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

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

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

     Edge hints can be made invisible  by  disabling  `Show  Edge
     Hints' in the `Data Options' menu.

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



DDD 2.1.1            Last change: 1 Jun 1997                   18






ddd(1)                    User Commands                    ddd(1)



     suppressed displays.

     Suppressed displays become visible again as soon as

     + alias detection is disabled,

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

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

     Please note the following caveats with alias detection:
                               -------

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

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

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

  Refreshing the Data Window
     Although the data window refreshes itself automatically each
     time  the program stops, there are some situations where you
     should refresh it explicitly.

     The data window should be refreshed whenever:

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

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

     + you think it could be useful.

     You can refresh the data window by  selecting  the  `Refresh
     Displays' item in the `Data' menu.



DDD 2.1.1            Last change: 1 Jun 1997                   19






ddd(1)                    User Commands                    ddd(1)



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

     Typing

       graph refresh

     at the debugger prompt has the same effect.

GRAPH EDITING
     The DDD data window offers some basic functionality to mani-
     pulate the display graph.

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

     If the data window becomes too small to hold  all  displays,
     scroll  bars  are  created.   If  your  DDD is set up to use
     panners instead, a panner is  created  in  the  lower  right
     -------
     edge.  When the panner is moved around, the window view fol-
     lows the position of the  panner.   See  `CUSTOMIZING  DDD',
     below, for details on how to set up scroll bars or panners.

     For fine-grain movements,  selected  displays  may  also  be
     moved using the arrow keys.  Pressing Shift and an arrow key
     moves displays by single pixels.  Pressing `Ctrl' and  arrow
     keys moves displays by grid positions.

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

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

     You can enforce alignment by selecting `Snap to Grid' in the
     `Data Options' menu.  If `Snap to Grid' is enabled, displays
     can be moved on grid positions only.

  Layouting the Display Graph
     You can layout the entire graph as a tree by selecting `Lay-
     out Graph' from the `Data' menu.

     Layouting the graph may introduce edge hints; that is, edges
                                       ---- -----
     are  no  more  straight  lines, but lead to an edge hint and



DDD 2.1.1            Last change: 1 Jun 1997                   20






ddd(1)                    User Commands                    ddd(1)



     from there to their destination.  You can  make  edge  hints
     invisible  by  disabling  `Show  Edge  Hints'  in  the `Data
     Options' menu.  Edge hints can be moved  around  like  arbi-
     trary displays.

     To enable a more compact layout, you can  set  the  `Compact
     Layout' option in the `Data Options' menu.  This realizes an
     alternate layout algorithm, where successors are placed next
     to  their parents.  This algorithm is suitable for homogene-
     ous data structures only.

     You can enforce layout by  setting  the  `Automatic  Layout'
     option in the `Data Options' menu.  If `Automatic Layout' is
     enabled, the graph is layouted after each change.

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

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

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

     To print the graph  on  a  PostScript  printer,  select  the
     `Print  Graph...'  item  from  the  `File'  menu.  Enter the
     printing command in the `Print Command' field.  Click on the
     `Print' button to start printing.

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

     As an alternative, you may also print the graph in  a  file.
     Click  on  the  `File' button and enter the file name in the
     `File Name' field.  Click on the `Print'  button  to  create
     the file.

     When the graph is printed in a file, two formats are  avail-
     able:

     + PostScript - suitable for enclosing it  in  another  docu-
       ment;

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





DDD 2.1.1            Last change: 1 Jun 1997                   21






ddd(1)                    User Commands                    ddd(1)



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

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

     Sometimes, it is desirable to examine a program not only  at
     the  source  level, but also at the machine level.  DDD pro-
     vides special machine code and  register  windows  for  this
     task.

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

     The machine code window works very much like the source win-
     dow.   You can set, clear, and change breakpoints by select-
     ing the address and pressing a `Break at ()'  or  `Clear  at
     ()'  button;  the  usual  popup  menus  are  also available.
     Breakpoints and the current execution position are displayed
     simultaneously in both source and machine code.

     The `Lookup()' button can be used to  look  up  the  machine
     code  for a specific function-or the function for a specific
     address.  Just click on the location in one window and press
     `Lookup()'  to  see the corresponding code in the other win-
     dow.

     If source code is not available, only the machine code  win-
     dow is updated.

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

     To execute  just  one  machine  instruction,  click  on  the
     `Stepi' button.

     To continue to the next instruction in the current function,
     click  on  the  `Nexti' button.  This is similar to `Stepi',
     but any subroutine calls are executed without stopping.

  Registers
     DDD provides a register window showing the machine  register
                    -------- ------
     values  after  each  program  stop.   To enable the register



DDD 2.1.1            Last change: 1 Jun 1997                   22






ddd(1)                    User Commands                    ddd(1)



     window, select `Registers...' from the `Status' menu.

     By selecting one of the registers, its name is copied to the
     argument  field.   You  can use it as value for `Display()',
     for instance, to have its value displayed in the  data  win-
     dow.

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

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

     + The editor specified in the  `XEDITOR'  environment  vari-
       able;

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

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

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

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

     After the editor  has  exited,  the  source  code  shown  is
     automatically brought up-to-date.

     If you have DDD and an editor running in parallel,  you  can
     also  update  the  source  code  manually  by  selecting the
     `Reload  Source...'  item  from  the  `Source'  menu.   This
     reloads  the source code shown from the source file.  As DDD
     automatically reloads the source code if the  debugged  pro-
     gram has been recompiled, this should seldom be necessary.

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

     An interrupt (Ctrl+C or Interrupt) does not exit  from  DDD,
     but  rather  terminates  the  action of any debugger command
     that is in progress and  returns  to  the  debugger  command
     level.   It  is  safe to type the interrupt character at any



DDD 2.1.1            Last change: 1 Jun 1997                   23






ddd(1)                    User Commands                    ddd(1)



     time because the debugger does not allow it to  take  effect
     until a time when it is safe.

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

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

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

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

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

       ddd --host hostname remote-program
                  -------- ------ -------

     If your remote  username differs from  the  local  username,
                     --------
     use

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

     instead.

     There are a few caveats in remote mode:
                     -------

     + The remote debugger is started in your remote home  direc-
       tory.   Hence,  you must specify an absolute path name for
       remote-program (or a path name  relative  to  your  remote
       ------ -------
       home  directory).   Same  applies  to  remote  core files.
       Also, be sure to specify a remote process id  when  debug-
       ging a running program.

     + The remote debugger is  started  non-interactively.   Some
       DBX  versions  have trouble with this.  If you don't get a
       prompt from the remote debugger, use the `--rhost'  option



DDD 2.1.1            Last change: 1 Jun 1997                   24






ddd(1)                    User Commands                    ddd(1)



       instead of `--host'.  This will invoke the remote debugger
       via an interactive shell on the  remote  host,  which  may
       lead to better results.
       Note: using `--rhost', DDD invokes the  inferior  debugger
       as  soon  as  a shell prompt appears.  The first output on
       the remote host ending in a space character or `>' and not
       followed by a newline is assumed to be a shell prompt.  If
       necessary, adjust your shell prompt on the remote host.

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

     + In remote mode, all sources are  loaded  from  the  remote
       host;  file  dialogs  scan  remote  directories.  This may
       result in somewhat slower operation than normal.

     + To help you find problems due to remote execution, run DDD
       with the `--trace-shell-commands' option.  This prints the
       shell commands issued by DDD on standard error.

ROOT DEBUGGING
     Sometimes, you may  require  to  debug  programs  with  root
     privileges,  but  without actually logging in as root.  This
     is usually done by installing the debugger setuid root, that
                                                ------ ----
     is, having the debugger run with root privileges.  For secu-
     rity reasons, you cannot install DDD as  a  setuid  program.
     Instead,  you  should  invoke DDD such that a setuid copy of
                                                   ------
     the inferior debugger is used.

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

       ddd --debugger rootgdb

     to debug programs with root privileges.

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

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

  General Information
     To have DDD run as an inferior debugger in other front-ends,
     set  up  your  debugger  front-end  such that `ddd --tty' is



DDD 2.1.1            Last change: 1 Jun 1997                   25






ddd(1)                    User Commands                    ddd(1)



     invoked instead of  the  inferior  debugger.   When  DDD  is
     invoked  using the `--tty' option, it enables its TTY inter-
                                                       --- ------
     face, taking  additional  debugger  commands  from  standard
     ----
     input  and  forwarding  debugger  output to standard output,
     just as if the inferior debugger had been invoked  directly.
     All remaining DDD functionality stays unchanged.

     In case your debugger front-end  uses  the  GDB  `-fullname'
     option to have GDB report source code positions, the `--tty'
     option is not  required.   DDD  recognizes  the  `-fullname'
     option,  finds  that  it  has  been  invoked from a debugger
     front-end and automatically enables the TTY interface.

     You may also invoke `ddd --tty' directly, entering DDD  com-
     mands  from  your TTY, or use DDD as the end of a pipe, con-
     trolled by a remote program.  Be aware,  however,  that  the
     TTY interface does not support line editing and command com-
     pletion and that DDD exits as soon as it receives a  EOF  on
     its standard input.  Also, do not try to run DDD with DDD as
     inferior debugger.

     The `--tty' option automatically disables the debugger  con-
     sole,  as  its facilities are supposed to be provided by the
     integrating  front-end.   If  the  front-end  also  provides
     source  and/or  data  facilities,  you  may be interested in
     disabling the DDD source window or the DDD data window, too.
     Use  the `--no-source-window' and `--no-data-window' options
     for this purpose.

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

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

       (setq gdb-command-name "ddd")

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

  Using DDD with XXGDB
     Invoke xxgdb as

      xxgdb -db name ddd -db prompt '(gdb) '
               -            -






DDD 2.1.1            Last change: 1 Jun 1997                   26






ddd(1)                    User Commands                    ddd(1)



PREFERENCES
     You can set up your personal DDD preferences  by  using  the
     `Options' menu from the menu bar.  These options affect your
     running DDD process only, unless you save these  preferences
     for a later DDD invocation.

  Frequent Preferences
     If you want to run your debugged process in a separate  ter-
     minal  emulator  window,  set  the `Run in Execution Window'
     option.  This is useful for programs that have special  ter-
     minal  requirements  not provided by the debugger window, as
     raw keyboard processing or terminal control sequences.

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

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

     Through the `Preferences...'  item,  you  can  set  up  more
     preferences, which are dicussed here.

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

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

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

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

     If you want to use TAB key completion in all  text  windows,
     set  the `TAB key completes in all windows' option.  This is



DDD 2.1.1            Last change: 1 Jun 1997                   27






ddd(1)                    User Commands                    ddd(1)



     useful if you have pointer-driven keyboard focus (see below)
     and  no  special  usage for the TAB key.  Otherwise, the TAB
     key completes in the debugger console only.

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

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

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

     If you want to save the command history  for  the  next  DDD
     invocation,  set  the `Save command history on exit' option.
     Note: This option is always set if your GDB  is  set  up  to
     save its command history.

     The `Reset' button restores the most recently saved  prefer-
     ences.

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

     By default, DDD caches source files in memory.  This is con-
     venient  for  remote debugging, since remote file access may
     be slow.  If you want to  reduce  memory  usage,  unset  the
     `Cache source files' option.

     By default, DDD caches machine code in memory.  This is  bad
     for  memory usage, but convenient for speed, since disassem-
     bling a function each time it is reached may take time.   If
     you  want  to  reduce memory usage, unset the `Cache machine
     code' option.

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



DDD 2.1.1            Last change: 1 Jun 1997                   28






ddd(1)                    User Commands                    ddd(1)



     The `Reset' button restores the most recently saved  prefer-
     ences.

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

     Graph layout and alias detection may introduce  edge  hints;
                                                     ----  -----
     that  is,  edges  are no more straight lines, but lead to an
     edge hint and from there to their destination.   These  edge
     hints  can  be selected and moved around like displays.  You
     can make edge hints visible by setting the `Show Edge Hints'
     option.

     To facilitate alignment of data displays, you  can  set  the
     `Auto-align displays' option.  If auto-alignment is enabled,
     displays can be moved on grid positions only.

     To enable a more compact layout, you can  set  the  `Compact
     Layout'  option.   This  realizes  an alternate layout algo-
     rithm, where successors are placed next  to  their  parents.
     This  algorithm  is suitable for homogeneous data structures
     only.

     To enforce layout, you can set the `Re-layout graph automat-
     ically'  option.   If automatic layout is enabled, the graph
     is layouted after each change.

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

     The `Reset' button restores the most recently saved  prefer-
     ences.

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

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

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



DDD 2.1.1            Last change: 1 Jun 1997                   29






ddd(1)                    User Commands                    ddd(1)



     By default, DDD directs keyboard  input  to  the  item  your
     mouse pointer points at.  If you prefer a click-to-type key-
     board focus (that is, click on an item  to  make  it  accept
     keyboard  input),  set the `Keyboard Focus' option on `Click
     to type'.

     By default, DDD uses Motif scroll bars to  scroll  the  data
     window.   Many  people find this inconvenient, since you can
     scroll in the horizontal or vertical direction only.  As  an
     alternative,   DDD   provides  a  panner  (a  kind  of  two-
     dimensional scroll bar).  This is much more comfortable, but
     may  be incompatible with your Motif toolkit.  To set up DDD
     such that it uses panners by default, set the  `Data  Scrol-
     ling'  option  to  `Panner'.   This change takes only effect
     after you have saved options and restarted  DDD.   See  also
     the  `--panned-graph-editor'  and  `--scrolled-graph-editor'
     options, below.

     By default, DDD runs with  GDB  as  inferior  debugger.   To
     change  this  default,  set  the  `Debugger  Type' option to
     another debugger.  This change takes only effect  after  you
     have saved options and restarted DDD.  See also the `--gdb',
     `--dbx', and `--xdb' options, below.

     The `Reset' button restores the most recently saved  prefer-
     ences.

  Saving Options
     You can save the current option settings by selecting  `Save
     Options' in the `Options' menu.  Options are saved in a file
     named `.dddinit' in your home directory.

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

     The inferior debugger can be customized  through  the  `Set-
     tings...' item.  See the `DEBUGGER SETTINGS' section, below.

DEBUGGER SETTINGS
     If you use GDB as inferior debugger, you can change its set-
     tings  using  the  `Settings...' item in the `Options' menu.
     Using the settings editor, you  can  determine  whether  C++
     names  are  to  be demangled, how many array elements are to
     print, and so on.

     The capabilities of the settings editor depend on the  capa-
     bilities  of  your  inferior debugger-that is, your GDB ver-
     sion.  Clicking on  `?'  gives  an  an  explanation  on  the
     specific item; the GDB documentation gives more details.





DDD 2.1.1            Last change: 1 Jun 1997                   30






ddd(1)                    User Commands                    ddd(1)



     Clicking on `Reset' restores the most  recently  saved  set-
     tings.

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

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

USING DDD WITH LESSTIF
     DDD 2.1.1 and later include a number of hacks that make  DDD
     run  with LessTif, a free Motif clone, without loss of func-
               -------
     tionality.  Since a DDD binary may be dynamically bound  and
     used  with  either  an  OSF/Motif  or LessTif library, these
     hacks can be enabled and disabled at run time.  The  default
     setting  depends  on  the  include files used when compiling
     DDD:

     + If DDD was compiled using LessTif 0.99 or  earlier,  these
       hacks  are  enabled  by default.  When using a dynamically
       bound  DDD  binary  with  a  LessTif  1.0  library  or  an
       OSF/Motif  library, you may wish to disable the hacks.  To
       disable them, invoke DDD with `--no-lesstif-hacks' or  set
       the `lessTifHacks' resource to `false'.

     + If DDD was  compiled  using  OSF/Motif  include  files  or
       LessTif  include  files, version 1.0 or later, these hacks
       are disabled by default.  When using a  dynamically  bound
       DDD  binary  with  a LessTif library, version 0.99 or ear-
       lier, you may wish to enable these hacks.  To enable them,
       invoke    DDD    with   `--lesstif-hacks'   or   set   the
       `lessTifHacks' resource to `true'.

     All of these hacks apply to  LessTif  0.79;  future  LessTif
     releases  might need them no more.  In the DDD source, these
     hacks are controlled by the string `lesstif hacks'.
                                                -

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

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

       Ddd*fontList: \
       -*-helvetica-bold-r-*-*-12-*-*-*-*-*-*-*=charset,\
       -*-helvetica-bold-r-*-*-10-*-*-*-*-*-*-*=small,\
       -*-lucidatypewriter-medium-r-*-*-12-*-*-*-*-*-*-*=tt,\
       -*-helvetica-bold-r-*-*-12-*-*-*-*-*-*-*=key,\
       -*-helvetica-medium-r-*-*-12-*-*-*-*-*-*-*=rm,\
       -*-helvetica-medium-o-*-*-12-*-*-*-*-*-*-*=sl,\



DDD 2.1.1            Last change: 1 Jun 1997                   31






ddd(1)                    User Commands                    ddd(1)



       -*-helvetica-bold-r-*-*-12-*-*-*-*-*-*-*=bf,\
       -*-helvetica-bold-o-*-*-12-*-*-*-*-*-*-*=bs,\
       -*-helvetica-bold-r-*-*-14-*-*-*-*-*-*-*=Logo,\
       -*-helvetica-bold-r-*-*-12-*-*-*-*-*-*-*=logo,\
       -*-symbol-*-*-*-12-*-*-*-*-*-*-*=symbol


     The font names are used as follows:

     charset   The default font in buttons, menus, etc.

     small     The default font in a slightly smaller size.

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

     key       The font used for describing key caps.

     rm        Roman font.  In help texts.

     sl        Slanted font.  In help texts.

     bf        Bold face.  In help texts.

     bs        Slanted bold face.  In help texts.

     Logo      The DDD logo font (uppercase letters).

     logo      The DDD logo font (lowercase letters).

     symbol    The symbol font.  In help texts.

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

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

     The fonts in text fields are specified as follows:

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



DDD 2.1.1            Last change: 1 Jun 1997                   32






ddd(1)                    User Commands                    ddd(1)



       -*-lucidatypewriter-medium-r-*-*-12-*-*-*-*-*-*-*=charset

     And here is another resolution-independent alternative:

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

     These are the fonts in the command tool:

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

     The resolution-independent alternative looks like this:

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

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

  Setting DDD Colors
     These are the most important color resources used in DDD:

     Ddd*foreground:               black

     Ddd*background:               grey

     Ddd*XmText.background:grey90        

     Ddd*XmTextField.background:grey90   

     Ddd*GraphEdit.background:grey90     

     Ddd*XmList.background:grey90        

     Ddd*graph edit.nodeColor:black     
              -

     Ddd*graph edit.edgeColor:blue4     
              -

     Ddd*graph edit.selectColor:black   
              -




DDD 2.1.1            Last change: 1 Jun 1997                   33






ddd(1)                    User Commands                    ddd(1)



     Ddd*graph edit.gridColor:black     
              -

     Ddd*graph edit.frameColor:grey50    
              -

     Ddd*graph edit.outlineColor:grey50  
              -

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

  Options and Preferences
     The following resources determine DDD  options  and  prefer-
     ences.

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

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

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

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

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

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

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

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




DDD 2.1.1            Last change: 1 Jun 1997                   34






ddd(1)                    User Commands                    ddd(1)



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

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

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

     indentAmount (class IndentAmount)
          The number of columns used for  the  code  line  number
          display (default:  8)

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

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

     saveHistoryOnExit (class SaveHistoryOnExit)
          If `true' (default), the command history  is  automati-
          cally  saved  when DDD exits.  If the inferior debugger
          saves its command history, its history  file  is  used,
          otherwise, `$HOME/.ddd history' is used.
                                -

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

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




DDD 2.1.1            Last change: 1 Jun 1997                   35






ddd(1)                    User Commands                    ddd(1)



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

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

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

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

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

     ungrabMousePointer (class UngrabMousePointer)
          When debugging a modal X application, DDD may interrupt
          it  while  it  has  grabbed the pointer, making further
          interaction impossible.  If this is  `true'  (default),
          DDD  will  check  after  each  interaction  whether the
          pointer is grabbed.  If this is so, DDD  will  instruct
          the debugged program to ungrab the mouse pointer.

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

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

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

  Debugger Settings
     The following resources determine the inferior debugger.




DDD 2.1.1            Last change: 1 Jun 1997                   36






ddd(1)                    User Commands                    ddd(1)



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

     dbxSettings (class DBXSettings)
          This string contains a list of  newline-separated  com-
          mands that are also initially sent to DBX.  By default,
          it is empty.
          In future DDD releases, this resource will be  used  to
          save and restore debugger settings.

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

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

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

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

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

     fullNameMode (class TTYMode)
          If this is `true', DDD reports the current source posi-
          tion  on  standard  output  in GDB `--fullname' format.
          See also the `--fullname' option, below.



DDD 2.1.1            Last change: 1 Jun 1997                   37






ddd(1)                    User Commands                    ddd(1)



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

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

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

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

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

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

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

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

            Ddd*rHostInitCommands: stty -echo -onlcr

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

     synchronousDebugger (class SynchronousDebugger)
          If  `true',  X  events  are  not  processed  while  the



DDD 2.1.1            Last change: 1 Jun 1997                   38






ddd(1)                    User Commands                    ddd(1)



          debugger  is  busy.  This may result in slightly better
          performance on single-processor systems.  See also  the
          `--sync-debugger' option, below.

     ttyMode (class TTYMode)
          If `true',  enable  TTY  interface,  taking  additional
          debugger  commands  from  standard input and forwarding
          debugger output  on  standard  output.   See  also  the
          `--tty' and `--fullname' options, below.

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

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

     xdbSettings (class XDBSettings)
          This string contains a list of  newline-separated  com-
          mands that are also initially sent to XDB.  By default,
          it is empty.
          In future DDD releases, this resource will be  used  to
          save and restore debugger settings.

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

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

          The following characters have special meanings:

          + Commands ending with '...' insert  their  name,  fol-
            lowed by a space, in the debugger console.

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

          + The string `()' is replaced by the  current  contents



DDD 2.1.1            Last change: 1 Jun 1997                   39






ddd(1)                    User Commands                    ddd(1)



            of the argument field `()'.

          The following button names are reserved:

          Clear     Clear current command

          Prev      Show previous command

          Next      Show next command

          Apply     Send the given command to the debugger.

          Back      Lookup previously selected source position.

          Forward   Lookup next selected source position.

          Edit      Edit current source file.

          Reload    Reload source file.

          Complete  Complete current command.

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

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


          The name of the button widget is built from the  button
          specification.   First, trailing `...' and `^' specifi-
          cations removed.  Then,  any  non-identifier  character
          (letter, number, underscore) is replaced by ` ' (under-
                                                       -
          score).   Thus,  the  button   specification   `display
          *()...'   results  in  a  widget  named  `display    '.
                                                           ----
          Unless a `labelString' resource is specified, the capi-
          talized button specification is used as label.

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

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

            Ddd*consoleButtons: Yes:No:break^C

          This setting creates some more buttons:

            Ddd*consoleButtons: \



DDD 2.1.1            Last change: 1 Jun 1997                   40






ddd(1)                    User Commands                    ddd(1)



            Yes:No:run:Clear:Prev:Next:Apply:break^C

          See also the `dataButtons', `sourceButtons' and  `tool-
          Buttons' resources, below.


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

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

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

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

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

            Ddd*sourceButtons: \
            run:step:next:stepi:nexti:cont:\
            finish:kill:up:down:\
            Back:Forward:Edit:interrupt^C

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

            Ddd*sourceButtons: \
            print *():graph display *():print /x ():\
            whatis ():ptype ():watch ():until:shell

          An even more professional setting uses customized  but-
          ton labels:

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

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



DDD 2.1.1            Last change: 1 Jun 1997                   41






ddd(1)                    User Commands                    ddd(1)



          below.

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

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

          The default resource value is

            Ddd*toolButtons: \
            run:interrupt^C:step:stepi:\
            next:nexti:cont:finish:\
            up:down:Back:Forward:Edit:kill

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

            Ddd*tool buttons.break.topPosition:1    
                    -
            Ddd*tool buttons.break.bottomPosition:2 
                    -
            Ddd*tool buttons.break.leftPosition:0   
                    -
            Ddd*tool buttons.break.rightPosition:8  
                    -

          while the Back button position is specified as

            Ddd*tool buttons.Back.topPosition:6     
                    -
            Ddd*tool buttons.Back.bottomPosition:7  
                    -
            Ddd*tool buttons.Back.leftPosition:0    
                    -
            Ddd*tool buttons.Back.rightPosition:4   
                    -

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

            Ddd*tool buttons.fractionBase:10         
                    -

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



DDD 2.1.1            Last change: 1 Jun 1997                   42






ddd(1)                    User Commands                    ddd(1)



          details.

          If the `toolButtons' resource value is empty, the  com-
          mand tool is not created.

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

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

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

  Data Display Resources
     The following resources control the data display.

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

          The general pattern to replace  a  function  definition
          FUNCTION with a new definition NEW DEF is:
          --------                       -------

          #pragma replace FUNCTION
                          --------
          FUNCTION(ARGS...) = NEW DEF;
          -------- ----       -------

          The following VSL functions are frequently used:

          color(BOX, FOREGROUND [, BACKGROUND])
                ---  ----------    ----------
                    Set the FOREGROUND and BACKGROUND  colors  of
                            ----------     ----------
                    BOX.
                    ---

          display color(BOX)
                 -      ---
                    The color used in  data  displays.   Default:
                    color(BOX, "black", "grey95")
                          ---

          title color(BOX)
               -      ---
                    The color used in the  title  bar.   Default:
                    color(BOX, "black")
                          ---

          disabled color(BOX)
                  -      ---



DDD 2.1.1            Last change: 1 Jun 1997                   43






ddd(1)                    User Commands                    ddd(1)



                    The color used for disabled boxes.   Default:
                    color(BOX, "white", "grey50")
                          ---

          simple color(BOX)
                -      ---
                    The color used for simple  values.   Default:
                    color(BOX, "black")
                          ---

          pointer color(BOX)
                 -      ---
                    The  color  used  for   pointers.    Default:
                    color(BOX, "blue4")
                          ---

          struct color(BOX)
                -      ---
                    The  color  used  for  structures.   Default:
                    color(BOX, "black")
                          ---

          array color(BOX)
               -      ---
                    The  color   used   for   arrays.    Default:
                    color(BOX, "blue4")
                          ---

          reference color(BOX)
                   -      ---
                    The  color  used  for  references.   Default:
                    color(BOX, "blue4")
                          ---

          stdfontfamily()
                    The font family used.  One of family times(),
                                                        -
                    family courier(),         family helvetica(),
                          -                         -
                    family new century(), or  family typewriter()
                          -   -                     -
                    (default).

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

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

          stdfontweight()
                    The font weight used.  Either weight medium()
                                                        -
                    (default) or weight bold().
                                       -

          To set the pointer color to "red4", use

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

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

            Ddd*vslDefs: \



DDD 2.1.1            Last change: 1 Jun 1997                   44






ddd(1)                    User Commands                    ddd(1)



            #pragma replace stdfontsize\n\
            #pragma replace stdfontpoints\n\
            stdfontsize() = 0;\n
            stdfontpoints() = 100;\n

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

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

          See the file `ddd.vsl' for further definitions to over-
          ride using the `vslDefs' resource.


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

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

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

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

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

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

  Customizing Helper Programs
     The following resources determine external programs  invoked
     by DDD.

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



DDD 2.1.1            Last change: 1 Jun 1997                   45






ddd(1)                    User Commands                    ddd(1)



          $XEDITOR first, then $EDITOR, then vi:

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

          This `.dddinit' setting invokes an editing session  for
          an XEmacs editor running gnuserv:
             ------                -------

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

          This `.dddinit' setting invokes an editing session  for
          an Emacs editor running emacsserver:
             -----                -----------

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


     lessTifHacks (class LessTifHacks)
          If true, enable some hacks to  make  DDD  run  properly
          with  LessTif.   The  default  value is true if DDD was
          compiled with a LessTif version earlier than  1.0,  and
          false, otherwise.

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

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


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

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


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

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



DDD 2.1.1            Last change: 1 Jun 1997                   46






ddd(1)                    User Commands                    ddd(1)



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

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


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

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

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

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

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

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

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

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

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

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




DDD 2.1.1            Last change: 1 Jun 1997                   47






ddd(1)                    User Commands                    ddd(1)



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


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

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

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

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

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

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

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

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

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

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

     traceShellCommands (class Trace)



DDD 2.1.1            Last change: 1 Jun 1997                   48






ddd(1)                    User Commands                    ddd(1)



          If `true', show the programs invoked by DDD on standard
          output.  Default is `false'.

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

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

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

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

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

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

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

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

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

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

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

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

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



DDD 2.1.1            Last change: 1 Jun 1997                   49






ddd(1)                    User Commands                    ddd(1)



          any.

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

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

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

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

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

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

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

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

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

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

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



DDD 2.1.1            Last change: 1 Jun 1997                   50






ddd(1)                    User Commands                    ddd(1)



          any.

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

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

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

     unselect-all ()
          Clear the selection.

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

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

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

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

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

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

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

     gdb-delete-or-control (control-character)
                            ------- ---------
          Like gdb-control, but effective only if the  cursor  is



DDD 2.1.1            Last change: 1 Jun 1997                   51






ddd(1)                    User Commands                    ddd(1)



          at  the end of a line.  Otherwise, control-character is
                                             ------- ---------
          ignored and  the  character  following  the  cursor  is
          deleted.  Bound to Ctrl+D.

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

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

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

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

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

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

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

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

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

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

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

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





DDD 2.1.1            Last change: 1 Jun 1997                   52






ddd(1)                    User Commands                    ddd(1)



     All other arguments and options are passed to  the  inferior
     debugger.   To  pass an option to the inferior debugger that
     conflicts with an X option, or  with  a  DDD  option  listed
     here, use the `--debugger' option, below.

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

     --attach-source-window
          Attaches only the source window to  the  debugger  con-
          sole.

     --attach-data-window
          Attaches only the source window to  the  debugger  con-
          sole.

     --button-tips
          Enable button tips.

     --configuration
          Show the DDD configuration settings and exit.

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

     --dbx
          Run the DBX debugger as inferior debugger.

     --debugger name
                ----
          Invoke the inferior debugger name.  This is  useful  if
                                       ----
          you  have  several  debugger versions around, or if the
          inferior debugger cannot be invoked as `gdb', `dbx', or
          `xdb',  respectively.   This option can also be used to
          pass options to the inferior debugger that would other-
          wise  conflict with DDD options.  For instance, to pass
          a `-d directory' option to XDB, use:
                ---------

            ddd --debugger "xdb -d directory"
                                   ---------


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

     --exec-window
          Run the debugged program in a specially created  execu-
          tion  window.   This  is  useful for programs that have
          special  terminal  requirements  not  provided  by  the
          debugger window, as raw keyboard processing or terminal



DDD 2.1.1            Last change: 1 Jun 1997                   53






ddd(1)                    User Commands                    ddd(1)



          control sequences.

     --fullname
          Enable TTY interface, taking additional  debugger  com-
          mands  from standard input and forwarding debugger out-
          put on standard output.  Current positions  are  issued
          in  GDB `-fullname' format suitable for debugger front-
          ends.

     --gdb
          Run the GDB debugger as inferior debugger.

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

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

     --host hostname
            --------
          Invoke the inferior debugger  directly  on  the  remote
          host hostname.  See `REMOTE DEBUGGING', above.
               --------

     --lesstif-hacks
          Enable  some  hacks  to  make  DDD  run  properly  with
          LessTif.  See also the `lessTifHacks' resource, above.

     --license
          Show the DDD license and exit.

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

     --manual
          Show this manual page and exit.

     --no-button-tips
          Disable button tips.

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

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

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

     --no-exec-window
          Do not run the debugged program in a specially  created



DDD 2.1.1            Last change: 1 Jun 1997                   54






ddd(1)                    User Commands                    ddd(1)



          execution  window;  use  the  debugger console instead.
          Useful  for  programs   that   have   little   terminal
          input/output, or for remote debugging.

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

     --no-lesstif-hacks
          Disable hacks to make DDD run  properly  with  LessTif.
          See also the `lessTifHacks' resource, above.

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

     --no-value-tips
          Disable value tips.

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

     --panned-graph-editor
          Use an Athena panner to scroll the data  window.   Most
          people  prefer  panners  on  scroll bars, since panners
          allow two-dimensional scrolling.  However,  the  panner
          is  off by default, since some Motif implementations do
          not  work  well  with   Athena   widgets.    See   also
          --scrolled-graph-editor, below.

     --rhost hostname
             --------
          Run the inferior debugger interactively on  the  remote
          host hostname.  See `REMOTE DEBUGGING', above.
               --------

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

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

     --status-at-bottom
          Place the status line at the bottom of the source  win-
          dow.

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

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



DDD 2.1.1            Last change: 1 Jun 1997                   55






ddd(1)                    User Commands                    ddd(1)



          single-processor systems.

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

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

     --trace
          Show both interaction and shell commands.

     --tty
          Enable TTY interface, taking additional  debugger  com-
          mands  from standard input and forwarding debugger out-
          put on standard output.  Current positions  are  issued
          in a format readable for humans.

     --value-tips
          Enable value tips.

     --version
          Show the DDD version and exit.

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

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

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

     --xdb
          Run XDB as inferior debugger.

FILES
     $HOME/.dddinit      Individual  DDD  resource   file.    DDD
                         options are saved here.
     $HOME/.ddd history  Default DDD command history file.
               -
     $HOME/.gdbinit      GDB initialization file.
     $HOME/.dbxinit      DBX initialization file.
     $HOME/.dbxrc        Alternate DBX initialization file.
     $HOME/.xdbrc        XDB initialization file.



DDD 2.1.1            Last change: 1 Jun 1997                   56






ddd(1)                    User Commands                    ddd(1)



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

     `gdb' entry in info

     Using GDB: A Guide to  the  GNU  Source-Level  Debugger,  by
     ----- ---  - ----- --  ---  ---  ------ -----  --------
     Richard M. Stallman and Roland H. Pesch.

     DDD-A  Free  Graphical  Front-End  for  UNIX  Debuggers,  by
     --- -  ----  ---------  ----- ---  ---  ----  ---------
     Andreas  Zeller  and  Dorothea  L"tkehaus,  Computer Science
     Report 95-07, Technische Universit"t Braunschweig, 1995.

     DDD   ein  Debugger  mit  graphischer  Datendarstellung,  by
     ---   ---  --------  ---  -----------  ----------------
     Dorothea  L"tkehaus,  Diploma Thesis, Technische Universit"t
     Braunschweig, 1994.

     The DDD FTP site,
             --- ----

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


     The DDD WWW page,
             --- ----

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


     The DDD Mailing List,
             ------- ----

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

     For more information on this list, send a mail to

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


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

       set height 0
       set width 0
       set print repeats 0
       set verbose off
       set prompt (gdb)

     DDD sets these values automatically when invoking GDB.

     If these values are changed, there may be some malfunctions,
     especially  in  the  data display.  If you want to display C
     strings (i.e., `char  *'-fields),  it  might  be  useful  to
     change the settings of `print repeats' and `print elements'.



DDD 2.1.1            Last change: 1 Jun 1997                   57






ddd(1)                    User Commands                    ddd(1)



     But to recognize array structures correctly, you should have
     `print  repeats'  set to 0.  Also, do not change the setting
     of `print elements' while there are array structures in  the
     data display.

     When debugging at the machine level with GDB 4.12  and  ear-
     lier as inferior debugger, use a `display /x $pc' command to
     ensure the program counter value  is  updated  correctly  at
     each stop.  You may also enter the command in $HOME/.gdbinit
     or (better yet) upgrade to the most recent GDB version.

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

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

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

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

  General Limitations
     If command output is sent to the  debugger  console,  it  is
     impossible  for DDD to distinguish between the output of the
     debugged program and the output of  the  inferior  debugger.
     For  instance,  if  your  program  output  includes debugger
     prompts or debugger-like output, DDD will likely become con-
     fused.   To  avoid such problems, use the separate execution
     window.

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

REPORTING BUGS
     If you find a bug in DDD, please send us a bug  report.   We



DDD 2.1.1            Last change: 1 Jun 1997                   58






ddd(1)                    User Commands                    ddd(1)



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

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

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

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

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

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

       ddd --check-configuration

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

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

       ddd --trace

     This shows the dialog between DDD and the inferior  debugger
     on  standard  error  while  DDD  is  running.   Compare  the
     debugger output to the output of DDD and determine which one
     is wrong.

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

     + The fundamental principle of reporting  bugs  usefully  is
       this:   report all the facts.  If you are not sure whether
               ------ --- --- -----



DDD 2.1.1            Last change: 1 Jun 1997                   59






ddd(1)                    User Commands                    ddd(1)



       to state a fact or leave it out, state it!

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

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

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

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

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

     + Your DDD configuration.  Invoke DDD as

         ddd --configuration

       to get the configuration information.  If  this  does  not
       work, please include at least the DDD version, the type of
       machine you are using, and its operating system  name  and
       version number.

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

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

     + A description  of  what  behavior  you  observe  that  you
       believe is incorrect.  For example, "DDD gets a fatal sig-
       nal" or "DDD exits immediately after attempting to  create
       the data window".

     + If possible, include a dialog trace showing  the  interac-
                              ------ -----
       tion between DDD and the inferior debugger.  Such a dialog
       trace is  created  by  invoking  DDD  with  the  `--trace'
       option.   Include all trace output from the DDD invocation
       up to the first bug occurrence.

     + If you wish to suggest changes to the DDD source, send  us



DDD 2.1.1            Last change: 1 Jun 1997                   60






ddd(1)                    User Commands                    ddd(1)



       context  diffs.   If you even discuss something in the DDD
       source, refer to it by context, never by line number.
                                       -----

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

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

     In 1992, the VSL and Box libraries  were  recycled  for  the
     NORA  project.   For  NORA,  an experimental inference-based
     software development tool set, Andreas wrote a graph  editor
     (based  on  VSL  and  the  BOX libraries) and facilities for
     inter-process knowledge exchange.   Based  on  these  tools,
     Dorothea L"tkehaus 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 quar-
     ter of 1995, finally, Andreas completed DDD by  adding  com-
     mand  and  execution  windows, extensions for DBX and remote
     debugging as  well  as  configuration  support  for  several
     architectures.   Since then, many people have contributed to
     the success of DDD; see the file `CONTRIBUTORS' in  the  DDD
     distribution for details.

     Major DDD events:
     April, 1995         DDD 0.9: First DDD beta release
     May, 1995           DDD 1.0: First public DDD release
     December, 1995      DDD   1.4:   Machine-level    debugging,
                         glyphs, EMACS integration
     October, 1996       DDD 2.0: Color  displays,  XDB  support,
                         generic DBX support, command tool.
     May, 1997           DDD 2.1: Alias detection,  button  tips,
                         status displays.

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

IF YOU LIKE DDD...
     If you appreciate this software, or  have  any  suggestions,
     please send us a picture postcard.  Our address is:





DDD 2.1.1            Last change: 1 Jun 1997                   61






ddd(1)                    User Commands                    ddd(1)



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

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

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


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

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

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

     This directory also contains other documentation related  to
     DDD.

     A ROFF copy of this manual page, suitable  for  installation
     as      manual      page     on     UNIX     systems     (as
     `/usr/local/man/man1/ddd.1' or similar), is included in  the
     DDD source distribution.


COPYRIGHT
                      c
     DDD is Copyright   1995, 1996, 1997  Technische  Universit"t
     Braunschweig, Germany.

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

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

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



DDD 2.1.1            Last change: 1 Jun 1997                   62






ddd(1)                    User Commands                    ddd(1)



     from within DDD, use the `DDD License...' item in the `Help'
     menu.

                                       c
     This DDD manual page is Copyright   1995, 1996,  1997  Tech-
     nische Universit"t Braunschweig, Germany.

     Permission is granted to make and distribute verbatim copies
     of  this  manual page provided the copyright notice and this
     permission notice are preserved on all copies.

     Permission is granted to copy and distribute  modified  ver-
     sions  of this manual page under the conditions for verbatim
     copying, provided that the entire resulting derived work  is
     distributed under the terms of a permission notice identical
     to this one.

     Permission is granted to copy and distribute translations of
     this manual page into another language, under the above con-
     ditions for modified versions, except that  this  permission
     notice  may be included in translations approved by the Free
     Software Foundation instead of in the original English.


































DDD 2.1.1            Last change: 1 Jun 1997                   63