


ddd(1)                       DDD 1.4d                      ddd(1)


NNAAMMEE
       ddd, xddd - the data display debugger (v1.4d)

SSYYNNOOPPSSIISS
       dddddd    [----hheellpp] [----nnww] [----ggddbb] [----ddbbxx] [----ddeebbuuggggeerr
              _g_d_b_-_n_a_m_e] [----hhoosstt _h_o_s_t_n_a_m_e [----llooggiinn _u_s_e_r_n_a_m_e]]
              [----vvssll--lliibbrraarryy _l_i_b_r_a_r_y] [----vvssll--ppaatthh _p_a_t_h]
              [----ttrraaccee--ddiiaalloogg] [----ttrraaccee--sshheellll] [----eexxeecc--wwiinnddooww]
              [----nnoo--eexxeecc--wwiinnddooww] [----aattttaacchh--wwiinnddoowwss]
              [----sseeppaarraattee--wwiinnddoowwss] [----ssccrroolllleedd--ggrraapphh]
              [----ppaannnneedd--ggrraapphh] [----ttttyy] [----ffuullllnnaammee] [----vveerrssiioonn]
              [----ccoonnffiigguurraattiioonn] [----mmaannuuaall] [_g_d_b_-_o_p_t_i_o_n_s]
              [_x_-_o_p_t_i_o_n_s] [_v_s_l_-_o_p_t_i_o_n_s] [_p_r_o_g_r_a_m [_c_o_r_e|
              _p_r_o_c_e_s_s_-_i_d]]

       but usually just

       dddddd    _p_r_o_g_r_a_m


DDEESSCCRRIIPPTTIIOONN
       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:

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

       +o Make your program stop on specified conditions.

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

       +o 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 com-
       mands for these and other debugging purposes.   DDD  is  a
       _w_r_a_p_p_e_r  around an inferior GDB or DBX debugger.  In addi-
       tion to the GDB or DBX command-line  interface,  DDD  pro-
       vides  a _g_r_a_p_h_i_c_a_l _u_s_e_r _i_n_t_e_r_f_a_c_e to support common debug-
       ging tasks.  The DDD _g_r_a_p_h_i_c_a_l  _d_a_t_a  _d_i_s_p_l_a_y  allows  for
       interactive exploration of data structures.


IINNVVOOKKIINNGG DDDDDD
       You  can  run  DDD with no arguments or options.  However,
       the most usual way to start DDD is with  one  argument  or



DDD 1.4d                 12 January 1996                        1





ddd(1)                       DDD 1.4d                      ddd(1)


       two, specifying an executable program as the argument:

         dddddd pprrooggrraamm

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

         dddddd pprrooggrraamm ccoorree

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

         dddddd pprrooggrraamm 11223344

       would  attach  DDD to process 11223344 (unless you also have a
       file named `11223344'; DDD does check for a core file  first).

       By default, DDD uses GDB as inferior debugger.  Use

         dddddd ----ddbbxx pprrooggrraamm

       to run DBX as inferior debugger for the program.

       To learn more about DDD options, run

         dddddd ----hheellpp

       to  get  a  list  of  frequently  used options, or see the
       `OOPPTTIIOONNSS' section, below.


GGEETTTTIINNGG HHEELLPP
       You can get help on any visible DDD item by  pressing  the
       `FF11'  key  and  moving the question mark arrow on the item
       you want help for.  Clicking on the item pops  up  a  help
       text.

       You  can  get help on GDB and DBX commands by entering the
       `hheellpp' command at the `((ggddbb))' or `((ddbbxx))' prompt (see  next
       section).


EENNTTEERRIINNGG CCOOMMMMAANNDDSS
       In  the  _c_o_m_m_a_n_d  _w_i_n_d_o_w, you can interact with the GDB or
       DBX command interface.  Enter GDB commands at the  `((ggddbb))'
       prompt, and DBX commands at the `((ddbbxx))' prompt.  Arbitrary
       GDB and DBX commands can be used.

       You can _r_e_p_e_a_t previous and next commands by pressing  the
       `UUpp' and `DDoowwnn' keys, respectively.  If you enter an empty
       line, the last command is repeated as well.  The  `CCoommmmaanndd
       HHiissttoorryy......'  item in the `CCoommmmaannddss......' menu shows the com-
       mand history.




DDD 1.4d                 12 January 1996                        2





ddd(1)                       DDD 1.4d                      ddd(1)


       Using GDB, you can  _c_o_m_p_l_e_t_e  commands  and  arguments  by
       pressing  the TTAABB key; pressing the TTAABB key multiple times
       shows one possible expansion after the other.

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

       bbrreeaakk [_f_i_l_e::]_f_u_n_c_t_i_o_n
               (GDB only) Set a breakpoint at _f_u_n_c_t_i_o_n (in _f_i_l_e).

       ssttoopp iinn _f_u_n_c_t_i_o_n
               (DBX only) Set a breakpoint at _f_u_n_c_t_i_o_n_.

       rruunn [_a_r_g_l_i_s_t]
              Start your program (with _a_r_g_l_i_s_t, if specified).

       wwhheerree  Display the program stack.

       pprriinntt _e_x_p_r
               Display the value of an expression.

       ccoonntt   Continue running your program (after stopping, e.g.
              at a breakpoint).

       nneexxtt   Execute  next  program  line (after stopping); step
              _o_v_e_r any function calls in the line.

       sstteepp   Execute next program line  (after  stopping);  step
              _i_n_t_o any function calls in the line.

       hheellpp [_n_a_m_e]
              Show information about the command _n_a_m_e, or general
              usage information.

       qquuiitt   Exit DDD.

       For full details on GDB commands, see _U_s_i_n_g _G_D_B_:  _A  _G_u_i_d_e
       _t_o  _t_h_e  _G_N_U _S_o_u_r_c_e_-_L_e_v_e_l _D_e_b_u_g_g_e_r, by Richard M. Stallman
       and Roland H. Pesch.  The same text is available online as
       the ggddbb entry in the iinnffoo program.

       For  full  details on DBX commands, see the DBX documenta-
       tion.


OOPPEENNIINNGG FFIILLEESS
       If you did not invoke  DDD  specifying  a  program  to  be
       debugged,  you  can  use the `FFiillee' menu to open programs,
       core dumps and sources.

       To open a program to be debugged,  select  `OOppeenn  PPrrooggrraamm'
       from the `FFiillee' menu.

       To  open  a  core dump for the program, select `OOppeenn CCoorree'



DDD 1.4d                 12 January 1996                        3





ddd(1)                       DDD 1.4d                      ddd(1)


       from the `FFiillee' menu.

       To open an arbitrary source  file,  select  `OOppeenn  SSoouurrccee'
       from the `FFiillee' menu.


BBRREEAAKKPPOOIINNTTSS
       If  the  source  of the debugged program is available, the
       _s_o_u_r_c_e _w_i_n_d_o_w displays its current  source  text.   (If  a
       source  text cannot be found, use the GDB `ddiirreeccttoorryy' com-
       mand to specify source text directories).

       Using the source window, you can make the program stop  at
       certain _b_r_e_a_k_p_o_i_n_t_s and trace its execution.

   SSeettttiinngg BBrreeaakkppooiinnttss bbyy LLooccaattiioonn
       If  the  source line is visible, click with the _l_e_f_t _m_o_u_s_e
       _b_u_t_t_o_n on the source line number and then on the `BBrreeaakk(())'
       button.

       As  an  alternative,  you can simply press the _r_i_g_h_t _m_o_u_s_e
       _b_u_t_t_o_n on the source  line  number  and  select  the  `SSeett
       BBrreeaakkppooiinntt' item from the popup menu.

       As  another  alternative, you can enter the line number in
       the argument field (indicated by `(())::') and click  on  the
       `BBrreeaakk(())' button.

       As  yet  another  alternative, you can select `EEddiitt BBrreeaakk--
       ppooiinnttss......'  in the `SSoouurrccee' menu, click on the `NNeeww'  but-
       ton and enter the line number.

       And  finally,  you can also use the GDB `bbrreeaakk' command or
       the DBX `ssttoopp' command.  Type `hheellpp bbrreeaakk' at the  `((ggddbb))'
       prompt (or `hheellpp ssttoopp' at the `((ddbbxx))' prompt) for details.

       (If you find this number  of  alternatives  confusing,  be
       aware  that  DDD  users  fall into three categories, which
       must all be supported.  _N_o_v_i_c_e _u_s_e_r_s explore DDD  and  may
       prefer  to  use  one  single mouse button.  _A_d_v_a_n_c_e_d _u_s_e_r_s
       know how to use shortcuts and prefer popup menus.  _E_x_p_e_r_i_-
       _e_n_c_e_d  _G_D_B  _a_n_d  _D_B_X  _u_s_e_r_s prefer the command line inter-
       face.)

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

   SSeettttiinngg BBrreeaakkppooiinnttss bbyy NNaammee
       If the function name is visible, click with the _l_e_f_t _m_o_u_s_e
       _b_u_t_t_o_n' on the function name.  The function name is copied
       to  the  argument field.  Click on the `BBrreeaakk(())' button to
       set a breakpoint there.

       As a shorter alternative, you can simply press  the  _r_i_g_h_t



DDD 1.4d                 12 January 1996                        4





ddd(1)                       DDD 1.4d                      ddd(1)


       _m_o_u_s_e  _b_u_t_t_o_n  on the function name and select the `bbrreeaakk'
       item from the popup menu.

       As another alternative, you can enter the function name in
       the  argument  field  (possibly  using  name completion by
       pressing the `TTaabb' key) and click on the `BBrreeaakk(())' button.

       As  yet  another  alternative, you can click on `NNeeww' from
       the  Breakpoint  editor  (invoked  through  `EEddiitt   BBrreeaakk--
       ppooiinnttss......'   in  the `SSoouurrccee' menu) and enter the function
       name.

       Finally, you can use the GDB `bbrreeaakk' command  or  the  DBX
       `ssttoopp'  command.   Type `hheellpp bbrreeaakk' at the `((ggddbb))' prompt
       (or `hheellpp ssttoopp' at the `((ddbbxx))' prompt) for details.

   DDiissaabblliinngg aanndd EEnnaabblliinngg BBrreeaakkppooiinnttss
       Note: DBX does not support breakpoint disabling.

       Press the _r_i_g_h_t _m_o_u_s_e _b_u_t_t_o_n on the  breakpoint  name  and
       select  the  `DDiissaabbllee  BBrreeaakkppooiinntt'  item  (or  the `EEnnaabbllee
       BBrreeaakkppooiinntt' item, respectively) from the popup menu.

       As an alternative, you can select the breakpoint and click
       on `DDiissaabbllee' or `EEnnaabbllee' in the Breakpoint editor (invoked
       through `EEddiitt BBrreeaakkppooiinnttss......' in the `SSoouurrccee' menu).

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

       Finally,  you  can  use  the  GDB `ddiissaabbllee' command.  Type
       `hheellpp ddiissaabbllee' at the `((ggddbb))' prompt for details.

   TTeemmppoorraarryy BBrreeaakkppooiinnttss
       A _t_e_m_p_o_r_a_r_y _b_r_e_a_k_p_o_i_n_t is immediately deleted as  soon  as
       it  is reached.  To set a temporary breakpoint,  press the
       _r_i_g_h_t _m_o_u_s_e _b_u_t_t_o_n on the source line  number  and  select
       the `SSeett TTeemmppoorraarryy BBrreeaakkppooiinntt' 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  `CCoonnttiinnuuee UUnnttiill HHeerree' 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, execution
       stops when the temporary breakpoint is reached.

   DDeelleettiinngg BBrreeaakkppooiinnttss
       If the breakpoint is visible, click with  the  _l_e_f_t  _m_o_u_s_e
       _b_u_t_t_o_n  on  the  breakpoint.   The  breakpoint location is
       copied to the argument  field.   Click  on  the  `CClleeaarr(())'



DDD 1.4d                 12 January 1996                        5





ddd(1)                       DDD 1.4d                      ddd(1)


       button to delete all breakpoints there.

       If the function name is visible, click with the _l_e_f_t _m_o_u_s_e
       _b_u_t_t_o_n on the function name.  The function name is  copied
       to  the  argument field.  Click on the `CClleeaarr(())' button to
       set a breakpoint there.

       As a shorter alternative, you can simply press  the  _r_i_g_h_t
       _m_o_u_s_e  _b_u_t_t_o_n  on the function name and select the `cclleeaarr'
       item from the popup menu.

       As yet another alternative, you can select the  breakpoint
       and  click on `DDeelleettee' from the Breakpoint editor (invoked
       through `EEddiitt BBrreeaakkppooiinnttss......' in the `SSoouurrccee' menu).

       Finally, you can use the GDB  `cclleeaarr'  and  `ddeelleettee'  com-
       mands.   Type `hheellpp cclleeaarr' or `hheellpp ddeelleettee' at the `((ggddbb))'
       prompt for details.

   MMoorree BBrreeaakkppooiinntt FFeeaattuurreess
       Using the Breakpoint editor (invoked through `EEddiitt  BBrreeaakk--
       ppooiinnttss......'  in  the `SSoouurrccee' menu), you can specify break-
       point conditions and ignore counts.  Click on the  `CCoonnddii--
       ttiioonn......'  and  `IIggnnoorree  CCoouunntt......' buttons and click on the
       `HHeellpp' button.

       More breakpoint features can be invoked through  the  com-
       mand  window.   Enter  `hheellpp  bbrreeaakkppooiinnttss'  at the `((ggddbb))'
       prompt.


LLOOOOKKIINNGG UUPP IITTEEMMSS
   SSeeaarrcchhiinngg DDeeffiinniittiioonnss
       If you wish to lookup a specific function or variable def-
       inition  whose  name  is visible in the source text, click
       with the _l_e_f_t _m_o_u_s_e _b_u_t_t_o_n on  the  function  or  variable
       name.  The name is copied to the argument field.  Click on
       the `LLooookkuupp(())' button to find its definition.

       As a shorter alternative, you can simply press  the  _r_i_g_h_t
       _m_o_u_s_e  _b_u_t_t_o_n on the function name and select the `llooookkuupp'
       item from the popup menu.

       As another alternative, you can enter the function name in
       the  argument  field and click on the `LLooookkuupp(())' button to
       find its definition.

       Finally, you can use the GDB `iinnffoo  lliinnee'  command.   Type
       `hheellpp iinnffoo lliinnee' at the `((ggddbb))' prompt for details.

   SSeeaarrcchhiinngg IItteemmss iinn tthhee SSoouurrccee TTeexxtt
       If  the  item  you wish to search is visible in the source
       text, click with the _l_e_f_t _m_o_u_s_e _b_u_t_t_o_n on it.  The identi-
       fier  is  copied  to  the  argument  field.   Click on the



DDD 1.4d                 12 January 1996                        6





ddd(1)                       DDD 1.4d                      ddd(1)


       `FFiinndd>>>>(())' button to find following occurrences and on the
       `FFiinndd<<<<(())' button to find previous occurrences.

       As  an alternative, you can enter the item in the argument
       field and click on one of the `FFiinndd' buttons.

       By default, DDD finds only complete words.  To search  for
       arbitrary  substrings, change the value of the `FFiinndd WWoorrddss
       OOnnllyy' option in the `SSoouurrccee OOppttiioonnss' menu.

   FFiinnddiinngg BBrreeaakkppooiinnttss
       If you wish to lookup a specific  breakpoint,  select  the
       `LLooookkuupp'  item from the `BBrreeaakkppooiinnttss' menu.  After select-
       ing a breakpoint from the list and clicking  the  `LLooookkuupp'
       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
       `LLooookkuupp(())' button to find its definition.

   LLooookkiinngg uupp PPrreevviioouuss LLooccaattiioonnss
       Use the `BBaacckk' and `FFoorrwwaarrdd' buttons to lookup previous or
       next looked-up locations.  The location  found  is  under-
       lined.


RRUUNNNNIINNGG TTHHEE PPRROOGGRRAAMM
   SSttaarrttiinngg PPrrooggrraamm EExxeeccuuttiioonn
       Select `RRuunn' from the `PPrrooggrraamm' 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
       arguments  in  the text field.  Afterwards, press the `OOKK'
       button to start execution with the selected arguments.

       To run your program again, with the same arguments, select
       `RRuunn  AAggaaiinn'  from  the  `PPrrooggrraamm' menu or press the `RRuunn'
       button below.  You may also enter `rruunn', followed by argu-
       ments at the `((ggddbb))' or `((ddbbxx))' prompt instead.

       When  the  program is first started, DDD invokes an _e_x_e_c_u_-
       _t_i_o_n _w_i_n_d_o_w, where the program terminal input  and  output
       is  shown.   (You can disable this feature by starting DDD
       with the `----nnoo--eexxeecc--wwiinnddooww' option.)

   SSttooppppiinngg tthhee PPrrooggrraamm
       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 `IInntteerrrruupptt' button or typing CCttrrll++CC in a DDD window.

   RReessuummiinngg EExxeeccuuttiioonn
       To resume execution, at the  address  where  your  program



DDD 1.4d                 12 January 1996                        7





ddd(1)                       DDD 1.4d                      ddd(1)


       last  stopped, click on the `CCoonnttiinnuuee` button.  Any break-
       points set at that address are bypassed.

       To execute just one source line, click on the `SStteepp'  but-
       ton.  The program is executed until control reaches a dif-
       ferent source line, which may be in a different  function.

       To  continue  to  the  next  line in the current function,
       click on the `NNeexxtt' button.  This is  similar  to  `SStteepp',
       but  any  function calls appearing within the line of code
       are executed without stopping.

       To continue running until the  current  function  returns,
       use  the  `FFiinniisshh' button.  The returned value (if any) is
       printed.

       To continue running until a line after the current  source
       line  is  reached,  use the `CCoonnttiinnuuee UUnnttiill HHeerree' facility
       from the line popup menu.   See  `TTeemmppoorraarryy  BBrreeaakkppooiinnttss',
       above, for a discussion.

   EExxaammiinniinngg tthhee SSttaacckk
       When your program has stopped, the first thing you need to
       know is where it stopped and how it got there.

       The `UUpp' button selects the function that called the  cur-
       rent one.

       The  `DDoowwnn' button selects the function that was called by
       the current one.

       You can also type the GDB and DBX `uupp' and `ddoowwnn' commands
       at the `((ggddbb))' or `((ddbbxx))' prompt.


EEXXAAMMIINNIINNGG DDAATTAA
       In DDD, the usual way to examine data is using the _g_r_a_p_h_i_-
       _c_a_l _d_a_t_a _d_i_s_p_l_a_y in the  _d_a_t_a  _w_i_n_d_o_w.   The  data  window
       holds  _d_i_s_p_l_a_y_s showing names and the values of variables.
       The display is updated each time the program stops.

   DDiissppllaayyiinngg VVaarriiaabbllee VVaalluueess
       To create a new display, select the variable  by  clicking
       the  _l_e_f_t  _m_o_u_s_e _b_u_t_t_o_n on its name.  The variable name is
       copied to the argument field.  By clicking the `DDiissppllaayy(())'
       button, a new display is created in the data window.

       As  a  shorter alternative, you can simply press the _r_i_g_h_t
       _m_o_u_s_e _b_u_t_t_o_n on the variable name and select the `ddiissppllaayy'
       item from the popup menu.

       As  another  alternative,  you may also enter the variable
       name in the argument field and press the `DDiissppllaayy(())'  but-
       ton.



DDD 1.4d                 12 January 1996                        8





ddd(1)                       DDD 1.4d                      ddd(1)


       If  the  data  window is visible, you may invoke the `EEddiitt
       DDiissppllaayyss......' item from the `DDaattaa' menu and  click  on  the
       `NNeeww......' button.  Enter the variable name in the resulting
       prompt dialog.

       Finally, you may enter

         ggrraapphh ddiissppllaayy  _e_x_p_r

       at the `((ggddbb))' or `((ddbbxx))' prompt.

   SSeelleeccttiinngg DDiissppllaayyss
       Each display in the data window has a _t_i_t_l_e _b_a_r containing
       the  _d_i_s_p_l_a_y _n_u_m_b_e_r and the displayed expression (the _d_i_s_-
       _p_l_a_y _n_a_m_e).  Below the title, the _d_i_s_p_l_a_y _v_a_l_u_e is  shown.

       You  can  select  individual  displays by clicking on them
       with the _l_e_f_t _m_o_u_s_e _b_u_t_t_o_n.  The resulting  expression  is
       shown in the _a_r_g_u_m_e_n_t _f_i_e_l_d, below.

       You can _e_x_t_e_n_d an existing selection by pressing the SShhiifftt
       _K_e_y _w_h_i_l_e _s_e_l_e_c_t_i_n_g_.

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

   SSeelleeccttiinngg MMuullttiippllee DDiissppllaayyss
       Multiple displays are selected by pressing and holding the
       _l_e_f_t _m_o_u_s_e _b_u_t_t_o_n 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.

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

   SSeelleeccttiinngg DDiissppllaayy PPaarrttss
       If a display is composed from several values (that  is,  a
       C/C++  _c_l_a_s_s,  _s_t_r_u_c_t, _u_n_i_o_n, or _a_r_r_a_y; or a Pascal/Modula
       _R_E_C_O_R_D or _A_R_R_A_Y),  you  can  select  individual  parts  by
       clicking  on their names or values.  The resulting expres-
       sion is shown in the _a_r_g_u_m_e_n_t _f_i_e_l_d, below.

       Selection of multiple display parts is not supported.

   MMaanniippuullaattiinngg AAggggrreeggaattee VVaalluueess
       _A_g_g_r_e_g_a_t_e _V_a_l_u_e_s can be shown _e_x_p_a_n_d_e_d, that is,  display-
       ing all details, or _h_i_d_d_e_n, that is, displayed as `{{......}}'.

       To show details about an aggregate, select  the  aggregate
       by clicking the _l_e_f_t _m_o_u_s_e _b_u_t_t_o_n on its name or value and
       click on the `SShhooww(())' button.

       To hide details about an aggregate, select  the  aggregate



DDD 1.4d                 12 January 1996                        9





ddd(1)                       DDD 1.4d                      ddd(1)


       by clicking the _l_e_f_t _m_o_u_s_e _b_u_t_t_o_n on its name or value and
       click on the `HHiiddee(())' button.

       As a faster alternative, you  can  also  press  the  _r_i_g_h_t
       _m_o_u_s_e  _b_u_t_t_o_n  on the aggregate and select the appropriate
       menu item.

       Arrays can be  aligned  horizontally  or  vertically.   To
       change the alignment of an array, select it and then click
       on the `RRoottaattee(())' button.

       As a faster alternative, you  can  also  press  the  _r_i_g_h_t
       _m_o_u_s_e  _b_u_t_t_o_n  on  the  array and select the `RRoottaattee' menu
       item.

   DDiissppllaayyiinngg DDeeppeennddeenntt VVaalluueess
       Dependent displays are created from an  existing  display.
       The  dependency  is  indicated  by arrows leading from the
       originating display to the dependent display.

       To create a dependent display, select the originating dis-
       play  or  display part and click on the `DDeeppeennddeenntt(())' but-
       ton.  A prompt dialog appears where you can  enter  a  new
       expression  _E_X_P_R  in  the  argument field.  By clicking on
       `OOKK', the new display showing _E_X_P_R is created.

       As a faster alternative, you  can  also  press  the  _r_i_g_h_t
       _m_o_u_s_e  _b_u_t_t_o_n  on  the originating display part and select
       the `DDeeppeennddeenntt DDiissppllaayy......' 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.

   DDeerreeffeerreenncciinngg PPooiinntteerrss
       Since so many data structures are realized using pointers,
       there  is a shortcut for creating dependent displays show-
       ing the value of a dereferenced pointer.

       To dereference a pointer, select the  originating  pointer
       value  or name and click on the `DDeerreeffeerreennccee(())' button.  A
       new display showing the dereferenced pointer value is cre-
       ated.

       As  a  faster  alternative,  you  can also press the _r_i_g_h_t
       _m_o_u_s_e _b_u_t_t_o_n on the originating pointer value or name  and
       select the `DDeerreeffeerreennccee' menu item.

   DDiissppllaayyiinngg MMuullttiippllee AArrrraayy IItteemmss
       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.




DDD 1.4d                 12 January 1996                       10





ddd(1)                       DDD 1.4d                      ddd(1)


       To display several successive objects of the same type  (a
       section of an array, or an array of dynamically determined
       size), use the notation [[_F_R_O_M...._T_O]] in display expressions.
       _F_R_O_M  and  _T_O  denote the first and last array position to
       display.  Thus,

         ggrraapphh ddiissppllaayy aarrggvv[[00....99]]

       creates ten new display nodes  for  `aarrggvv[[00]]',  `aarrggvv[[11]]',
       ..., `aarrggvv[[99]]'.

       As  an  alternative,  you  can  use GDB _a_r_t_i_f_i_c_i_a_l _a_r_r_a_y_s.
       Typing

         ggrraapphh ddiissppllaayy aarrggvv[[00]] @@ 1100

       creates a single array display node  containing  `aarrggvv[[00]]'
       up  to  `aarrggvv[[99]]'.   Generally, by using the `@@' operator,
       you can specify the number of array elements  to  be  dis-
       played.

       For  more  details on artificial arrays, see the GDB docu-
       mentation.

   DDeelleettiinngg DDiissppllaayyss
       To delete a single display, select it  and  click  on  the
       `DDeelleettee(())'  button.  As an alternative, you can also press
       the _r_i_g_h_t _m_o_u_s_e _b_u_t_t_o_n  on  the  display  and  select  the
       `DDeelleettee DDiissppllaayy' item.

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

       To delete several displays at once, select the `DDeelleettee......'
       item in the Display Editor (invoked through the `EEddiitt DDiiss--
       ppllaayyss......'  item in the `DDaattaa' menu).  Select any number of
       display items in the usual way and delete them by pressing
       `DDeelleettee'.

       As an alternative, you can also type

         uunnddiissppllaayy _N_U_M_._._.

       at the `((ggddbb))' or `((ddbbxx))' prompt, where _N_U_M_._._. is a space-
       separated list of the displays to delete.  You may need to
       refresh the data window afterwards (see below).

   DDiissaabblliinngg oorr EEnnaabblliinngg DDiissppllaayyss
       Note: DBX does not support display disabling.

       Unlike  a  _d_e_l_e_t_e_d  display  item, a _d_i_s_a_b_l_e_d display item
       remains in the display, but its value is not  shown  until
       it is enabled again.



DDD 1.4d                 12 January 1996                       11





ddd(1)                       DDD 1.4d                      ddd(1)


       Displays  are  enabled  and disabled the same way they are
       deleted,  using  the  `DDiissaabbllee(())'/`EEnnaabbllee(())'  button,  the
       `DDiissaabbllee'/`EEnnaabbllee  DDiissppllaayy'  popup menu item, or the `DDiiss--
       aabbllee'/`EEnnaabbllee' buttons in the Display Editor.

       The corresponding GDB commands are

         ddiissaabbllee ddiissppllaayy _N_U_M_._._.

       and

         eennaabbllee ddiissppllaayy _N_U_M_._._.

       respectively.

   RReeffrreesshhiinngg tthhee DDaattaa WWiinnddooww
       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:

       +o you disabled, enabled or deleted displays items  at  the
         `((ggddbb))' or `((ddbbxx))' prompt,

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

       +o you think it could be useful.

       You can refresh the data window by selecting the  `RReeffrreesshh
       DDiissppllaayyss' item in the `DDaattaa' menu.

       As an alternative, you can press the _r_i_g_h_t _m_o_u_s_e _b_u_t_t_o_n on
       the background of the data window and select the  `RReeffrreesshh
       DDiissppllaayy' item.

       Typing

         ggrraapphh rreeffrreesshh

       at the `((ggddbb))' or `((ddbbxx))' prompt has the same effect.


GGRRAAPPHH EEDDIITTIINNGG
       The  DDD  data  window  offers some basic functionality to
       manipulate the display graph.

   MMoovviinngg DDiissppllaayyss AArroouunndd
       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 _l_e_f_t _m_o_u_s_e  _b_u_t_t_o_n  on
       the  display  title.  Moving the pointer while holding the
       button causes all selected displays to move along with the



DDD 1.4d                 12 January 1996                       12





ddd(1)                       DDD 1.4d                      ddd(1)


       pointer.

       If the data window becomes too small to hold all displays,
       scroll bars are created.  If your DDD is  set  up  to  use
       _p_a_n_n_e_r_s  instead,  a  panner is created in the lower right
       edge.  When the panner is moved around,  the  window  view
       follows  the  position  of  the  panner.  See `CCUUSSTTOOMMIIZZIINNGG
       DDDDDD', 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 SShhiifftt and  an  arrow
       key  moves  displays  by single pixels.  Pressing Ctrl aanndd
       aarrrrooww kkeeyyss mmoovveess ddiissppllaayyss bbyy ggrriidd ppoossiittiioonnss..

   AAlliiggnniinngg DDiissppllaayyss
       You can align all displays on the nearest grid position by
       selecting `AAlliiggnn DDiissppllaayyss' from the `GGrraapphh' menu.  This is
       useful for keeping edges horizontal or vertical.

       You can enforce alignment by selecting `SSnnaapp ttoo  GGrriidd'  in
       the  `DDaattaa  OOppttiioonnss'  menu.  If `SSnnaapp ttoo GGrriidd' is enabled,
       displays can be moved on grid positions only.

   LLaayyoouuttiinngg tthhee DDiissppllaayy GGrraapphh
       You can layout the entire graph as  a  tree  by  selecting
       `LLaayyoouutt GGrraapphh' from the `DDaattaa' menu.

       Layouting  the  graph  may  introduce _e_d_g_e _h_i_n_t_s; that is,
       edges are no more straight lines, but lead to an edge hint
       and  from  there  to their destination.  You can make edge
       hints visible by selecting `SShhooww EEddggee HHiinnttss' in the  `DDaattaa
       OOppttiioonnss'  menu.  Edge hints can be moved around like arbi-
       trary displays.

       To enable a more compact layout, you can set the  `CCoommppaacctt
       LLaayyoouutt'  option in the `DDaattaa OOppttiioonnss' menu.  This realizes
       an alternate layout algorithm, where successors are placed
       next  to  their  parents.   This algorithm is suitable for
       homogeneous data structures only.

       You can enforce layout by setting the  `AAuuttoommaattiicc  LLaayyoouutt'
       option  in the `DDaattaa OOppttiioonnss' menu.  If `AAuuttoommaattiicc LLaayyoouutt'
       is enabled, the graph is layouted after each change.

   RRoottaattiinngg tthhee DDiissppllaayy GGrraapphh
       You can rotate the entire graph clockwise by 90 degrees by
       selecting `RRoottaattee GGrraapphh' from the `DDaattaa' menu.

       If the graph was previously layouted, you may need to lay-
       out it again.  Subsequent layouts will respect the  direc-
       tion of the last rotation.





DDD 1.4d                 12 January 1996                       13





ddd(1)                       DDD 1.4d                      ddd(1)


   PPrriinnttiinngg tthhee DDiissppllaayy GGrraapphh
       DDD  allows  for  printing the graph picture on PostScript
       printers or into files.  This is  useful  for  documenting
       program states.

       To  print  the  graph  on a PostScript printer, select the
       `PPrriinntt GGrraapphh......' item from the  `FFiillee'  menu.   Enter  the
       printing command in the `PPrriinntteerr CCoommmmaanndd' field.  Click on
       the `PPrriinntt' button to start printing.

       To re-print the display graph using the previous settings,
       select the `PPrriinntt AAggaaiinn' item from the `FFiillee' menu.

       As an alternative, you may also print the graph in a file.
       Click on the `FFiillee' button and enter the file name in  the
       `FFiillee  NNaammee' field.  Click on the `PPrriinntt' button to create
       the file.

       When the graph is printed  in  a  file,  two  formats  are
       available:

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

       +o XFIG - suitable for editing, using the XFIG graphic edi-
         tor,  or  for  conversion  into  other formats using the
         TRANSFIG package.


MMAACCHHIINNEE--LLEEVVEELL DDEEBBUUGGGGIINNGG
       Note: Machine-level support is not available with DBX.

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

   EExxaammiinniinngg MMaacchhiinnee CCooddee
       To  enable  machine-level support, select `DDiissppllaayy MMaacchhiinnee
       CCooddee' from  the  `SSoouurrccee  OOppttiioonnss'  menu.   With  `DDiissppllaayy
       MMaacchhiinnee  CCooddee'  enabled, an additional _m_a_c_h_i_n_e _c_o_d_e _w_i_n_d_o_w
       shows up, displaying the machine code of the current func-
       tion.   By  moving the sash at the right of the separating
       line between source and machine code, you can  resize  the
       source and machine code windows.

       The  machine  code  window works very much like the source
       window.  You can set, clear,  and  change  breakpoints  by
       selecting   the   address  and  pressing  a  `BBrreeaakk(())'  or
       `CClleeaarr(())' button; the usual popup menus  are  also  avail-
       able.   Breakpoints and the current execution position are
       displayed simultaneously in both source and machine  code.

       The  `LLooookkuupp(())'  button can be used to look up the machine



DDD 1.4d                 12 January 1996                       14





ddd(1)                       DDD 1.4d                      ddd(1)


       code for a specific function--or the function for  a  spe-
       cific  address.   Just click on the location in one window
       and press `LLooookkuupp(())' to see the corresponding code in  the
       other window.

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

   EExxeeccuuttiioonn
       All execution facilities available in the source code win-
       dow are available in the machine code window as well.  Two
       special facilities are convenient for machine-level debug-
       ging:

       To  execute  just  one  machine  instruction, click on the
       `SStteeppii' button.

       To continue to the next instruction in the  current  func-
       tion,  click  on  the  `NNeexxttii' button.  This is similar to
       `SStteeppii', but any subroutine  calls  are  executed  without
       stopping.

   RReeggiisstteerrss
       DDD  provides a _r_e_g_i_s_t_e_r _w_i_n_d_o_w showing the machine regis-
       ter values after each program stop.  To enable the  regis-
       ter window, select `SShhooww RReeggiisstteerrss' from the `SSttaacckk' menu.

       By selecting one of the registers, its name is  copied  to
       the  argument  field.   You  can use it as value for `DDiiss--
       ppllaayy(())', for instance, to have its value displayed in  the
       data window.


EEDDIITTIINNGG SSOOUURRCCEE CCOODDEE
       In DDD itself, you cannot change the source file currently
       displayed.   DDD  allows  you  to  invoke  a  _t_e_x_t  _e_d_i_t_o_r
       instead.   To  invoke a text editor for the current source
       file, select the `EEddiitt' button  or  the  `EEddiitt  SSoouurrccee......'
       item from the `SSoouurrccee' menu.

       The  editor  command  is  specified  in  the `eeddiittCCoommmmaanndd'
       resource.  By default,  DDD  tries  to  invoke  the  first
       available editor from the following list:

       +o The  editor specified in the `XXEEDDIITTOORR' environment vari-
         able;

       +o The `ggnnuucclliieenntt' program, invoking a separate window from
         a running EEmmaaccss editor;

       +o The  `eemmaaccsscclliieenntt'  program,  invoking a separate window
         from a running EEmmaaccss editor;

       +o A `xxtteerrmm' terminal emulator running the editor specified



DDD 1.4d                 12 January 1996                       15





ddd(1)                       DDD 1.4d                      ddd(1)


         in the `EEDDIITTOORR' environment variable;

       +o A `xxtteerrmm' terminal emulator running the `vvii' 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
       `RReellooaadd SSoouurrccee......' item  from  the  `SSoouurrccee'  menu.   This
       reloads  the  source  code shown from the source file.  As
       DDD automatically reloads the source code if the  debugged
       program  has been recompiled, this should seldom be neces-
       sary.


QQUUIITTTTIINNGG DDDDDD
       To exit DDD, select `EExxiitt' from the `FFiillee' menu.  You  may
       also  type  the  `qquuiitt'  command at the `((ggddbb))' or `((ddbbxx))'
       prompt.  GDB also accepts the `qq' command  or  an  end-of-
       file character (usually CCttrrll++DD).

       An  interrupt  (CCttrrll++CC) does not exit from DDD, but rather
       terminates the action of any GDB or DBX command that is in
       progress and returns to the debugger command level.  It is
       safe to type the interrupt character at any  time  because
       the debugger does not allow it to take effect until a time
       when it is safe.

       You may also interrupt DDD using an interrupt signal (SIG-
       INT)--for instance by pressing CCttrrll++CC in the shell DDD was
       started from, or by using the UNIX `kkiillll'  command.   This
       interrupts  any DDD action; the inferior GDB or DBX debug-
       ger is interrupted as well.  Use this as a last resort  in
       emergencies only--if DDD hangs, for example.


RREEMMOOTTEE DDEEBBUUGGGGIINNGG
       It  is  possible  to  have GDB or DBX run on a remote UNIX
       host.  This is useful when the remote host has a slow net-
       work connection or when DDD is available on the local host
       only.

       In order to run the inferior debugger on  a  remote  host,
       you  need  `rreemmsshh' (called `rrsshh' on BSD systems) access on
       the remote host.

       To run the debugger on a remote host _h_o_s_t_n_a_m_e, invoke  DDD
       as

         dddddd ----hhoosstt _h_o_s_t_n_a_m_e _r_e_m_o_t_e_-_p_r_o_g_r_a_m

       If  your remote  _u_s_e_r_n_a_m_e differs from the local username,
       use



DDD 1.4d                 12 January 1996                       16





ddd(1)                       DDD 1.4d                      ddd(1)


         dddddd ----hhoosstt _h_o_s_t_n_a_m_e ----llooggiinn _u_s_e_r_n_a_m_e _r_e_m_o_t_e_-_p_r_o_g_r_a_m

       instead.

       There are a few _c_a_v_e_a_t_s in remote mode:

       +o The remote debugger  is  started  in  your  remote  home
         directory.   Hence,  you  must  specify an absolute path
         name for _r_e_m_o_t_e_-_p_r_o_g_r_a_m (or a path name relative to your
         remote  home  directory).   Same  applies to remote core
         files.  Also, be sure to specify  a  remote  process  id
         when debugging a running program.

       +o To run the remote program, DDD invokes an `xxtteerrmm' termi-
         nal emulator on the remote  host,  giving  your  current
         `DDIISSPPLLAAYY'  environment  variable  as  address.   If  the
         remote host cannot invoke  `xxtteerrmm',  or  does  not  have
         access   to   your   X   display,  start  DDD  with  the
         `----nnoo--eexxeecc--wwiinnddooww'  option.   The  program  input/output
         will then go through the DDD command window.

       +o 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.

       +o To  help  you find problems due to remote execution, run
         DDD  with  the  `----ttrraaccee--sshheellll--ccoommmmaannddss'  option.   This
         prints  the  shell  commands  issued  by DDD on standard
         error.


RROOOOTT DDEEBBUUGGGGIINNGG
       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  _s_e_t_u_i_d  _r_o_o_t,
       that  is,  having  the  debugger run with root privileges.
       For security reasons, you cannot install DDD as  a  setuid
       program.   Instead,  you  should  invoke  DDD  such that a
       _s_e_t_u_i_d copy of the inferior debugger is used.

       Here is an example.   Have  a  _s_e_t_u_i_d  _r_o_o_t  copy  of  GDB
       installed as `rroooottggddbb'.  Then invoke

         dddddd ----ddeebbuuggggeerr rroooottggddbb

       to debug programs with root privileges.

       Since  a  program like `rroooottggddbb' grants root privileges to
       any invoking user, you should give it very limited access.


IINNTTEEGGRRAATTIINNGG DDDDDD
       You  can run DDD as an inferior debugger in other debugger
       front-ends, combining their special abilities  with  those



DDD 1.4d                 12 January 1996                       17





ddd(1)                       DDD 1.4d                      ddd(1)


       of DDD.


   GGeenneerraall IInnffoorrmmaattiioonn
       To  have  DDD  run as an inferior debugger in other front-
       ends, set up your debugger front-end such that `dddddd ----ttttyy'
       is  invoked instead of GDB resp. DBX.  When DDD is invoked
       using the `----ttttyy' option, it enables  its  _T_T_Y  _i_n_t_e_r_f_a_c_e,
       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  `--ffuullllnnaammee'
       option  to  have  GDB  report  source  code positions, the
       `----ttttyy'  option  is  not  required.   DDD  recognizes  the
       `--ffuullllnnaammee'  option, finds that it has been invoked from a
       debugger  front-end  and  automatically  enables  the  TTY
       interface.

       You  may  also  invoke  `dddddd ----ttttyy' directly, entering DDD
       commands from your TTY, or use DDD as the end of  a  pipe,
       controlled  by  a remote program.  Be aware, however, that
       the TTY interface does not support line editing  and  com-
       mand  completion and that DDD exits as soon as it receives
       a EOF on its standard input.  Also, do not try to run  DDD
       with DDD as inferior debugger.


   UUssiinngg DDDDDD wwiitthh FFSSFF EEmmaaccss
       Use  `MM--xx  ggddbb' or `MM--xx ddbbxx' to start a debugging session.
       At the prompt, enter `dddddd ----ttttyy', followed by  `----ddbbxx'  or
       `----ggddbb',  if  required,  and the name of the program to be
       debugged.  Proceed as usual.


   UUssiinngg DDDDDD wwiitthh XXEEmmaaccss
       Set the variable ggddbb--ccoommmmaanndd--nnaammee to ""dddddd"",  by  inserting
       the following line in your $$HHOOMMEE//..eemmaaccss file or evaluating
       it via EESSCC EESSCC:

         ((sseettqq ggddbb--ccoommmmaanndd--nnaammee ""dddddd""))

       Use `MM--xx ggddbb' to start a debugging  session.   Proceed  as
       usual.


   UUssiinngg DDDDDD wwiitthh XXXXGGDDBB
       Invoke xxxxggddbb as

        xxxxggddbb --ddbb__nnaammee dddddd --ddbb__pprroommpptt ''((ggddbb)) ''






DDD 1.4d                 12 January 1996                       18





ddd(1)                       DDD 1.4d                      ddd(1)


CCUUSSTTOOMMIIZZIINNGG DDDDDD
       You  can set up your personal DDD preferences by using the
       `OOppttiioonnss' menu from the menu bar.   These  options  affect
       your  running  DDD  process  only,  unless  you save these
       options for a later DDD invocation.

   GGeenneerraall OOppttiioonnss
       These items are found in the `OOppttiioonnss' menu:

       If you frequently switch  between  DDD  and  other  multi-
       window  applications,  you  may  like  to  set  the `GGrroouupp
       IIccoonniiffyy' option.  This way, all DDD windows are  iconified
       and deiconified as a group.

       If you want to use TTAABB key completion in all text windows,
       set the `GGlloobbaall TTaabb CCoommpplleettiioonn' option.  This is useful if
       you  have pointer-driven keyboard focus (see below) and no
       special usage for the TTAABB key.

       If you want to run your debugged  process  in  a  separate
       terminal  emulator  window, set the `RRuunn iinn EExxeeccuuttiioonn WWiinn--
       ddooww' option.  This is useful for programs that  have  spe-
       cial  terminal  requirements  not provided by the debugger
       window, as raw keyboard  processing  or  terminal  control
       sequences.

       If  you want to save changed options automatically for the
       next DDD  invocation,  set  the  `SSaavvee  OOppttiioonnss  oonn  EExxiitt'
       option.

       If  you  want to save the command history for the next DDD
       invocation, set the `SSaavvee OOppttiioonnss oonn EExxiitt' option.   Note:
       This  option  is  always set if your GDB is set up to save
       its command history.

   SSoouurrccee OOppttiioonnss
       By default, DDD finds only complete words.  This is conve-
       nient 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 `FFiinndd
       WWoorrddss OOnnllyy' option.

       If you wish to display machine code of selected  funtions,
       set the `DDiissppllaayy MMaacchhiinnee CCooddee' option.  This makes DDD run
       a little slower, so it is disabled by default.

       As of this DDD release, the current execution position and
       breakpoints  are  indicated by symbols (``glyphs'') in the
       source text.  Previous releases  used  special  texts  for
       this  purpose.   If  you wish to disable glyphs, unset the
       `DDiissppllaayy GGllyypphhss' option.  This also makes DDD run slightly
       faster, especially when scrolling.

       By  default,  DDD  caches source files in memory.  This is



DDD 1.4d                 12 January 1996                       19





ddd(1)                       DDD 1.4d                      ddd(1)


       convenient for remote debugging, since remote file  access
       may  be  slow.   If you want to reduce memory usage, unset
       the `CCaacchhee SSoouurrcceess' option.

       By default, DDD caches machine code in  memory.   This  is
       bad for memory usage, but convenient for speed, since dis-
       assembling a function each time it  is  reached  may  take
       time.   If  you  want  to  reduce  memory usage, unset the
       `CCaacchhee MMaacchhiinnee CCooddee' option.

   DDaattaa OOppttiioonnss
       By default, DDD displays a grid  in  the  data  window  to
       facilitate display alignment.  If you prefer not to have a
       grid, unset the `SShhooww GGrriidd' option.

       Layouting the display graph may introduce _e_d_g_e _h_i_n_t_s; 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  `SShhooww  EEddggee
       HHiinnttss' option.

       To  enforce  alignment,  you  can  set  the `SSnnaapp ttoo GGrriidd'
       option.  If `SSnnaapp ttoo GGrriidd' is  enabled,  displays  can  be
       moved on grid positions only.

       To  enable a more compact layout, you can set the `CCoommppaacctt
       LLaayyoouutt' 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 `AAuuttoommaattiicc LLaayyoouutt'
       option.  If `AAuuttoommaattiicc LLaayyoouutt' is enabled,  the  graph  is
       layouted after each change.

   SSttaarrttuupp OOppttiioonnss
       By  default, DDD uses three separate windows for commands,
       source, and data.  To attach the source and  data  windows
       to the command window, creating one single big DDD window,
       set the `WWiinnddoowwss' option to  `OOnnee  SSiinnggllee  WWiinnddooww'.   This
       change  takes only effect after you have saved options and
       restarted  DDD.   See  also  the  `----aattttaacchh--wwiinnddoowwss'   and
       `----sseeppaarraattee--wwiinnddoowwss' options, below.

       By  default,  DDD  directs keyboard input to the item your
       mouse pointer points at.  If you  prefer  a  click-to-type
       keyboard  focus  (that  is,  click  on  an item to make it
       accept keyboard input), set the `KKeeyybbooaarrdd FFooccuuss' option on
       `CClliicckk ttoo ttyyppee'.

       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



DDD 1.4d                 12 January 1996                       20





ddd(1)                       DDD 1.4d                      ddd(1)


       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 `DDaattaa
       SSccrroolllliinngg' option to `PPaannnneerr'.   This  change  takes  only
       effect  after  you  have  saved options and restarted DDD.
       See  also  the  `----ppaannnneedd--ggrraapphh'  and   `----ssccrroolllleedd--ggrraapphh'
       options, below.

       By  default,  DDD  runs with GDB as inferior debugger.  To
       change this default, set the  `DDeebbuuggggeerr  TTyyppee'  option  to
       another debugger.  This change takes only effect after you
       have saved  options  and  restarted  DDD.   See  also  the
       `----ggddbb' and `----ddbbxx' options, below.

   SSaavviinngg OOppttiioonnss
       You  can  save  the  current  option settings by selecting
       `SSaavvee OOppttiioonnss' in the `OOppttiioonnss' menu.  Options  are  saved
       in a file named `..ddddddiinniitt' in your home directory.

   OOtthheerr CCuussttoommiizzaattiioonnss
       Other  personal  DDD  resources  can  also  be set in your
       `..ddddddiinniitt' file.  To find out which resources  are  avail-
       able,  and  how they are set by default, look at the `DDdddd'
       application defaults file, which is shipped with  the  DDD
       source.   For  individual customization, copy the lines of
       resources you want to change into your `..ddddddiinniitt' file and
       modify them as you like.


EEXXTTEENNDDIINNGG DDDDDD
       If you have any contributions to be incorporated into DDD,
       please send them to  `dddddd@@iippss..ccss..ttuu--bbss..ddee'.   For  sugges-
       tions  on  what  might be done, see the file `PPRROOJJEECCTTSS' in
       the DDD distribution.

       If you wish something done in DDD, but cannot do it  your-
       self,  you  can  _f_i_n_a_n_c_e  specific  DDD  extensions.   For
       details, contact  `dddddd@@iippss..ccss..ttuu--bbss..ddee';  direct  mail  is
       also welcome.

       Some  of  the  people offering DDD support may also accept
       offers to extend DDD.  For a list of people  offering  DDD
       support, see the file `SSEERRVVIICCEE' in the DDD distribution.


IIFF YYOOUU LLIIKKEE DDDDDD......
       If  you appreciate this software, or have any suggestions,
       please send us a picture postcard.  Our address is:  Tech-
       nische Universitaet Braunschweig
       Institut fuer Programmiersprachen und Informationssysteme
       Abteilung Softwaretechnologie
       Gaussstrasse 17
       D-38092 Braunschweig



DDD 1.4d                 12 January 1996                       21





ddd(1)                       DDD 1.4d                      ddd(1)


       GERMANY
       You  may also leave a message in the DDD guestbook (acces-
       sible   via   the   DDD   WWW   page,   `hhttttpp::////wwwwww..ccss..ttuu--
       bbss..ddee//ssoofftteecchh//dddddd//')


OOPPTTIIOONNSS
       You  can use the following options when starting DDD.  All
       options may be abbreviated, as long as they are  unambigu-
       ous;  single  dashes may also be used.  Options not listed
       here are passed to the inferior debugger.

       ----aattttaacchh--wwiinnddoowwss
              Attach the source and data windows to  the  command
              window,  creating  one single big DDD window.  This
              gives the good ole `xxxxggddbb' or `xxddbbxx' feeling.

       ----aattttaacchh--ssoouurrccee--wwiinnddooww
              Attaches only the source window to the command win-
              dow.

       ----aattttaacchh--ddaattaa--wwiinnddooww
              Attaches only the source window to the command win-
              dow.

       ----ccoonnffiigguurraattiioonn
              Show the DDD configuration settings and exit.

       ----cchheecckk--ccoonnffiigguurraattiioonn
              Check the DDD environment  (in  particular,  the  X
              configuration),  report any possible problem causes
              and exit.

       ----ddbbxx  Run the DBX debugger as inferior debugger.

       ----ddeebbuuggggeerr _n_a_m_e
              Invoke the inferior debugger _n_a_m_e.  This is  useful
              if you have several debugger versions around, or if
              GDB and DBX cannot be invoked as  `ggddbb'  or  `ddbbxx',
              respectively.

       ----eexxeecc--wwiinnddooww
              Run  the  debugged  program  in a specially created
              execution window.  This is useful for programs that
              have  special terminal requirements not provided by
              the debugger window, as raw keyboard processing  or
              terminal control sequences.

       ----ffuullllnnaammee
              Enable  TTY  interface,  taking additional debugger
              commands from standard input and forwarding  debug-
              ger  output  on standard output.  Current positions
              are issued in GDB `--ffuullllnnaammee' format  suitable  for
              debugger front-ends.



DDD 1.4d                 12 January 1996                       22





ddd(1)                       DDD 1.4d                      ddd(1)


       ----ggddbb  Run the GDB debugger as inferior debugger.

       ----hheellpp Give  a  list  of  frequently  used  options.  Show
              options of the inferior debugger as well.

       ----hhoosstt _h_o_s_t_n_a_m_e
              Run the inferior debugger on the remote host  _h_o_s_t_-
              _n_a_m_e.  See RREEMMOOTTEE MMOODDEE, above.

       ----llooggiinn _u_s_e_r_n_a_m_e
              Use _u_s_e_r_n_a_m_e as remote user name.  See RREEMMOOTTEE MMOODDEE,
              above.

       ----mmaannuuaall
              Show this manual page and exit.

       ----nnoo--eexxeecc--wwiinnddooww
              Do not run the debugged program in a specially cre-
              ated  execution  window;  use  the  command  window
              instead.  Useful for programs that have little ter-
              minal input/output, or for remote debugging.

       ----nnww   Do not use the X window interface.  Start the infe-
              rior debugger on the local host.

       ----ppaannnneedd--ggrraapphh
              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  wid-
              gets.  See also ----ssccrroolllleedd--ggrraapphh, below.

       ----sseeppaarraattee--wwiinnddoowwss
              Separate  the  command,  source  and  data windows.
              This is  the  default.   See  also  the  `----aattttaacchh'
              options, above.

       ----ssccrroolllleedd--ggrraapphh
              Use  Motif  scroll  bars to scroll the data window.
              This is the default  in  most  DDD  configurations.
              See also ----ppaannnneedd--ggrraapphh, above.

       ----ssyynncchhrroonnoouuss--ddeebbuuggggeerr
              Do not process X events while the debugger is busy.
              This may result in slightly better  performance  on
              single-processor systems.

       ----ttrraaccee--ddiiaalloogg
              Show  the  interaction between DDD and the inferior
              debugger on standard error.   This  is  useful  for
              debugging DDD.





DDD 1.4d                 12 January 1996                       23





ddd(1)                       DDD 1.4d                      ddd(1)


       ----ttrraaccee--sshheellll
              Show  the  shell commands issued by DDD on standard
              error.  This is useful for debugging DDD.

       ----ttrraaccee
              Show both interaction and shell commands.

       ----ttttyy  Enable TTY interface,  taking  additional  debugger
              commands  from standard input and forwarding debug-
              ger output on standard output.   Current  positions
              are issued in a format readable for humans.

       ----vveerrssiioonn
              Show the DDD version and exit.

       ----vvssll--lliibbrraarryy _l_i_b_r_a_r_y
              Load  the  VSL library _l_i_b_r_a_r_y instead of using the
              DDD built-in library.  This is useful for customiz-
              ing display shapes and fonts.

       ----vvssll--ppaatthh _p_a_t_h
              Search  VSL  libraries  in  _p_a_t_h (a colon-separated
              directory list).

       ----vvssll--hheellpp
              Show a list of further options controlling the  VSL
              interpreter.  These options are intended for debug-
              ging purposes and are  subject  to  change  without
              further notice.


RREESSOOUURRCCEESS
       See  the `DDdddd' application defaults file for full informa-
       tion about customizing DDD.  The `DDdddd' file comes with the
       DDD distribution.


FFIILLEESS
       $$HHOOMMEE//..ddddddiinniitt      Individual  DDD  resource  file.   DDD
                           options are saved here.
       $$HHOOMMEE//..ggddbbiinniitt      GDB initialization file.
       $$HHOOMMEE//..ddbbxxiinniitt      DBX initialization file.


SSEEEE AALLSSOO
       XX(1), ggddbb(1), ddbbxx(1), rreemmsshh(1), rrsshh(1)

       `ggddbb' entry in iinnffoo..

       _U_s_i_n_g _G_D_B_: _A _G_u_i_d_e _t_o _t_h_e _G_N_U  _S_o_u_r_c_e_-_L_e_v_e_l  _D_e_b_u_g_g_e_r,  by
       Richard M. Stallman and Roland H. Pesch.

       _D_D_D_-_-_A  _F_r_e_e  _G_r_a_p_h_i_c_a_l  _F_r_o_n_t_-_E_n_d  _f_o_r _U_N_I_X _D_e_b_u_g_g_e_r_s, by
       Andreas Zeller and Dorothea Luetkehaus,  Computer  Science



DDD 1.4d                 12 January 1996                       24





ddd(1)                       DDD 1.4d                      ddd(1)


       Report  95-07, Technische Universitaet Braunschweig, 1995.

       _D_D_D _-_- _e_i_n _D_e_b_u_g_g_e_r _m_i_t _g_r_a_p_h_i_s_c_h_e_r  _D_a_t_e_n_d_a_r_s_t_e_l_l_u_n_g,  by
       Dorothea  Luetkehaus, Diploma Thesis, Technische Universi-
       taet Braunschweig, 1994.

       The DDD _F_T_P _s_i_t_e,

         ffttpp::////ffttpp..iippss..ccss..ttuu--bbss..ddee//ppuubb//llooccaall//ssoofftteecchh//dddddd//


       The DDD _W_o_r_l_d_-_W_i_d_e_-_W_e_b _p_a_g_e,

         hhttttpp::////wwwwww..ccss..ttuu--bbss..ddee//ssoofftteecchh//dddddd//


       The DDD _M_a_i_l_i_n_g _L_i_s_t,

          dddddd--uusseerrss@@iippss..ccss..ttuu--bbss..ddee

       For more information on this list, send a mail to

          dddddd--uusseerrss--rreeqquueesstt@@iippss..ccss..ttuu--bbss..ddee



LLIIMMIITTAATTIIOONNSS
   LLiimmiittaattiioonnss uussiinngg GGDDBB
       Some GDB settings are essential for DDD to work correctly.
       These settings with their correct values are:

         sseett hheeiigghhtt 00
         sseett wwiiddtthh 00
         sseett pprriinntt pprreettttyy
         sseett pprriinntt rreeppeeaattss 00
         sseett vveerrbboossee ooffff
         sseett pprroommpptt ((ggddbb))

       DDD sets these values automatically when invoking GDB.

       If  these  values  are changed, there may be some malfunc-
       tions, especially in the data display.   If  you  want  to
       display  C  strings  (i.e.,  `cchhaarr **'-fields), it might be
       useful to change  the  settings  of  `pprriinntt  rreeppeeaattss'  and
       `pprriinntt  eelleemmeennttss'.  But to recognize array structures cor-
       rectly, you should have `pprriinntt rreeppeeaattss' set to  0.   Also,
       do  not change the setting of `pprriinntt eelleemmeennttss' 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 `ddiissppllaayy //xx $$ppcc' command
       to ensure the program counter value is  updated  correctly
       at   each  stop.   You  may  also  enter  the  command  in
       $$HHOOMMEE//..ggddbbiinniitt or (better yet) upgrade to the most  recent



DDD 1.4d                 12 January 1996                       25





ddd(1)                       DDD 1.4d                      ddd(1)


       GDB version.


   LLiimmiittaattiioonnss uussiinngg DDBBXX
       When  used  for debugging Modula-2 or Pascal programs, DDD
       always  numerates  array  elements  starting  with   zero,
       instead  of using correct array subscripts.  This shall be
       fixed in a future DDD release.

       Using DBX 3.x or later as inferior debugger, DDD strips C-
       style  and C++-style comments from the DBX output in order
       to operate properly.  This also affects the output of  the
       debugged  program  when sent to the command window.  Using
       the separate execution window avoids these problems.


   GGeenneerraall LLiimmiittaattiioonnss
       If command output is sent to the  command  window,  it  is
       impossible  for  DDD  to distinguish between the output of
       the debugged program and the output of the inferior debug-
       ger.  For instance, if your program output includes debug-
       ger prompts, DDD will become confused.  Using the separate
       execution window avoids these problems.

       Paper sizes larger than 2,147,483,648pt (757km, 470 miles)
       can not be handled.


RREEPPOORRTTIINNGG BBUUGGSS
       If you find a bug in DDD, please send us a bug report.  We
       will  either  attempt  to  fix the bug--or include the bug
       description in the DDD `BBUUGGSS' file, such that  others  can
       attempt  to  fix it.  (Instead of sending bug reports, you
       may also send _f_i_x_e_s; DDD is an excellent tool  for  debug-
       ging itself :-)

   WWhheerree ttoo SSeenndd BBuugg RReeppoorrttss
       We  recommend  that you send bug reports for DDD via elec-
       tronic mail to

         dddddd--bbuuggss@@iippss..ccss..ttuu--bbss..ddee

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

         Technische Universitaet Braunschweig
         Institut fuer Programmiersprachen  und  Informationssys-
       teme
         Abteilung Softwaretechnologie
         DDD-Bugs
         Gaussstrasse 17
         D-38092 Braunschweig
         GERMANY





DDD 1.4d                 12 January 1996                       26





ddd(1)                       DDD 1.4d                      ddd(1)


   IIss iitt aa DDDDDD BBuugg??
       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 installa-
       tions, for instance, or bugs in  the  X  server  or  Motif
       itself.  Running DDD as


         dddddd ----cchheecckk--ccoonnffiigguurraattiioonn

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

       Another potential cause of problems is the inferior GDB or
       DBX  debugger;  although unlikely, they may have bugs.  To
       find out whether a bug was caused by GDB or DBX,  run  DDD
       as

         dddddd ----ttrraaccee--ddiiaalloogg

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

   HHooww ttoo RReeppoorrtt BBuuggss
       Here are some guidelines for bug reports:

       +o The fundamental principle of reporting bugs usefully  is
         this: _r_e_p_o_r_t _a_l_l _t_h_e _f_a_c_t_s.  If you are not sure whether
         to state a fact or leave it out, state it!

       +o 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.

       +o 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.

       +o 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  appropri-
         ate maintainer.

       +o 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.






DDD 1.4d                 12 January 1996                       27





ddd(1)                       DDD 1.4d                      ddd(1)


   WWhhaatt ttoo IInncclluuddee iinn aa BBuugg RReeppoorrtt
       To enable us to fix a DDD bug, you _m_u_s_t include  the  fol-
       lowing information:

       +o Your DDD configuration.  Invoke DDD as

           dddddd ----ccoonnffiigguurraattiioonn

         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.

       +o The debugger  you  are  using  and  its  version  (e.g.,
         `ggddbb--44..1144' or `ddbbxx aass sshhiippppeedd wwiitthh SSoollaarriiss 22..44').

       +o The  compiler  you  used  to compile DDD and its version
         (e.g., `ggcccc--22..66..33').

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

       +o If possible, include a _d_i_a_l_o_g _t_r_a_c_e showing the interac-
         tion between DDD and the inferior debugger.  Such a dia-
         log  trace is created by invoking DDD with the `----ttrraaccee'
         option.  Include all trace output from the  DDD  invoca-
         tion up to the first bug occurrence.

       +o If  you  wish to suggest changes to the DDD source, send
         us context diffs.  If you even discuss something in  the
         DDD  source,  refer to it by context, _n_e_v_e_r by line num-
         ber.

       Be sure to include this information in  _e_v_e_r_y  single  bug
       report.


HHIISSTTOORRYY
       The history of DDD is a story of code recycling.  The old-
       est parts of DDD were written in 1990, when _A_n_d_r_e_a_s _Z_e_l_l_e_r
       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 edi-
       tor (based on VSL and the BOX  libraries)  and  facilities
       for  inter-process  knowledge  exchange.   Based  on these
       tools, _D_o_r_o_t_h_e_a _L_u_e_t_k_e_h_a_u_s realized  DDD  as  her  Diploma



DDD 1.4d                 12 January 1996                       28





ddd(1)                       DDD 1.4d                      ddd(1)


       Thesis, 1994.

       The  original  DDD had no source window; this was added by
       Dorothea during the winter of  1994/1995.   In  the  first
       quarter  of 1995, finally, Andreas completed DDD by adding
       command and execution  windows,  extensions  for  DBX  and
       remote debugging as well as configuration support for sev-
       eral architectures.  Since then,  many  people  have  con-
       tributed  to  the  success of DDD; see the file `CCOONNTTRRIIBBUU--
       TTOORRSS' in the DDD distribution for details.

       Major DDD events:
       April, 1995         First DDD beta release (DDD 0.9)
       May, 1995           First public DDD release (DDD 1.0)
       August, 1995        Code adapted to ANSI/ISO C++  standard
                           (DDD 1.3)
       December, 1995      Machine-level debugging, glyphs, EMACS
                           integration (DDD 1.4)


PPRRIINNTTIINNGG TTHHIISS MMAANNUUAALL
       Invoke DDD with the `----mmaannuuaall' option to show this  manual
       page on standard output.  This text output is suitable for
       installation    as    formatted    manual     page     (as
       `//uussrr//llooccaall//mmaann//ccaatt11//dddddd..11' or similar) on UNIX systems.

       A PostScript copy of this manual page, suitable for print-
       ing, is included in the DDD source distribution and avail-
       able separately as


         ffttpp::////ffttpp..iippss..ccss..ttuu--bbss..ddee//ppuubb//llooccaall//ssoofftteecchh//dddddd//ddoocc//dddddd--
       mmaann..ppss..ggzz


       A ROFF copy of this manual page, suitable for installation
       as     manual     page     on     UNIX     systems     (as
       `//uussrr//llooccaall//mmaann//mmaann11//dddddd..11' or similar),  is  included  in
       the DDD source distribution.


CCOOPPYYIINNGG
       DDD  is  Copyright  (C) 1995, 1996 Technische Universitaet
       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 verba-
       tim copying, provided that the  entire  resulting  derived
       work is distributed under the terms of a permission notice
       identical to this one.



DDD 1.4d                 12 January 1996                       29





ddd(1)                       DDD 1.4d                      ddd(1)


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



















































DDD 1.4d                 12 January 1996                       30


