PC World Komputer 1999 March

home *** CD-ROM | disk | FTP | other *** search

/ PC World Komputer 1999 March / PCWK3A99.iso / Linux / DDD331 / DDD-3_1_.000 / DDD-3_1_ / ddd-3.1.1 / ddd / ddd.man.txt < prev next >

Wrap

Text File | 1998-12-06 | 320.2 KB | 7,393 lines

ddd(1) ddd(1) NNAAMMEE ddd, xddd - the data display debugger SSYYNNOOPPSSIISS dddddd [----ggddbb] [----ddbbxx] [----xxddbb] [----jjddbb] [----ppyyddbb] [----ppeerrll] [----ddeebbuuggggeerr _n_a_m_e] [----[rr]hhoosstt [_u_s_e_r_n_a_m_e@@]_h_o_s_t_n_a_m_e]] [----hheellpp] [----ttrraaccee] [----vveerrssiioonn] [----ccoonnffiigguurraattiioonn] [_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 dddddd _p_r_o_g_r_a_m DDEESSCCRRIIPPTTIIOONN 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 comfortable _g_r_a_p_h_i_c_a_l _u_s_e_r _i_n_t_e_r_f_a_c_e around an inferior GDB, DBX, XDB, JDB, Python debugger, or Perl debugger. IINNVVOOKKIINNGG DDDDDD 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: dddddd pprrooggrraamm You can also start with both an executable program and a core file specified: dddddd pprrooggrraamm ccoorree You can, instead, specify a process ID as a second DDD 3.1.1 1998-12-06 1 ddd(1) ddd(1) argument, if you want to debug a running process: dddddd pprrooggrraamm 11223344 would attach DDD to process 11223344 (unless you also have a file named `11223344'; DDD does check for a core file first). By default, DDD determines the inferior debugger automati- cally. Use dddddd ----ggddbb _p_r_o_g_r_a_m or dddddd ----ddbbxx _p_r_o_g_r_a_m or dddddd ----xxddbb _p_r_o_g_r_a_m or dddddd ----jjddbb _c_l_a_s_s or dddddd ----ppyyddbb _m_o_d_u_l_e or dddddd ----ppeerrll _p_r_o_g_r_a_m_f_i_l_e to run GDB, DBX, XDB, JDB, PYDB or Perl as inferior debug- ger. To learn more about DDD options, run dddddd ----hheellpp to get a list of frequently used options, or see the `OOPPTTIIOONNSS' section, below. TTHHEE DDDDDD WWIINNDDOOWWSS TThhee DDDDDD MMaaiinn WWiinnddoowwss DDD is composed of three main windows: +o The _D_a_t_a _W_i_n_d_o_w shows the current data of the debugged program. +o The _S_o_u_r_c_e _W_i_n_d_o_w shows the current source code of the debugged program. +o The _D_e_b_u_g_g_e_r _C_o_n_s_o_l_e accepts debugger commands and shows debugger messages. DDD 3.1.1 1998-12-06 2 ddd(1) ddd(1) By default, DDD places these main windows stacked into one single top-level window, but DDD can also be configured to treat each one separately. Besides these main windows, there are some other optional windows: +o The _C_o_m_m_a_n_d _T_o_o_l offers buttons for frequently used com- mands. It is usually placed on the source window. +o The _M_a_c_h_i_n_e _C_o_d_e _W_i_n_d_o_w shows the current machine code. It is usually placed beneath the current source. +o The _E_x_e_c_u_t_i_o_n _W_i_n_d_o_w shows the input and output of the debugged program. DDD also has several temporary _d_i_a_l_o_g_s for showing and entering additional information. UUssiinngg tthhee CCoommmmaanndd TTooooll The command tool is a small window containing frequently used DDD commands. It can be moved around on top of the DDD windows, but it can also be placed besides them. Whenever you save DDD state, DDD also saves the distance between command tool and source window, such that you can select your own individual command tool placement. To move the command tool to its saved position, use `VViieeww-->>CCoommmmaanndd TTooooll'. By default, the command tool _s_t_i_c_k_s to the DDD source win- dow: Whenever you move the DDD source window, the command tool follows such that the distance between source window and command tool remains the same. By default, the com- mand tool is also _a_u_t_o_-_r_a_i_s_e_d, such that it stays on top of other DDD windows. The command tool can be configured to appear as a command tool bar above the source window; see `EEddiitt-->>PPrreeffeerreenncceess-->>SSoouurrccee-->>TTooooll BBuuttttoonnss LLooccaattiioonn' for details. UUssiinngg tthhee TTooooll BBaarr Some DDD commands require an _a_r_g_u_m_e_n_t. This argument is specified in the _a_r_g_u_m_e_n_t _f_i_e_l_d, labeled `(())::'. Basi- cally, there are four ways to set arguments: +o You can _k_e_y _i_n the argument manually. +o You can _p_a_s_t_e the current selection into the argument field (typically using _m_o_u_s_e _b_u_t_t_o_n _2). To clear old contents beforehand, click on the `(())::' label. DDD 3.1.1 1998-12-06 3 ddd(1) ddd(1) +o You can _s_e_l_e_c_t _a_n _i_t_e_m from the source and data windows. This will automatically copy the item to the argument field. +o You can select a _p_r_e_v_i_o_u_s_l_y _u_s_e_d _a_r_g_u_m_e_n_t from the drop- down menu at the right of the argument field. Using GDB and Perl, the argument field provides a comple- tion mechanism. You can enter the first few characters of an item an press the TTAABB key to complete it. Pressing TTAABB again shows alternative completions. After having entered an argument, you can select one of the buttons on the right. Most of these buttons also have menus associated with them; this is indicated by a small arrow in the upper right corner. Pressing and holding _m_o_u_s_e _b_u_t_t_o_n _1 on such a button will pop up a menu with further operations. GGEETTTTIINNGG HHEELLPP DDD has an extensive on-line help system. Here's how to get help while working with DDD. BBuuttttoonn TTiippss You can get a short help text on most DDD buttons by sim- ply moving the mouse pointer on it and leave it there. After a second, a small window (called _b_u_t_t_o_n _t_i_p) 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. TThhee SSttaattuuss LLiinnee The status line also displays information about the cur- rently selected item. By clicking on the status line, you can redisplay the most recent messages. CCoonntteexxtt--SSeennssiittiivvee HHeellpp You can get detailed help on any visible DDD item. Just point on the item you want help and press the `FF11' key. This pops up a detailed help text. The DDD dialogs all contain `HHeellpp' buttons that give detailed information about the dialog. HHeellpp oonn DDeebbuuggggeerr CCoommmmaannddss You can get help on debugger commands by entering `hheellpp' at the debugger prompt. See `EEnntteerriinngg CCoommmmaannddss', below, for details on entering commands. AArree YYoouu SSttuucckk?? If you are stuck, try `HHeellpp-->>WWhhaatt NNooww??' (the `WWhhaatt NNooww' DDD 3.1.1 1998-12-06 4 ddd(1) ddd(1) item in the `HHeellpp' menu) or press CCttrrll++FF11. Depending on the current state, DDD will give you some hints on what you can do next. UUnnddooiinngg CCoommmmaannddss And if, after all, you made a mistake, don't worry. Almost every DDD command can be undone, using `EEddiitt-->>UUnnddoo' or the `UUnnddoo' button on the command tool. Likewise, `EEddiitt-->>RReeddoo' repeats the command most recently undone. OOPPEENNIINNGG FFIILLEESS If you did not invoke DDD specifying a program to be debugged, you can use the `FFiillee' menu to open programs, core dumps and sources. To open a program to be debugged, select `FFiillee-->>OOppeenn PPrroo-- ggrraamm'. In JDB, select `FFiillee-->>OOppeenn CCllaassss' instead. This gives you a list of available classes to choose from. To re-open a recently debugged program or class, select `FFiillee-->>OOppeenn RReecceenntt' and choose a program or class from the list. Note: With XDB and some DBX versions, the debugged program must be specified upon invocation and cannot be changed at run time. To open a core dump for the program, select `FFiillee-->>OOppeenn CCoorree DDuummpp'. Before `OOppeenn CCoorree DDuummpp', you should first use `FFiillee-->>OOppeenn PPrrooggrraamm' to specify the program that generated the core dump and to load its symbol table. To open a source file of the debugged program, select `FFiillee-->>OOppeenn SSoouurrccee'. +o Using GDB, this gives you a list of the sources used for compiling your program. +o Using other inferior debuggers, this gives you a list of accessible source files, which may or may not be related to your program. LLOOOOKKIINNGG UUPP IITTEEMMSS As soon as the source of the debugged program is avail- able, 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 `EEddiitt-->>GGDDBB SSeett-- ttiinnggss' 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. DDD 3.1.1 1998-12-06 5 ddd(1) ddd(1) LLooookkiinngg uupp DDeeffiinniittiioonnss If you wish to lookup a specific function or variable def- inition whose name is visible in the source text, click with _m_o_u_s_e _b_u_t_t_o_n _1 on the function or variable name. The name is copied to the argument field. Alter the name if desired and click on the `LLooookkuupp (())' button to find its definition. As a faster alternative, you can simply press _m_o_u_s_e _b_u_t_t_o_n _3 on the function name and select the `LLooookkuupp' item from the source popup menu. As an even faster alternative, you can also double-click on a function call (an identifier followed by a `((' char- acter) to lookup the function definition. TTeexxttuuaall SSeeaarrcchh If the item you wish to search is visible in the source text, click with _m_o_u_s_e _b_u_t_t_o_n _1 on it. The identifier is copied to the argument field. Click on the `FFiinndd>>>> (())' button to find following occurrences and on the `FFiinndd<<<< (())' button to find previous occurrences. As an alternative, you can enter the item in the argument field and click on one of the `FFiinndd' buttons. By default, DDD finds only complete words. To search for arbitrary substrings, change the value of the `SSoouurrccee-->>FFiinndd WWoorrddss OOnnllyy' option. LLooookkiinngg uupp PPrreevviioouuss LLooccaattiioonnss After looking up a location, use `EEddiitt-->>UUnnddoo' (or the `UUnnddoo' button on the command tool) to go back to the orig- inal locations. `EEddiitt-->>RReeddoo' brings you back again to the location you looked for. BBRREEAAKKPPOOIINNTTSS You can make the program stop at certain _b_r_e_a_k_p_o_i_n_t_s and trace its execution. SSeettttiinngg BBrreeaakkppooiinnttss bbyy LLooccaattiioonn If the source line is visible, click with _m_o_u_s_e _b_u_t_t_o_n _1 on the left of the source line and then on the `BBrreeaakk aatt (())' button. As a faster alternative, you can simply press _m_o_u_s_e _b_u_t_t_o_n _3 on the left of the source line and select the `SSeett BBrreeaakkppooiinntt' item from the line popup menu. As an even faster alternative, you can simply double-click on the left of the source line to set a breakpoint. DDD 3.1.1 1998-12-06 6 ddd(1) ddd(1) As yet another alternative, you can select `SSoouurrccee-->>EEddiitt BBrreeaakkppooiinnttss'. Click on the `BBrreeaakk' button and enter the location. (If you find this number of alternatives confusing, be aware that DDD users fall into three categories, which must all be supported. _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 _u_s_e_r_s prefer the command line interface.) Breakpoints are indicated by a plain stop sign, or as `##_n##', where _n is the breakpoint number. A greyed out stop sign (or `___n__') indicates a disabled breakpoint. A stop sign with a question mark (or `??_n??') indicates a con- ditional breakpoint or a breakpoint with an ignore count set. If you set a breakpoint by mistake, use `EEddiitt-->>UUnnddoo' to delete it again. Note: We have received reports that some Motif versions fail to display stop signs correctly. If this happens, try writing in your `$$HHOOMMEE//..dddddd//iinniitt' file: DDdddd**ccaacchheeGGllyypphhIImmaaggeess:: ooffff and restart DDD. See also the `ccaacchheeGGllyypphhIImmaaggeess' resource in the `RREESSOOUURRCCEESS' section, below. SSeettttiinngg BBrreeaakkppooiinnttss bbyy NNaammee If the function name is visible, click with _m_o_u_s_e _b_u_t_t_o_n _1 on the function name. The function name is copied to the argument field. Click on the `BBrreeaakk aatt (())' button to set a breakpoint there. As a shorter alternative, you can simply press _m_o_u_s_e _b_u_t_- _t_o_n _3 on the function name and select the `bbrreeaakk' item from the popup menu. As yet another alternative, you can click on `NNeeww' from the Breakpoint editor (invoked through `SSoouurrccee-->>EEddiitt BBrreeaakkppooiinnttss') and enter the function name. SSeettttiinngg RReeggeexxpp BBrreeaakkppooiinnttss Using GDB, you can also set a breakpoint on all functions that match a given string. `BBrreeaakk aatt (())-->>SSeett BBrreeaakkppooiinnttss aatt RReeggeexxpp (())' sets a breakpoint on all functions whose name matches the _r_e_g_u_l_a_r _e_x_p_r_e_s_s_i_o_n given in `(())'. Here are some examples: +o To set a breakpoint on every function that starts with `XXmm', set `(())' to `^^XXmm'. DDD 3.1.1 1998-12-06 7 ddd(1) ddd(1) +o To set a breakpoint on every member of class `DDaattee', set `(())' to `^^DDaattee::::'. +o To set a breakpoint on every function whose name con- tains `__ffuunn', set `(())' to `__ffuunn'. +o To set a breakpoint on every function that ends in `__tteesstt', set `(())' to `__tteesstt$$'. Once these multiple breakpoints are set, they are treated just like the breakpoints set with the `BBrreeaakk aatt (())' but- ton. You can delete them, disable them, or make them con- ditional the same way as any other breakpoint. Use `SSoouurrccee-->>EEddiitt BBrreeaakkppooiinnttss' to view and edit the list of breakpoints. DDiissaabblliinngg BBrreeaakkppooiinnttss To temporarily disable a breakpoint, press _m_o_u_s_e _b_u_t_t_o_n _3 on the breakpoint symbol and select the `DDiissaabbllee BBrreeaakk-- ppooiinntt' item from the breakpoint popup menu. To enable it again, select `EEnnaabbllee BBrreeaakkppooiinntt'. As an alternative, you can select the breakpoint and click on `DDiissaabbllee' or `EEnnaabbllee' in the Breakpoint editor (invoked through `SSoouurrccee-->>EEddiitt BBrreeaakkppooiinnttss'. Disabled breakpoints are indicated by a grey stop sign, or `___n__', where _n is the breakpoint number. The `DDiissaabbllee BBrreeaakkppooiinntt' item is also accessible via the `CClleeaarr aatt (())' button. Just press and hold _m_o_u_s_e _b_u_t_t_o_n _1 on the button to get a popup menu. Note: JDB does not support breakpoint disabling. TTeemmppoorraarryy BBrreeaakkppooiinnttss 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 _m_o_u_s_e _b_u_t_t_o_n _3 on the left of the source line and select the `SSeett TTeemmppoorraarryy BBrreeaakkppooiinntt' item from the popup menu. As a faster alternative, you can simply double-click on the left of the source line while holding CCttrrll. 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 `CCoonnttiinnuuee UUnnttiill HHeerree' item from the popup menu sets a temporary breakpoint on the left of the source line and immediately continues execution. Execution stops when the temporary breakpoint is reached. DDD 3.1.1 1998-12-06 8 ddd(1) ddd(1) The `SSeett TTeemmppoorraarryy BBrreeaakkppooiinntt' and `CCoonnttiinnuuee UUnnttiill HHeerree' items are also accessible via the `BBrreeaakk aatt (())' button. Just press and hold _m_o_u_s_e _b_u_t_t_o_n _1 on the button to get a popup menu. Note: JDB does not support temporary breakpoints. DDeelleettiinngg BBrreeaakkppooiinnttss If the breakpoint is visible, click with _m_o_u_s_e _b_u_t_t_o_n _1 on the breakpoint. The breakpoint location is copied to the argument field. Click on the `CClleeaarr aatt (())' button to delete all breakpoints there. If the function name is visible, click with _m_o_u_s_e _b_u_t_t_o_n _1 on the function name. The function name is copied to the argument field. Click on the `CClleeaarr aatt (())' button to set a breakpoint there. As a faster alternative, you can simply press _m_o_u_s_e _b_u_t_t_o_n _3 on the breakpoint and select the `DDeelleettee BBrreeaakkppooiinntt' item from the popup menu. As yet another alternative, you can select the breakpoint and click on `DDeelleettee' in the Breakpoint editor (invoked through `SSoouurrccee-->>EEddiitt BBrreeaakkppooiinnttss'). As an even faster alternative, you can simply double-click on the breakpoint while holding CCttrrll. EEddiittiinngg BBrreeaakkppooiinntt PPrrooppeerrttiieess You can change all properties of a breakpoint by pressing _m_o_u_s_e _b_u_t_t_o_n _3 on the breakpoint symbol and select `PPrroopp-- eerrttiieess' from the breakpoint popup menu. This will pop up a dialog showing the current properties of the selected breakpoint. As an even faster alternative, you can simply double-click on the breakpoint. +o Click on `LLooookkuupp' to move the cursor to the breakpoint's location. +o Click on `EEnnaabbllee' to enable the breakpoint. +o Click on `DDiissaabbllee' to disable the breakpoint. +o Click on `TTeemmpp' to make the breakpoint temporary. Note: GDB has no way to make a temporary breakpoint non- temporary again. +o Click on `DDeelleettee' to delete the breakpoint. DDD 3.1.1 1998-12-06 9 ddd(1) ddd(1) BBrreeaakkppooiinntt CCoonnddiittiioonnss In the field `CCoonnddiittiioonn' of the `BBrreeaakkppooiinntt PPrrooppeerrttiieess' panel, you can specify a _b_r_e_a_k_p_o_i_n_t _c_o_n_d_i_t_i_o_n. If a breakpoint condition is set, the breakpoint stops the pro- gram only if the associated condition is met--that is, if the condition expression evaluates to a non-zero value. Note: JDB does not support breakpoint conditions. BBrreeaakkppooiinntt IIggnnoorree CCoouunnttss In the field `IIggnnoorree CCoouunntt' of the `BBrreeaakkppooiinntt PPrrooppeerrttiieess' panel, you can specify a _b_r_e_a_k_p_o_i_n_t _i_g_n_o_r_e _c_o_u_n_t. If the ignore count is set to some value _N, the next _N crossings of the breakpoint will be ignored: Each crossing of the breakpoint decrements the ignore count; the program stops only if the ignore count is zero. Note: JDB, Perl and some DBX variants do not support breakpoint ignore counts. BBrreeaakkppooiinntt CCoommmmaannddss Note: Breakpoint commands are currently available on GDB only. Using the `CCoommmmaannddss' buttons of the `BBrreeaakkppooiinntt PPrrooppeerr-- ttiieess' panel, you can record and edit commands to be exe- cuted when the breakpoint is hit. To record a command sequence, follow these steps: +o Click on `RReeccoorrdd' to begin the recording of the break- point commands. +o Now interact with DDD. While recording, DDD does not execute commands, but simply records them to be executed when the breakpoint is hit. The recorded debugger com- mands are shown in the debugger console. +o To stop the recording, click on `EEnndd' or enter `eenndd' at the GDB prompt. To _c_a_n_c_e_l the recording, click on `IInntteerrrruupptt' or press EESSCC. +o Click on `EEddiitt >>>>' to edit the recorded commands. When done with editing, click on `EEddiitt <<<<' to close the com- mands editor. MMoovviinngg aanndd CCooppyyiinngg BBrreeaakkppooiinnttss To move a breakpoint to a different location, press _m_o_u_s_e _b_u_t_t_o_n _1 on the stop sign and drag it to the desired loca- tion. This is equivalent to deleting the breakpoint at the old location and setting a breakpoint at the new loca- tion. The new breakpoint inherits all properties of the old breakpoint, except the breakpoint number. DDD 3.1.1 1998-12-06 10 ddd(1) ddd(1) To copy a breakpoint to a new location, press the SShhiifftt key while dragging. Note: Dragging breakpoints is not possible when glyphs are disabled. Delete and set breakpoints instead. LLooookkiinngg uupp BBrreeaakkppooiinnttss If you wish to lookup a specific breakpoint, select `SSoouurrccee-->>EEddiitt BBrreeaakkppooiinnttss-->>LLooookkuupp'. After selecting a breakpoint from the list and clicking the `LLooookkuupp' 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 `LLooookkuupp (())' button to find its definition. EEddiittiinngg aallll BBrreeaakkppooiinnttss To view and edit all breakpoints at once, select `SSoouurrccee-->>EEddiitt BBrreeaakkppooiinnttss'. This will popup the _B_r_e_a_k_- _p_o_i_n_t _E_d_i_t_o_r which displays the state of all breakpoints. In the breakpoint editor, you can select individual break- points by clicking on them. Pressing CCttrrll while clicking toggles the selection. To edit the properties of all selected breakpoints, click on `PPrrooppss'. MMoorree BBrreeaakkppooiinntt FFeeaattuurreess Using GDB, a few more commands related to breakpoints can be invoked through the debugger console: hhbbrreeaakk _p_o_s_i_t_i_o_n Sets a hardware-assisted breakpoint at _p_o_s_i_t_i_o_n. This command requires hardware support and some target hardware may not have this support. The main purpose of this is EPROM/ROM code debug- ging, so you can set a breakpoint at an instruc- tion without changing the instruction. tthhbbrreeaakk _p_o_s Set a temporary hardware-assisted breakpoint at _p_o_s. See the GDB documentation for details on these commands. WWAATTCCHHPPOOIINNTTSS You can make the program stop as soon as some variable value changes, or when some variable is read or written. This is called `setting a _w_a_t_c_h_p_o_i_n_t on a variable'. Watchpoints have much in common with breakpoints: in par- ticular, you can enable and disable them. You can also set conditions, ignore counts, and commands to be executed when a watched variable changes its value. DDD 3.1.1 1998-12-06 11 ddd(1) ddd(1) Please note: on architectures without special watchpoint support, watchpoints currently make the program execute two orders of magnitude more slowly. This is so because the inferior debugger must interrupt the program after each machine instruction in order to examine whether the watched value has changed. However, this delay can be well worth it to catch errors when you have no clue what part of your program is the culprit. Note: Watchpoints are available in GDB and some DBX vari- ants only. In XDB, a similar feature is available via XDB _a_s_s_e_r_t_i_o_n_s; see the XDB documentation for details. SSeettttiinngg WWaattcchhppooiinnttss If the variable name is visible, click with _m_o_u_s_e _b_u_t_t_o_n _1 on the variable name. The variable name is copied to the argument field. Otherwise, enter the variable name in the argument field. Click on the `WWaattcchh (())' button to set a watchpoint there. Using GDB, you can set different types of watchpoints. Click and hold _m_o_u_s_e _b_u_t_t_o_n _1 on the `WWaattcchh (())' button to get a menu. EEddiittiinngg WWaattcchhppooiinntt PPrrooppeerrttiieess To change the properties of a watchpoint, enter the name of the watched variable in the argument field. Click and hold _m_o_u_s_e _b_u_t_t_o_n _1 on the `WWaattcchh (())' button and select `WWaattcchhppooiinntt PPrrooppeerrttiieess'. The WWaattcchhppooiinntt PPrrooppeerrttiieess panel has the same functionality as the BBrreeaakkppooiinntt PPrrooppeerrttiieess panel; see `EEddiittiinngg BBrreeaakk-- ppooiinntt PPrrooppeerrttiieess', above, for details. As an additional feature, you can click on `PPrriinntt (())' to see the current value of a watched variable. EEddiittiinngg aallll WWaattcchhppooiinnttss To view and edit all watchpoints at once, select `DDaattaa-->>EEddiitt WWaattcchhppooiinnttss'. This will popup the _W_a_t_c_h_p_o_i_n_t _E_d_i_t_o_r which displays the state of all watchpoints. The _W_a_t_c_h_p_o_i_n_t _E_d_i_t_o_r has the same functionality as the _B_r_e_a_k_p_o_i_n_t _E_d_i_t_o_r; see `EEddiittiinngg AAllll BBrreeaakkppooiinnttss', above, for details. As an additional feature, you can click on `PPrriinntt (())' to see the current value of a watched variable. DDeelleettiinngg WWaattcchhppooiinnttss To delete a watchpoint, enter the name of the watched variable in the argument field and click the `UUnnwwaattcchh (())' button. RRUUNNNNIINNGG TTHHEE PPRROOGGRRAAMM SSttaarrttiinngg PPrrooggrraamm EExxeeccuuttiioonn To start execution of the debugged program, select DDD 3.1.1 1998-12-06 12 ddd(1) ddd(1) `PPrrooggrraamm-->>RRuunn'. You will then be prompted for the argu- ments to pass to your program. You can either select from a list of previously used arguments or enter own arguments in the text field. Afterwards, press the `RRuunn' button to start execution with the selected arguments. To run your program again, with the same arguments, select `PPrrooggrraamm-->>RRuunn AAggaaiinn' or press the `RRuunn' button on the com- mand tool. You may also enter `rruunn', followed by argu- ments at the debugger prompt instead. UUssiinngg tthhee EExxeeccuuttiioonn WWiinnddooww By default, input and output of your program go to the debugger console. As an alternative, DDD can also invoke 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. To activate the execution window, select `PPrrooggrraamm-->>RRuunn iinn EExxeeccuuttiioonn WWiinnddooww'. While the execution window is active, DDD invokes your program such that its standard input, output, and error streams are redirected to the execution window. Note that the device `//ddeevv//ttttyy' still refers to the debugger con- sole, _n_o_t the execution window. You can override the DDD stream redirection by giving alternate redirection operations as arguments. For instance, to have your program read from a file, but to write to the execution window, invoke your program with `<< _f_i_l_e' as argument. Likewise, to redirect the standard error output to the debugger console, use `22>> //ddeevv//ttttyy' (assuming the inferior debugger and/or your UNIX shell support standard error redirection). The execution window is not available in JDB and Perl. AAttttaacchhiinngg ttoo aa RRuunnnniinngg PPrroocceessss If the debugged program is already running in some pro- cess, you can _a_t_t_a_c_h to this process (instead of starting a new one with `RRuunn'). Select `FFiillee-->>AAttttaacchh ttoo PPrroocceessss' to choose from a list of processes. Afterwards, press the `AAttttaacchh' button to attach to the specified process. The first thing DDD does after arranging to debug the specified process is to stop it. You can examine and mod- ify an attached process with all the DDD commands that are ordinarily available when you start processes with `RRuunn'. You can insert breakpoints; you can step and continue; you can modify storage. If you would rather the process con- tinue running, you may use `CCoonnttiinnuuee' after attaching DDD to the process. When using `AAttttaacchh ttoo PPrroocceessss', you should first use `OOppeenn PPrrooggrraamm' to specify the program running in the process and DDD 3.1.1 1998-12-06 13 ddd(1) ddd(1) load its symbol table. When you have finished debugging the attached process, you can use the `FFiillee-->>DDeettaacchh PPrroocceessss' to release it from DDD control. Detaching the process continues its execution. After `DDeettaacchh PPrroocceessss', that process and DDD become com- pletely independent once more, and you are ready to attach another process or start one with `RRuunn'. You can customize the list of processes shown by defining an alternate command to list processes. See `EEddiitt-->>PPrreeffeerreenncceess-->>HHeellppeerrss-->>LLiisstt PPrroocceesssseess'. Note: JDB, PYDB, and Perl do not support attaching the debugger to running processes. SSttooppppiinngg tthhee PPrrooggrraamm 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 `IInntteerrrruupptt' button or typing EESSCC in a DDD window. RReessuummiinngg EExxeeccuuttiioonn To resume execution, at the address where your program last stopped, click on the `CCoonnttiinnuuee` button. Any break- points set at that address are bypassed. To execute just one source line, click on the `SStteepp' 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 `NNeexxtt' button. This is similar to `SStteepp', but any function calls appearing within the line of code are executed without stopping. To continue until a greater line in the current function is reached, click on the `UUnnttiill' button. This is useful to avoid single stepping through a loop more than once. To continue running until the current function returns, use the `FFiinniisshh' button. The returned value (if any) is printed. To continue running until a line after the current source line is reached, use the `CCoonnttiinnuuee UUnnttiill HHeerree' facility from the line popup menu. See the `TTeemmppoorraarryy BBrreeaakkppooiinnttss' section, above, for a discussion. AAlltteerriinngg tthhee EExxeeccuuttiioonn PPoossiittiioonn To resume execution at a different location, press _m_o_u_s_e _b_u_t_t_o_n _1 on the arrow and drag it to a different location. DDD 3.1.1 1998-12-06 14 ddd(1) ddd(1) The most common occasion to use this feature is to back up--perhaps with more breakpoints set-over a portion of a program that has already executed, in order to examine its execution in more detail. Moving the execution position does not change the current stack frame, or the stack pointer, or the contents of any memory location or any register other than the program counter. Some inferior debuggers (notably GDB) allow you to set the new execution position into a different function from the one currently executing. This may lead to bizarre results if the two functions expect different patterns of argu- ments or of local variables. For this reason, moving the execution position requests confirmation if the specified line is not in the function currently executing. After moving the execution position, click on the `CCoonn-- ttiinnuuee' button to resume execution. Note: Dragging the execution position is not possible when glyphs are disabled. Use `SSeett EExxeeccuuttiioonn PPoossiittiioonn' from the breakpoint popup menu instead to set the execution position to the current location. This item is also accessible by pressing and holding the `BBrreeaakk aatt (())/CClleeaarr aatt (())' button. Note: JDB does not support altering the execution posi- tion. EExxaammiinniinngg tthhee SSttaacckk When your program has stopped, the first thing you need to know is where it stopped and how it got there. DDD provides a _b_a_c_k_t_r_a_c_e _w_i_n_d_o_w showing a summary of how your program got where it is. To enable the backtrace window, select `SSttaattuuss-->>BBaacckkttrraaccee'. The `UUpp' button selects the function that called the cur- rent one. The `DDoowwnn' button selects the function that was called by the current one. You can also directly type the `uupp' and `ddoowwnn' commands at the debugger prompt. Typing CCttrrll++UUpp and CCttrrll++DDoowwnn, respectively, will also move you through the stack. `UUpp' and `DDoowwnn' actions can be undone via `EEddiitt-->>UUnnddoo'. DDD 3.1.1 1998-12-06 15 ddd(1) ddd(1) ""UUnnddooiinngg"" PPrrooggrraamm EExxeeccuuttiioonn If you take a look at the `EEddiitt-->>UUnnddoo' menu item after an execution command, you'll find that DDD offers you to undo execution commands just as other commands. Does this mean that DDD allows you to go backwards in time, undoing pro- gram execution as well as undoing any side-effects of your program? Sorry--we must disappoint you. DDD cannot undo what your program did. (After a little bit of thought, you'll find that this would be impossible in general.) However, DDD can do something different: it can show _p_r_e_v_i_o_u_s_l_y _r_e_c_o_r_d_e_d _s_t_a_t_e_s of your program. After "undoing" an execution command (via `EEddiitt-->>UUnnddoo', or the `UUnnddoo' button), the execution position moves back to the earlier position and displayed variables take their earlier values. Your program state is in fact unchanged, but DDD gives you a _v_i_e_w on the earlier state as recorded by DDD. In this so-called _h_i_s_t_o_r_i_c _m_o_d_e, most normal DDD commands that would query further information from the program are disabled, since the debugger cannot be queried for the earlier state. However, you can examine the current exe- cution position, or the displayed variables. Using `UUnnddoo' and `RReeddoo', you can move back and forward in time to exam- ine how your program got into the present state. To let you know that you are operating in historic mode, the execution arrow gets a dashed-line appearance (indi- cating a past position); variable displays also come with dashed lines. Furthermore, the status line informs you that you are seeing an earlier program state. Here's how historic mode works: each time your program stops, DDD collects the current execution position and the values of displayed variables. Backtrace, thread, and register information is also collected if the correspond- ing dialogs are open. When "undoing" an execution com- mand, DDD updates its view from this collected state instead of querying the program. If you want to collect this information without interrupt- ing your program--within a loop, for instance--you can place a breakpoint with an associated `ccoonntt' command; see `BBrreeaakkppooiinntt CCoommmmaannddss', above, for details. When the breakpoint is hit, DDD will stop, collect the data, and execute the `ccoonntt' command, resuming execution. Using a later `UUnnddoo', you can step back and look at every single loop iteration. To leave historic mode, you can use `RReeddoo' until you are back in the current program state. However, any DDD DDD 3.1.1 1998-12-06 16 ddd(1) ddd(1) command that refers to program state will also leave his- toric mode immediately by applying to the current program state instead. For instance, `UUpp' leaves historic mode immediately and selects an alternate frame in the restored current program state. If you want to see the history of a specific variable, as recorded during program stops, you can enter the DDD com- mand ggrraapphh hhiissttoorryy _n_a_m_e This returns a list of all previously recorded values of the variable _n_a_m_e, using array syntax. Note that _n_a_m_e must have been displayed at earlier program stops in order to record values. EExxaammiinniinngg TThhrreeaaddss Note: Thread support is available with GDB and JDB only. In some operating systems, a single program may have more than one _t_h_r_e_a_d 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 _c_u_r_r_e_n_t _t_h_r_e_a_d--the thread which is the focus of debugging. DDD shows all program information from the perspective of the current thread. To view all currently active threads in your program, select `SSttaattuuss-->>TThhrreeaaddss'. The current thread is high- lighted. Select any thread to make it the current thread. Using JDB, additional functionality is available: +o Select a _t_h_r_e_a_d _g_r_o_u_p to switch between viewing all threads and the threads of the selected thread group; +o Click on `SSuussppeenndd' to suspend execution of the selected threads; +o Click on `RReessuummee' to resume execution of the selected threads. For more information on threads, see the JDB and GDB docu- mentation. DDD 3.1.1 1998-12-06 17 ddd(1) ddd(1) HHaannddlliinngg SSiiggnnaallss Note: Signal support is available with GDB only. A signal is an asynchronous event that can happen in a program. The operating system defines the possible kinds of signals, and gives each kind a name and a number. For example, in Unix SSIIGGIINNTT is the signal a program gets when you type an interrupt; SSIIGGSSEEGGVV is the signal a program gets from referencing a place in memory far away from all the areas in use; SSIIGGAALLRRMM occurs when the alarm clock timer goes off (which happens only if your program has requested an alarm). Some signals, including SSIIGGAALLRRMM, are a normal part of the functioning of your program. Others, such as SSIIGGSSEEGGVV, indicate errors; these signals are _f_a_t_a_l (kill your pro- gram immediately) if the program has not specified in advance some other way to handle the signal. SSIIGGIINNTT does not indicate an error in your program, but it is normally fatal so it can carry out the purpose of the interrupt: to kill the program. GDB has the ability to detect any occurrence of a signal in your program. You can tell GDB in advance what to do for each kind of signal. Normally, DDD is set up to ignore non-erroneous signals like SSIIGGAALLRRMM (so as not to interfere with their role in the functioning of your program) but to stop your program immediately whenever an error signal happens. In DDD, you can change these settings via `SSttaattuuss-->>SSiiggnnaallss'. `SSttaattuuss-->>SSiiggnnaallss' pops up a panel showing all the kinds of signals and how GDB has been told to handle each one. The settings available for each signal are: SSttoopp If set, GDB should stop your program when this signal happens. This also implies `PPrriinntt' being set. If unset, GDB should not stop your program when this signal happens. It may still print a mes- sage telling you that the signal has come in. PPrriinntt If set, GDB should print a message when this signal happens. If unset, GDB should not mention the occurrence of the signal at all. This also implies `SSttoopp' being unset. PPaassss If set, GDB should allow your program to see this signal; your program can handle the signal, or else it may terminate if the signal is fatal and not handled. If unset, GDB should not allow your program to DDD 3.1.1 1998-12-06 18 ddd(1) ddd(1) see this signal. The entry `AAllll SSiiggnnaallss' is special. Changing a setting here affects _a_l_l _s_i_g_n_a_l_s _a_t _o_n_c_e--except those used by the debugger, typically SIGTRAP and SIGINT. To undo any changes, use `EEddiitt-->>UUnnddoo'. The `RReesseett' button restores the saved settings. When a signal stops your program, the signal is not visi- ble until you continue. Your program sees the signal then, if `PPaassss' is in effect for the signal in question _a_t _t_h_a_t _t_i_m_e. In other words, after GDB reports a signal, you can change the `PPaassss' setting in `SSttaattuuss-->>SSiiggnnaallss' to control whether your program sees that signal when you continue. You can also cause your program to see a signal it nor- mally would not see, or to give it any signal at any time. The `SSeenndd' button will resume execution where your program stopped, but immediately give it the signal shown. On the other hand, you can also prevent your program from seeing a signal. For example, if your program stopped due to some sort of memory reference error, you might store correct values into the erroneous variables and continue, hoping to see more execution; but your program would prob- ably terminate immediately as a result of the fatal signal once it saw the signal. To prevent this, you can resume execution using `CCoommmmaannddss-->>CCoonnttiinnuuee WWiitthhoouutt SSiiggnnaall'. `EEddiitt-->>SSaavvee OOppttiioonnss' does not save changed signal set- tings, since changed signal settings are normally useful within specific projects only. Instead, signal settings are saved with the current session, using `FFiillee-->>SSaavvee SSeess-- ssiioonn AAss'. EEXXAAMMIINNIINNGG DDAATTAA DDD provides several means to examine data. VVaalluuee HHiinnttss 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. PPrriinnttiinngg VVaalluueess If you want to reuse variable values at a later time, you can print the value in the debugger console. This allows for displaying and examin- ing larger data structures. DDD 3.1.1 1998-12-06 19 ddd(1) ddd(1) DDiissppllaayyiinngg VVaalluueess 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. PPlloottttiinngg VVaalluueess If you want to examine arrays of numeric values, you can plot them graphically in a separate plot window. The plot is updated each time the pro- gram stops. This is useful for large numeric arrays. MMeemmoorryy DDuummppss This feature, available using GDB only, allows you to dump memory contents in any of several formats, independently of your program's data types. This is described under `MMAACCHHIINNEE--LLEEVVEELL DDEEBBUUGGGGIINNGG', below. SShhoowwiinngg SSiimmppllee VVaalluueess uussiinngg VVaalluuee HHiinnttss To display the value of a simple variable, move the mouse pointer on its name. After a second, a small window (called _v_a_l_u_e _t_i_p) pops up showing the value of the vari- able 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. PPrriinnttiinngg SSiimmppllee VVaalluueess iinn tthhee DDeebbuuggggeerr CCoonnssoollee The variable value can also be printed in the debugger console, making it available for further operations. To print a variable value, select the desired variable by clicking _m_o_u_s_e _b_u_t_t_o_n _1 on its name. The variable name is copied to the argument field. By clicking the `PPrriinntt (())' button, the value is printed in the debugger console. Note that the value is also shown in the status line. As a shorter alternative, you can simply press _m_o_u_s_e _b_u_t_- _t_o_n _3 on the variable name and select the `PPrriinntt' item from the popup menu. DDiissppllaayyiinngg CCoommpplleexx VVaalluueess iinn tthhee DDaattaa WWiinnddooww To explore complex data structures, you can use 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. To create a new display, select the desired variable by clicking _m_o_u_s_e _b_u_t_t_o_n _1 on its name. The variable name is DDD 3.1.1 1998-12-06 20 ddd(1) ddd(1) copied to the argument field. By clicking the `DDiissppllaayy (())' button, a new display is created in the data window. The data window opens automatically as soon as you create a display. As a shorter alternative, you can simply press _m_o_u_s_e _b_u_t_- _t_o_n _3 on the variable name and select the `DDiissppllaayy' item from the popup menu. As an even faster alternative, you can also double-click on the variable name. As another alternative, you may also enter the expression to be displayed in the argument field and press the `DDiiss-- ppllaayy (())' button. Finally, you may also enter ggrraapphh ddiissppllaayy _e_x_p_r [cclluusstteerreedd] [aatt ((_x_, _y))] [ddeeppeennddeenntt oonn _d_i_s_p_l_a_y] [[nnooww oorr]wwhheenn iinn _s_c_o_p_e] at the debugger prompt. The options have the following meaning: +o If the suffix `cclluusstteerreedd' is specified, the new data display is created in a cluster. See `CClluusstteerriinngg DDiiss-- ppllaayyss', below, for a discussion. +o If the suffix `aatt ((_x_, _y))' is specified, the new data display is created at the position (_x, _y). Otherwise, a default position is assigned. +o If the suffix `ddeeppeennddeenntt oonn _d_i_s_p_l_a_y' is given, an edge from the display numbered or named _d_i_s_p_l_a_y to the new display is created. Otherwise, no edge is created. +o If the suffix `wwhheenn iinn _s_c_o_p_e' is given, display creation is _d_e_f_e_r_r_e_d until execution reaches the given _s_c_o_p_e (a function name, as in the backtrace output). +o If the suffix `nnooww oorr wwhheenn iinn _s_c_o_p_e' is given, DDD attempts to create the display immediately. If display creation fails, it is _d_e_f_e_r_r_e_d until execution reaches the given _s_c_o_p_e (a function name, as in the backtrace output). +o If no `wwhheenn iinn' suffix or `nnooww oorr wwhheenn iinn' suffix is given, the display is created immediately. If you created a display by mistake, use `EEddiitt-->>UUnnddoo' to undisplay it. DDD 3.1.1 1998-12-06 21 ddd(1) ddd(1) SSeelleeccttiinngg DDiissppllaayyss 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 _m_o_u_s_e _b_u_t_t_o_n _1. 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 SShhiifftt key while selecting. You can also _t_o_g_g_l_e an existing selection by pressing the SShhiifftt key while selecting already selected displays. Single displays may also be selected by using the arrow keys. SSeelleeccttiinngg MMuullttiippllee DDiissppllaayyss Multiple displays are selected by pressing and holding _m_o_u_s_e _b_u_t_t_o_n _1 somewhere on the window background. By moving the pointer while holding the button, a selection rectangle is shown; all displays fitting in the rectangle are selected when mouse button 1 is released. If the SShhiifftt key is pressed while selecting, the existing selection is _e_x_t_e_n_d_e_d. By double-clicking on a display title, the display itself and all connected displays are automatically selected. SShhoowwiinngg aanndd HHiiddiinngg VVaalluueess Aggregate values (i.e. records, structs, classes, and arrays) can be shown _e_x_p_a_n_d_e_d, that is, displaying all details, or _h_i_d_d_e_n, that is, displayed as `{{......}}'. To show details about an aggregate, select the aggregate by clicking _m_o_u_s_e _b_u_t_t_o_n _1 on its name or value and click on the `SShhooww (())' button. Details are shown for the aggre- gate itself as well as for all contained sub-aggregates. To hide details about an aggregate, select the aggregate by clicking _m_o_u_s_e _b_u_t_t_o_n _1 on its name or value and click on the `HHiiddee (())' button. When pressing and holding _m_o_u_s_e _b_u_t_t_o_n _1 on the `SShhooww (())/HHiiddee (())' button, a menu pops up with even more alterna- tives: SShhooww MMoorree (()) Shows details of all aggregates currently hidden, but not of their sub-aggregates. You can invoke this item several times in a row to reveal more and DDD 3.1.1 1998-12-06 22 ddd(1) ddd(1) more details of the selected aggregate. SShhooww JJuusstt (()) Shows details of the selected aggregate, but hides all sub-aggregates. SShhooww AAllll (()) Shows all details of the selected aggregate and of its sub-aggregates. This item is equivalent to the `SShhooww (())' button. HHiiddee (()) Hide all details of the selected aggregate. This item is equivalent to the `HHiiddee (())' button. As a faster alternative, you can also press _m_o_u_s_e _b_u_t_t_o_n _3 on the aggregate and select the appropriate menu item. As an even faster alternative, you can also double-click _m_o_u_s_e _b_u_t_t_o_n _1 on a value. If some part of the value is hidden, more details will be shown; if the entire value is shown, double-clicking will _h_i_d_e the value instead. This way, you can double-click on a value until you get the right amount of details. If _a_l_l details of a display are hidden, the display is called _d_i_s_a_b_l_e_d; this is indicated by the string `_(_D_i_s_- _a_b_l_e_d_)'. Displays can also be disabled or enabled via the DDD commands ggrraapphh ddiissaabbllee ddiissppllaayy _d_i_s_p_l_a_y_s_._._. and ggrraapphh eennaabbllee ddiissppllaayy _d_i_s_p_l_a_y_s_._._. at the debugger prompt. _d_i_s_p_l_a_y_s_._._. is either +o a space-separated list of display numbers to disable or enable, or +o a single display name. If you specify a display by name, all displays with this name will be affected. Use `EEddiitt-->>UUnnddoo' to undo disabling or enabling displays. RRoottaattiinngg AArrrraayyss Arrays can be aligned horizontally or vertically. To change the alignment of an array, select it and then click on the `RRoottaattee (())' button. As a faster alternative, you can also press _m_o_u_s_e _b_u_t_t_o_n _3 on the array and select the `RRoottaattee' menu item. DDD 3.1.1 1998-12-06 23 ddd(1) ddd(1) DDiissppllaayyiinngg DDeeppeennddeenntt VVaalluueess 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 enter the dependent expression in the `(())::' argument field. Then click on the `DDiissppllaayy' button. Using dependent displays, you can investigate the data structure of a "tree" for example and lay it out according to your intuitive image of the "tree" data structure. By default, DDD does not recognize shared data structures (i.e. a data object referenced by multiple other data objects). See `EExxaammiinniinngg SShhaarreedd DDaattaa SSttrruuccttuurreess', below, for details on how to examine such structures. DDiissppllaayy SShhoorrttccuuttss DDD maintains a _s_h_o_r_t_c_u_t _m_e_n_u of frequently used display expressions. This menu is activated +o by pressing and holding the `DDiissppllaayy' button, or +o by pressing _m_o_u_s_e _b_u_t_t_o_n _3 on some display and selecting `NNeeww DDiissppllaayy', or +o by pressing SShhiifftt and _m_o_u_s_e _b_u_t_t_o_n _3 on some display. By default, the shortcut menu contains frequently used base conversions. The `OOtthheerr' entry in the shortcut menu lets you create a new display that _e_x_t_e_n_d_s the shortcut menu. As an exam- ple, assume you have selected a display named `ddaattee__ppttrr'. Selecting `DDiissppllaayy-->>OOtthheerr' pops up a dialog that allows you to enter a new expression to be displayed -- for instance, you can cast the display `ddaattee__ppttrr' to a new display `((cchhaarr **))ddaattee__ppttrr'. If the `IInncclluuddee iinn ``NNeeww DDiiss-- ppllaayy' Menu' toggle was activated, the shortcut menu will then contain a new entry `DDiissppllaayy ((cchhaarr **))(())' that will cast _a_n_y selected display _d_i_s_p_l_a_y to `((cchhaarr **))_d_i_s_p_l_a_y'. Such shortcuts can save you a lot of time when examining complex data structures. You can edit the contents of the `NNeeww DDiissppllaayy' menu by selecting its `EEddiitt MMeennuu' item. This pops up the _S_h_o_r_t_c_u_t _E_d_i_t_o_r containing all shortcut expressions, which you can edit at leisure. Each line contains the expression for exactly one menu item. Clicking on `AAppppllyy' re-creates the `NNeeww DDiissppllaayy' menu from the text. If the text is empty, the `NNeeww DDiissppllaayy' menu will be empty, too. DDD 3.1.1 1998-12-06 24 ddd(1) ddd(1) DDD also allows you to specify individual labels for user- defined buttons. You can write such a label after the expression, separated by `////'. This feature is used in the default contents of the GDB `NNeeww DDiissppllaayy' menu, where each of the base conversions has a label: //tt (()) //// CCoonnvveerrtt ttoo BBiinn //dd (()) //// CCoonnvveerrtt ttoo DDeecc //xx (()) //// CCoonnvveerrtt ttoo HHeexx //oo (()) //// CCoonnvveerrtt ttoo OOcctt Feel free to add other conversions here. DDD supports up to 20 `NNeeww DDiissppllaayy' menu items. DDeerreeffeerreenncciinngg PPooiinntteerrss There are special shortcuts for creating dependent dis- plays showing the value of a dereferenced pointer. This allows for rapid examination of pointer-based data struc- tures. To dereference a pointer, select the originating pointer value or name and click on the `DDiissppllaayy **(())' button. A new display showing the dereferenced pointer value is cre- ated. As a faster alternative, you can also press _m_o_u_s_e _b_u_t_t_o_n _3 on the originating pointer value or name and select the `DDiissppllaayy **' menu item. As an even faster alternative, you can also double-click _m_o_u_s_e _b_u_t_t_o_n _1 on the originating pointer value or name. If you press CCttrrll while double-clicking, the display will be dereferenced _i_n _p_l_a_c_e--that is, it will be replaced by the dereferenced display. The `DDiissppllaayy **(())' function is also accessible by pressing and holding the `DDiissppllaayy (())' button. DDiissppllaayyiinngg LLooccaall VVaarriiaabblleess You can display all local variables at once by choosing `DDaattaa-->>DDiissppllaayy LLooccaall VVaarriiaabblleess'. When using DBX, XDB, JDB, or Perl, this displays all local variables, including the arguments of the current function. When using GDB or PYDB, function arguments are contained in a separate dis- play, activated by `DDiissppllaayy AArrgguummeennttss'. The display showing the local variables can be manipulated just like any other data display. Individual variables can be selected and dereferenced. DDiissppllaayyiinngg PPrrooggrraamm SSttaattuuss You can create a display from the output of an arbitrary DDD 3.1.1 1998-12-06 25 ddd(1) ddd(1) debugger command. By entering ggrraapphh ddiissppllaayy ``_c_o_m_m_a_n_d`` the output of _c_o_m_m_a_n_d is turned into a _s_t_a_t_u_s _d_i_s_p_l_a_y updated each time the program stops. For instance, ggrraapphh ddiissppllaayy ``wwhheerree`` creates a status display named `WWhheerree' that shows the cur- rent backtrace. If you are using GDB, DDD provides a panel from which you can choose useful status displays. Select `DDaattaa-->>MMoorree SSttaattuuss DDiissppllaayyss' and pick your choice from the list. Status displays consume time; you should delete them as soon as you don't need them any more. DDiissppllaayyiinngg MMuullttiippllee AArrrraayy VVaalluueess 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 [[_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, ggrraapphh ddiissppllaayy aarrggvv[[00....99]] creates ten new display nodes for `aarrggvv[[00]]', `aarrggvv[[11]]', ..., `aarrggvv[[99]]'. Using GDB as inferior debugger, you can use _a_r_t_i_f_i_c_i_a_l _a_r_r_a_y_s. Typing ggrraapphh ddiissppllaayy aarrggvv[[00]] @@ 1100 creates a single array display node containing `aarrggvv[[00]]' up to `aarrggvv[[99]]'. 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. RReeppeeaatteedd AArrrraayy VVaalluueess Using GDB, an array value that is repeated 10 or more times is displayed only once. The value is shown with a `<<_Nxx>>' postfix added, where _N is the number of times the DDD 3.1.1 1998-12-06 26 ddd(1) ddd(1) value is repeated. Thus, the display `00xx00 <<3300xx>>' stands for 30 array elements, each with the value 00xx00. This saves a lot of display space, especially with homogeneous arrays. The default GDB threshold for repeated array values is 10. You can change it via `EEddiitt-->>GGDDBB SSeettttiinnggss-->>TThhrreesshhoolldd ffoorr rreeppeeaatteedd pprriinntt eelleemmeennttss'. Setting the threshold to 00 will cause GDB (and DDD) to display each array element individ- ually. Be sure to refresh the data window via `DDaattaa-->>RReeffrreesshh DDiissppllaayyss' after a change in GDB settings. You can also configure DDD to display each array element individually, regardless of GDB settings; see the `eexxppaannddRReeppeeaatteeddVVaalluueess' resource for details. AAlltteerriinngg VVaarriiaabbllee VVaalluueess Using the `SSeett (())' button or the `SSeett VVaalluuee' 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 `OOKK' or `AAppppllyy' button commits your change. If you made a mistake, you can use `EEddiitt-->>UUnnddoo' to re-set the variable to its previous value. Note: Altering variable values is not supported in JDB. RReeffrreesshhiinngg tthhee DDaattaa WWiinnddooww The data window refreshes itself automatically each time the program stops. Values that have changed are high- lighted. However, there may be situations where you should refresh the data window explicitly. This is especially the case whenever you changed debugger settings that could affect the data format, and want the data window to reflect these settings. You can refresh the data window by selecting `DDaattaa-->>RReeffrreesshh DDiissppllaayyss'. As an alternative, you can press _m_o_u_s_e _b_u_t_t_o_n _3 on the background of the data window and select the `RReeffrreesshh DDiiss-- ppllaayy' item. Typing ggrraapphh rreeffrreesshh at the debugger prompt has the same effect. DDD 3.1.1 1998-12-06 27 ddd(1) ddd(1) DDeelleettiinngg DDiissppllaayyss To delete a single display, select it and click on the `DDeelleettee (())' button. As an alternative, you can also press _m_o_u_s_e _b_u_t_t_o_n _3 on the display and select the `DDeelleettee DDiiss-- ppllaayy' 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 `DDeelleettee' item in the Display Editor (invoked via `DDaattaa-->>EEddiitt DDiiss-- ppllaayyss'). Select any number of display items in the usual way and delete them by pressing `DDeelleettee'. As an alternative, you can also type ggrraapphh uunnddiissppllaayy _d_i_s_p_l_a_y_s_._._. at the debugger prompt. _d_i_s_p_l_a_y_s_._._. is either +o a space-separated list of display numbers to delete, or +o a single display name. If you specify a display by name, all displays with this name will be deleted. If you are using stacked windows, deleting the last dis- play from the data window also automatically closes the data window. (You can change this via `EEddiitt-->>PPrreeffeerreenncceess-->>DDaattaa-->>CClloossee ddaattaa wwiinnddooww wwhheenn ddeelleettiinngg llaasstt ddiissppllaayy'.) If you deleted a display by mistake, use `EEddiitt-->>UUnnddoo' to re-create it. EExxaammiinniinngg SShhaarreedd DDaattaa SSttrruuccttuurreess By default, DDD does not recognize shared data struc- tures--that is, a data object referenced by multiple other data objects. For instance, if two pointers pp11 and pp22 point at the same data object dd, the data displays dd, **pp11, and **pp22 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 _a_l_i_a_s_e_s into one single data display, the _o_r_i_g_i_n_a_l _d_a_t_a _d_i_s_p_l_a_y. This mode is called _A_l_i_a_s _D_e_t_e_c_t_i_o_n; it is enabled via the `DDaattaa-->>DDeetteecctt AAlliiaasseess'. When alias detection is enabled, DDD inquires the memory location (the _a_d_d_r_e_s_s) of each data display after each program step. If two displays have the same address, they are merged into one. More specifically, only the one DDD 3.1.1 1998-12-06 28 ddd(1) ddd(1) which has least recently changed remains (the _o_r_i_g_i_n_a_l _d_a_t_a _d_i_s_p_l_a_y); all other aliases are _s_u_p_p_r_e_s_s_e_d, i.e. com- pletely hidden. The edges leading to the aliases are replaced by edges leading to the original data display. An edge created by alias detection is somewhat special: rather than connecting two displays directly, it goes through an _e_d_g_e _h_i_n_t, 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 `UUnnddiissppllaayy (())'. To access suppressed display aliases, you can also use the Display Editor. Suppressed displays are listed in the Display Editor as _a_l_i_a_s_e_s of the original data display. Via the Display Editor, you can select, change, and delete suppressed displays. Suppressed displays become visible again as soon as +o alias detection is disabled, +o their address changes such that they are no more aliases, or +o the original data display is deleted, such that the least recently changed alias becomes the new original data display. Please note the following _c_a_v_e_a_t_s with alias detection: +o Alias detection requires that the current programming language provides a means to determine the address of an arbitrary data object. Currently, only C and C++ are supported. +o Some inferior debuggers (for instance, SunOS DBX) pro- duce 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 Dis- play Editor. +o Alias detection slows down DDD slightly, 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 DDD 3.1.1 1998-12-06 29 ddd(1) ddd(1) automatically restore edges and data displays when switching modes. CClluusstteerriinngg DDiissppllaayyss If you examine several variables at once, having a sepa- rate display for each of them uses a lot of screen space. This is why DDD supports _c_l_u_s_t_e_r_s. A cluster merges sev- eral logical data displays into one physical display, sav- ing screen space. There are two ways to create clusters: +o You can create clusters _m_a_n_u_a_l_l_y. This is done by selecting the displays to be clustered and choosing `UUnnddiisspp-->>CClluusstteerr (())'. This creates a new cluster from all selected displays. If an already existing cluster is selected, too, the selected displays will be clus- tered into the selected cluster. +o You can create a cluster _a_u_t_o_m_a_t_i_c_a_l_l_y for all indepen- dent data displays, such that all new data displays will automatically be clustered, too. This is achieved by enabling `EEddiitt-->>PPrreeffeerreenncceess-->>DDaattaa-->>CClluusstteerr DDaattaa DDiiss-- ppllaayyss'. Displays in a cluster can be selected and manipulated like parts of an ordinary display; in particular, you can show and hide details, or dereference pointers. However, edges leading to clustered displays can not be shown, and you must either select one or all clustered displays. Disabling a cluster is called _u_n_c_l_u_s_t_e_r_i_n_g, and again, there are two ways of doing it: +o You can uncluster displays _m_a_n_u_a_l_l_y, by selecting the cluster and choosing `UUnnddiisspp-->>UUnncclluusstteerr (())'. +o You can uncluster all current and future displays by disabling `EEddiitt-->>PPrreeffeerreenncceess-->>DDaattaa-->>CClluusstteerr DDaattaa DDiiss-- ppllaayyss'. MMoovviinngg DDiissppllaayyss AArroouunndd 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 _m_o_u_s_e _b_u_t_t_o_n _1 on the dis- play 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 DDD 3.1.1 1998-12-06 30 ddd(1) ddd(1) _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 `CCUUSSTTOOMMIIZZIINNGG DDDDDD', 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 SShhiifftt and an arrow key moves displays by single pixels. Pressing CCttrrll 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. AAlliiggnniinngg DDiissppllaayyss You can align all displays on the nearest grid position by selecting `DDaattaa-->>AAlliiggnn oonn GGrriidd'. This is useful for keep- ing edges horizontal or vertical. You can enforce alignment by selecting `EEddiitt-->>PPrreeffeerreenncceess-->>DDaattaa-->>AAuuttoo--aalliiggnn ddiissppllaayyss oonn nneeaarreesstt ggrriidd ppooiinntt'. If this feature is enabled, displays can be moved on grid positions only. LLaayyoouuttiinngg tthhee DDiissppllaayy GGrraapphh You can layout the entire graph as a tree by selecting `DDaattaa-->>LLaayyoouutt GGrraapphh'. 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. Edge hints can be moved around like arbitrary displays. To enable a more compact layout, you can set the `EEddiitt-->>PPrreeffeerreenncceess-->>DDaattaa-->>CCoommppaacctt llaayyoouutt' option. This realizes an alternate layout algorithm, where successors are placed next to their parents. This algorithm is suit- able for homogeneous data structures only. You can enforce layout by setting `EEddiitt-->>PPrreeffeerreenncceess-->>DDaattaa-->> AAuuttoommaattiicc LLaayyoouutt'. If auto- matic layout is enabled, the graph is layouted after each change. RRoottaattiinngg tthhee DDiissppllaayy GGrraapphh You can rotate the entire graph clockwise by 90 degrees by selecting `DDaattaa-->>RRoottaattee GGrraapphh'. 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 3.1.1 1998-12-06 31 ddd(1) ddd(1) PPrriinnttiinngg tthhee DDiissppllaayy GGrraapphh 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 `FFiillee-->>PPrriinntt GGrraapphh'. Enter the printing command in the `PPrriinntt CCoommmmaanndd' field. Click on the `OOKK' or the `AAppppllyy' button to start printing. As an alternative, you may also print the graph in a file. Click on the `FFiillee' button and enter the file name in the `FFiillee NNaammee' field. Click on the `PPrriinntt' button to create the file. When the graph is printed in a file, two formats are available: +o PPoossttSSccrriipptt--suitable for enclosing the graph in another document; +o FFIIGG--suitable for post-processing, using the XFIG graphic editor, or for conversion into other formats (among others IBMGL, LATEX, PIC), using the TRANSFIG or FIG2DEV package. Please note the following _c_a_v_e_a_t_s related to printing graphs: +o If any displays were selected when invoking the `PPrriinntt' dialog, the option `SSeelleecctteedd OOnnllyy' is set. This makes DDD print only the selected displays. +o The `CCoolloorr', `OOrriieennttaattiioonn', and `PPaappeerr SSiizzee' options are meaningful for PostScript only. PPLLOOTTTTIINNGG DDAATTAA If you have huge amounts of numerical data to examine, a picture often says more than a thousand numbers. There- fore, DDD allows you to draw numerical values in nice 2-D and 3-D plots. PPlloottttiinngg AArrrraayyss Basically, DDD can plot two types of numerical values: +o One-dimensional arrays. These are drawn in a 2-D _X/_Y space, where _X denotes the array index, and _Y the ele- ment value. +o Two-dimensional arrays. These are drawn in a 3-D _X/_Y/_Z space, where _X and _Y denote the array indexes, and _Z the DDD 3.1.1 1998-12-06 32 ddd(1) ddd(1) element value. To plot an array, select it by clicking _m_o_u_s_e _b_u_t_t_o_n _1 on an occurrence. The array name is copied to the argument field. By clicking the `PPlloott' button, a new display is created in the data window, followed by a new top-level window containing the value plot. Each time the value changes during program execution, the plot is updated to reflect the current values. The plot window remains active until you close it (via `FFiillee-->>CClloossee') or until the associated display is deleted. CChhaannggiinngg tthhee PPlloott AAppppeeaarraannccee The actual drawing is not done by DDD itself. Instead, DDD relies on an external Gnuplot program to create the drawing. DDD adds a menu bar to the Gnuplot plot window that lets you influence the appearance of the plot: +o The `VViieeww' menu toggles optional parts of the plot, such as border lines or a background grid. +o The `PPlloott' menu changes the plotting style. The `33--DD LLiinneess' option is useful for plotting two-dimensional arrays. +o The `SSccaallee' menu allows you to enable logarithmic scal- ing and to enable or disable the scale tics. +o The `CCoonnttoouurr' menu adds contour lines to 3-D plots. You can also resize the plot window as desired. In a 3-D plot, you can use the scroll bars to change your view position. The horizontal scroll bar rotates the plot around the _Z axis, that is, to the left and right. The vertical scroll bar rotates the plot around the _Y axis, that is, up and down. PPlloottttiinngg SSccaallaarrss aanndd CCoommppoossiitteess Besides plotting arrays, DDD also allows you to plot scalars (simple numerical values). This works just like plotting arrays--you select the numerical variable, click on `PPlloott', and here comes the plot. However, plotting a scalar is not very exciting. A plot that contains nothing but a scalar simply draws the scalar's value as a _Y con- stant--that is, a horizontal line. So why care about scalars at all? DDD allows you to com- bine multiple values into one plot. The basic idea is: if you want to plot something that is neither an array nor a scalar, DDD takes all numerical sub-values it can find and plots them all together in one window. For instance, you DDD 3.1.1 1998-12-06 33 ddd(1) ddd(1) can plot all local variables by selecting `DDaattaa-->>DDiissppllaayy LLooccaall VVaarriiaabblleess', followed by `PPlloott'. This will create a plot containing all numerical values as found in the cur- rent local variables. Likewise, you can plot all numeric members contained in a structure by selecting it, followed by `PPlloott'. If you want more control about what to include in a plot and what not, you can use display clusters. (See `CClluuss-- tteerriinngg DDiissppllaayyss', above, for details on clusters.) A com- mon scenario is to plot a one-dimensional array together with the current index position. This is done in three steps: +o Display the array and the index, using `DDiissppllaayy (())'. +o Cluster both displays: select them and choose `UUnnddiisspp-->>CClluusstteerr (())'. +o Plot the cluster by pressing `PPlloott'. Scalars that are displayed together with arrays can be displayed either as vertical lines or horizontal lines. By default, scalars are plotted as horizontal lines. How- ever, if a scalar is a valid index for an array that was previously plotted, it is shown as a vertical line. You can change this initial alignment by selecting the scalar display, followed by `RRoottaattee (())'. PPlloottttiinngg DDiissppllaayy HHiissttoorriieess At each program stop, DDD records the values of all dis- played variables. These _d_i_s_p_l_a_y _h_i_s_t_o_r_i_e_s can be plotted, too. The menu item `PPlloott-->>PPlloott hhiissttoorryy ooff (())' creates a plot that shows all previously recorded values of the selected display. PPrriinnttiinngg PPlloottss If you want to print the plot, select `FFiillee-->>PPrriinntt PPlloott'. This pops up the DDD printing dialog, set up for printing plots. Just as when printing graphs, you have the choice between printing to a printer or a file and setting up appropriate options. The actual printing is also performed by Gnuplot, using the appropriate driver. Please note the following caveats related to printing: +o Creating FFIIGG files requires an appropriate driver built into Gnuplot. Your Gnuplot program may not contain such a driver. In this case, you will have to recompile Gnu- plot, including the line `##ddeeffiinnee FFIIGG' in the Gnuplot `tteerrmm..hh' file. +o The `PPoorrttrraaiitt' option generates an EEPPSS file useful for DDD 3.1.1 1998-12-06 34 ddd(1) ddd(1) inclusion in other documents. The `LLaannddssccaappee' option makes DDD print the plot in the size specified in the `PPaappeerr SSiizzee' option; this is useful for printing on a printer. In `PPoorrttrraaiitt' mode, the `PPaappeerr SSiizzee' option is ignored. +o The PostScript and X11 drivers each have their own set of colors, such that the printed colors may differ from the displayed colors. +o The `SSeelleecctteedd OOnnllyy' option is set by default, such that only the currently selected plot is printed. (If you select multiple plots to be printed, the respective out- puts will all be concatenated, which may not be what you desire.) EEnntteerriinngg PPlloottttiinngg CCoommmmaannddss Via `FFiillee-->>CCoommmmaanndd', you can enter Gnuplot commands directly. Each command entered at the `ggnnuupplloott>>' prompt is passed to Gnuplot, followed by a Gnuplot `rreepplloott' com- mand to update the view. This is useful for advanced Gnu- plot tasks. Here's a simple example. The Gnuplot command `sseett xxrraannggee [[_x_m_i_n::_x_m_a_x]]' sets the horizontal range that will be dis- played to _x_m_i_n..._x_m_a_x. To plot only the elements 10 to 20, enter: gnuplot>sseett xxrraannggee [[1100::2200]] After each command entered, DDD adds a `rreepplloott' command, such that the plot is updated automatically. Here's a more complex example. The following sequence of Gnuplot commands saves the plot in LATEX format: gnuplot>sseett oouuttppuutt ""pplloott..tteexx"" # Set the output filename gnuplot>sseett tteerrmm llaatteexx # Set the output format gnuplot>sseett tteerrmm xx1111 # Show original picture again Due to the implicit `rreepplloott' command, the output is auto- matically written to `pplloott..tteexx' after the `sseett tteerrmm llaatteexx' command. The dialog keeps track of the commands entered; use the arrow keys to restore previous commands. Gnuplot error messages (if any) are also shown in the history area. The interaction between DDD and Gnuplot is logged in the file `$$HHOOMMEE//..dddddd//lloogg'. The DDD `----ttrraaccee' option logs this interaction on standard output. DDD 3.1.1 1998-12-06 35 ddd(1) ddd(1) EExxppoorrttiinngg PPlloott DDaattaa If you want some external program to process the plot data (a stand-alone Gnuplot program or the xxmmggrr program, for instance), you can save the plot data in a file, using `FFiillee-->>SSaavvee DDaattaa AAss'. This pops up a dialog that lets you choose a data file to save the plotted data in. The generated file starts with a few comment lines. The actual data follows in X/Y or X/Y/Z format. It is the same file as processed by Gnuplot. AAnniimmaattiinngg PPlloottss If you want to see how your data evolves in time, you can set a breakpoint whose command sequence ends in a `ccoonntt' command. Each time this "continue" breakpoint is reached, the program stops and DDD updates the displayed values, including the plots. Then, DDD executes the breakpoint command sequence, resuming execution. This way, you can set a "continue" breakpoint at some decisive point within an array-processing algorithm and have DDD display the progress graphically. When your pro- gram has topped for good, you can use `UUnnddoo' and `Redo' to redisplay and examine previous program states. MMAACCHHIINNEE--LLEEVVEELL DDEEBBUUGGGGIINNGG Note: Machine-level support is available with GDB only. Sometimes, it is desirable to examine a program not only at the source level, but also at the machine level. DDD provides special machine code and register windows for this task. EExxaammiinniinngg MMaacchhiinnee CCooddee To enable machine-level support, select `SSoouurrccee-->>DDiissppllaayy MMaacchhiinnee CCooddee'. With machine code 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 function. By moving the sash at the right of the separating line between source and machine code, you can resize the source and machine code windows. The machine code window works very much like the source window. You can set, clear, and change breakpoints by selecting the address and pressing a `BBrreeaakk aatt (())' or `CClleeaarr aatt (())' button; the usual popup menus are also available. Breakpoints and the current execution position are displayed simultaneously in both source and machine code. The `LLooookkuupp (())' button can be used to look up the machine code for a specific function--or the function for a spe- cific address. Just click on the location in one window and press `LLooookkuupp (())' to see the corresponding code in the DDD 3.1.1 1998-12-06 36 ddd(1) ddd(1) other window. The `mmaaxxDDiissaasssseemmbbllee' resource controls how much is to be disassembled. If `mmaaxxDDiissaasssseemmbbllee' is set to 256 (default) and the current function is larger than 256 bytes, DDD only disassembles the first 256 bytes below the current location. You can set the `mmaaxxDDiissaasssseemmbbllee' resource to a larger value if you prefer to have a larger machine code view. If source code is not available, only the machine code window is updated. EExxeeccuuttiioonn 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 `SStteeppii' button. To continue to the next instruction in the current func- tion, click on the `NNeexxttii' button. This is similar to `SStteeppii', but any subroutine calls are executed without stopping. RReeggiisstteerrss 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 `SSttaattuuss-->>RReeggiisstteerrss'. By selecting one of the registers, its name is copied to the argument field. You can use it as value for `DDiissppllaayy (())', for instance, to have its value displayed in the data window. EExxaammiinniinngg MMeemmoorryy Using GDB or DBX, you can examine memory in any of several formats, independently of your program's data types. The item `DDaattaa-->>EExxaammiinnee MMeemmoorryy' pops up a panel where you can choose the format to be shown. You can enter +o a _r_e_p_e_a_t _c_o_u_n_t, a decimal integer that specifies how much memory (counting by units) to display +o a _d_i_s_p_l_a_y _f_o_r_m_a_t--one of ooccttaall Print as integer in octal hheexx Regard the bits of the value as an integer, DDD 3.1.1 1998-12-06 37 ddd(1) ddd(1) and print the integer in hexadecimal. ddeecciimmaall Print as integer in signed decimal. uunnssiiggnneedd Print as integer in unsigned decimal. bbiinnaarryy Print as integer in binary. ffllooaatt Regard the bits of the value as a floating point number and print using typical floating point syntax. aaddddrreessss Print as an address, both absolute in hexadec- imal and as an offset from the nearest preced- ing symbol. iinnssttrruuccttiioonn Print as machine instructions. The _u_n_i_t _s_i_z_e is ignored for this display format. cchhaarr Regard as an integer and print it as a charac- ter constant. ssttrriinngg Print as null-terminated string. The _u_n_i_t _s_i_z_e is ignored for this display format. +o a _u_n_i_t _s_i_z_e--one of bbyytteess Bytes. hhaallffwwoorrddss Halfwords (two bytes). wwoorrddss Words (four bytes). ggiiaannttss Giant words (eight bytes). +o an _a_d_d_r_e_s_s--the starting display address. The expres- sion need not have a pointer value (though it may); it is always interpreted as an integer address of a byte of memory. There are two ways to examine the values: +o You can dump the memory in the debugger console (using `PPrriinntt'). If you repeat the resulting `xx' command by pressing RREETTUURRNN, the following area of memory is shown. +o You can also display the memory dump in the data window (using `DDiissppllaayy'). If you choose to display the values, the values will be updated automatically each time the program stop. DDD 3.1.1 1998-12-06 38 ddd(1) ddd(1) EEDDIITTIINNGG SSOOUURRCCEE CCOODDEE In DDD itself, you cannot change the source file currently displayed. Instead, DDD allows you to invoke a _t_e_x_t _e_d_i_- _t_o_r. To invoke a text editor for the current source file, select the `EEddiitt' button or `SSoouurrccee-->>EEddiitt SSoouurrccee'. By default, DDD tries a number of common editors. You can customize DDD to use your favourite editor via `EEddiitt-->>PPrreeffeerreenncceess-->>HHeellppeerrss-->>EEddiitt SSoouurrcceess'. After the editor has exited, the source code shown is automatically updated. If you have DDD and an editor running in parallel, you can also update the source code manually via `SSoouurrccee-->>RReellooaadd SSoouurrccee'. This reloads the source code shown from the source file. Since DDD automatically reloads the source code if the debugged program has been recompiled, this should seldom be necessary. EENNTTEERRIINNGG CCOOMMMMAANNDDSS In the _d_e_b_u_g_g_e_r _c_o_n_s_o_l_e, you can interact with the command interface of the inferior debugger. Enter commands at the _d_e_b_u_g_g_e_r _p_r_o_m_p_t--that is, `((ggddbb))' for GDB, `((ddbbxx))' for DBX, `>>' for XDB, `>>' and `_t_h_r_e_a_d[[_d_e_p_t_h]]' for JDB, or `((PPyyddbb))' for PYDB, or `DDBB<<>>' for Perl. You can use arbi- trary debugger commands; use the RREETTUURRNN key to enter them. You can _r_e_p_e_a_t previous and next commands by pressing the `UUpp' and `DDoowwnn' arrow keys, respectively. If you enter an empty line, the last command is repeated as well. `CCoomm-- mmaannddss-->>CCoommmmaanndd HHiissttoorryy' shows the command history. You can _s_e_a_r_c_h for previous commands by pressing CCttrrll++BB. This invokes _i_n_c_r_e_m_e_n_t_a_l _s_e_a_r_c_h _m_o_d_e_, where you can enter a string to be searched in previous commands. Press CCttrrll++BB again to repeat the search, or CCttrrll++FF to search in the reverse direction. To return to normal mode, press EESSCC, or use any cursor command. Using GDB and Perl, you can also _c_o_m_p_l_e_t_e commands and arguments by pressing the TTAABB key; pressing the TTAABB key multiple times shows one possible expansion after the other. CCUUSSTTOOMMIIZZIINNGG DDDDDD You can set up your personal DDD preferences by using the `EEddiitt-->>PPrreeffeerreenncceess' menu from the menu bar. These prefer- ences affect your running DDD process only, unless you save these preferences for a later DDD invocation. Fre- quently used preferences can also be found in the individ- ual menus. DDD 3.1.1 1998-12-06 39 ddd(1) ddd(1) FFrreeqquueennttllyy UUsseedd PPrreeffeerreenncceess If you want to run your debugged process in a separate terminal emulator window, set `PPrrooggrraamm-->>RRuunn iinn EExxeeccuuttiioonn WWiinnddooww'. This is useful for programs that have special terminal requirements not provided by the debugger window, as raw keyboard processing or terminal control sequences. By default, DDD finds only complete words. This is 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 `SSoouurrccee-->>FFiinndd WWoorrddss OOnnllyy'. By default, DDD find is case-sensitive. This is conve- nient for case-sensitive programming languages. If you want to find all occurrences, regardless of case, unset `SSoouurrccee-->>FFiinndd CCaassee SSeennssiittiivvee'. If you wish to display machine code of selected functions, set `SSoouurrccee-->>DDiissppllaayy MMaacchhiinnee CCooddee'. This makes DDD run a little slower, so it is disabled by default. Through `EEddiitt-->>PPrreeffeerreenncceess', you can set up more DDD pref- erences, which are discussed here. GGeenneerraall PPrreeffeerreenncceess By default, when you move the pointer over a button, DDD gives a hint on the button's meaning in a small window. This feature is known as _b_u_t_t_o_n _t_i_p_s (also known as _t_o_o_l _t_i_p_s or _b_a_l_l_o_o_n _h_e_l_p). Experienced users may find these hints disturbing; this is why you can disable them by unsetting the `AAuuttoommaattiicc ddiissppllaayy ooff bbuuttttoonn hhiinnttss aass ppooppuupp ttiippss' option. The button hints are also displayed in the status line. Disabling hints in status line (by unsetting the `AAuuttoo-- mmaattiicc ddiissppllaayy ooff bbuuttttoonn hhiinnttss iinn tthhee ssttaattuuss lliinnee' option) and disabling button tips as well makes DDD run slightly faster. By default, when you move the pointer over a variable in the source code, DDD displays the variable value in a small window. Users may find these _v_a_l_u_e _t_i_p_s disturbing; this is why you can disable them by unsetting the `AAuuttoo-- mmaattiicc ddiissppllaayy ooff vvaarriiaabbllee vvaalluueess aass ppooppuupp ttiippss' option. The variable values are also displayed in the status line. Disabling variable values in status line (by unsetting the `AAuuttoommaattiicc ddiissppllaayy ooff vvaarriiaabbllee vvaalluueess iinn tthhee ssttaattuuss lliinnee' option) and disabling value tips as well will make DDD run slightly faster. If you want to use TTAABB key completion in all text windows, DDD 3.1.1 1998-12-06 40 ddd(1) ddd(1) set the `TTAABB kkeeyy ccoommpplleetteess iinn aallll wwiinnddoowwss' option. This is useful if you have pointer-driven keyboard focus (see below) and no special usage for the TTAABB key. Otherwise, the TTAABB key completes in the debugger console only. If you frequently switch between DDD and other multi- window applications, you may like to set the `IIccoonniiffyy aallll wwiinnddoowwss aatt oonnccee' option. This way, all DDD windows are iconified and deiconified as a group. If you want to keep DDD off your desktop during a longer computation, you may like to set the `UUnniiccoonniiffyy wwhheenn rreeaaddyy' option. This way, you can iconify DDD while it is busy on a command (e.g. running a program); DDD will auto- matically pop up again after becoming ready (e.g. after the debugged program has stopped at a breakpoint). If you are bothered by X warnings, you can suppress them by setting the `SSuupppprreessss XX wwaarrnniinnggss' option. If you want to be warned about multiple DDD invocations sharing the same preferences and history files, enable `WWaarrnn iiff MMuullttiippllee DDDDDD IInnssttaanncceess aarree RRuunnnniinngg'. When debugging a modal X application, DDD may interrupt it while it has grabbed the pointer, making further interac- tion impossible. If the `CCoonnttiinnuuee aauuttoommaattiiccaallllyy wwhheenn mmoouussee ppooiinntteerr iiss ffrroozzeenn' option is set, DDD will check after each interaction whether the pointer is grabbed. If this is so, DDD will continue the debugged program such that you can continue to use your display. The _U_n_d_o _B_u_f_f_e_r is the area where DDD stores old program states and commands in order to undo operations. When you are displaying lots of data, the undo buffer can quickly grow. In `UUnnddoo BBuuffffeerr SSiizzee', you can limit the size of the undo buffer. Setting this limit to 00 disables undo altogether. A negative value means to place no limit. The `RReesseett' button restores the most recently saved pref- erences. SSoouurrccee PPrreeffeerreenncceess 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, set the `AAss TTeexxtt CChhaarraacctteerrss' option. This also makes DDD run slightly faster, especially when scrolling. DDD can locate the tool buttons in the command tool (`CCoomm-- mmaanndd TTooooll') or in a _c_o_m_m_a_n_d _t_o_o_l _b_a_r above the program source (`SSoouurrccee WWiinnddooww'). Pick your choice. DDD 3.1.1 1998-12-06 41 ddd(1) ddd(1) 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 `RReeffeerr ttoo ssoouurrcceess bbyy ffuullll ppaatthh nnaammee' option. 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 `FFiinndd wwoorrddss oonnllyy'. By default, DDD find is case-sensitive. This is conve- nient for case-sensitive programming languages. If you want to find all occurrences, regardless of case, unset `FFiinndd ccaassee sseennssiittiivvee'. By default, DDD caches source files in memory. This is convenient for remote debugging, since remote file access may be slow. If you want to reduce memory usage, unset the `CCaacchhee ssoouurrccee ffiilleess' 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 `CCaacchhee mmaacchhiinnee ccooddee' option. If your source code uses a tab width different from 88 (the default), you can set an alternate width using the `TTaabb wwiiddtthh' slider. You can instruct DDD to indent the source code, leaving more room for breakpoints and execution glyphs. This is done using the `SSoouurrccee iinnddeennttaattiioonn' slider. The default value is 00 for no indentation at all. If the source indentation is 55 or higher, DDD will also show line num- bers. Finally, you can instruct DDD to indent the machine code, leaving room for breakpoints and execution glyphs. This is done using the `MMaacchhiinnee ccooddee iinnddeennttaattiioonn' slider. The default value is 44. The `RReesseett' button restores the most recently saved pref- erences. DDaattaa PPrreeffeerreenncceess You can control whether edge hints and edge annotations are displayed. Set or unset the `SShhooww EEddggee HHiinnttss' and `SShhooww EEddggee AAnnnnoottaattiioonnss' option, respectively. By default, DDD disables the title of a dependent display if the name can be deduced from edge annotations. If you DDD 3.1.1 1998-12-06 42 ddd(1) ddd(1) want all dependent displays to have a title, set `SShhooww TTiittlleess ooff DDeeppeennddeenntt DDiissppllaayyss'. To enable a more compact layout, you can set the `CCoommppaacctt LLaayyoouutt' 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 `RRee--llaayyoouutt ggrraapphh aauuttoo-- mmaattiiccaallllyy' option. If automatic layout is enabled, the graph is layouted after each change. If you want DDD to detect aliases, set the `DDeetteecctt AAlliiaasseess' option. Note that alias detection makes DDD run slower. See `EExxaammiinniinngg SShhaarreedd DDaattaa SSttrruuccttuurreess', above, for details on alias detection. By default, DDD displays two-dimensional arrays as tables, aligning the array elements in rows and columns. If you prefer viewing two-dimensional arrays as nested one- dimensional arrays, you can disable the `DDiissppllaayy ttwwoo-- ddiimmeennssiioonnaall aarrrraayyss aass ttaabblleess' option. To facilitate alignment of data displays, you can set the `AAuuttoo--aalliiggnn ddiissppllaayyss' option. If auto-alignment is enabled, displays can be moved on grid positions only. By default, the stacked data window is automatically closed when you delete the last data display. You can keep the data window open by unsetting `CClloossee ddaattaa wwiinnddooww wwhheenn ddeelleettiinngg llaasstt ddiissppllaayy'. In the `GGrriidd SSiizzee' scale, you can change the spacing of grid points. A spacing of 0 disables the grid. Default is 16. The `RReesseett' button restores the most recently saved pref- erences. SSttaarrttuupp PPrreeffeerreenncceess If you change one of the resources in this panel, the change will not take effect immediately. Instead, you can +o save options (using `EEddiitt-->>SSaavvee OOppttiioonnss') to make the change effective for future DDD sessions, +o or restart DDD (using `FFiillee-->>RReessttaarrtt DDDDDD') to make it effective for the restarted DDD session. After having made changes in the panel, DDD will automati- cally offer you to restart itself, such that you can see the changes taking effect. Note that even after DDD 3.1.1 1998-12-06 43 ddd(1) ddd(1) restarting, you still must save options to make the changes permanent. By default, DDD stacks commands, source, and data in one single top-level window. To have separate top-level win- dows for source, data, and debugger console, set the `WWiinn-- ddooww LLaayyoouutt' option to `SSeeppaarraattee WWiinnddoowwss'. See also the `----aattttaacchh--wwiinnddoowwss' and `----sseeppaarraattee--wwiinnddoowwss' options, below. The CCttrrll++CC key can be bound to different actions, each in accordance with a specific style guide. CCooppyy This setting binds CCttrrll++CC to the Copy operation, as specified by the KDE style guide. In this setting, use EESSCC to interrupt the debuggee. IInntteerrrruupptt This (default) setting binds CCttrrll++CC to the Inter- rupt operation, as used in several UNIX command- line programs. In this setting, use CCttrrll++IInnss to copy text to the clipboard. The CCttrrll++AA key can be bound to different actions, too. SSeelleecctt AAllll This (default) setting binds CCttrrll++AA to the Select All operation, as specified by the KDE style guide. In this setting, use HHOOMMEE tp move the cursor to the beginning of a line. BBeeggiinnnniinngg ooff LLiinnee This setting binds CCttrrll++AA to the Beginning of Line operation, as used in several UNIX text-editing programs. In this setting, use CCttrrll++SShhiifftt++AA to select all text. The DDD tool bar buttons can appear in a variety of styles: IImmaaggeess This lets each tool bar button show an image illus- trating the action. CCaappttiioonnss This shows the action name below the image. The default is to have images as well as captions, but you can choose to have only images (saving space) or only cap- tions. If you choose to have neither images nor captions, tool bar buttons are labeled like other buttons, as in DDD 2.x. DDD 3.1.1 1998-12-06 44 ddd(1) ddd(1) Note that this implies that in the stacked window configu- ration, the common tool bar cannot be displayed; it is replaced by two separate tool bars, as in DDD 2.x. If you enable `FFllaatt' buttons (default), the border of tool bar buttons will appear only if the mouse pointer is over them. This latest-and-greatest GUI invention can be dis- abled, such that the button border is always shown. If you enable `CCoolloorr' buttons, tool bar images will be colored when entered. If DDD was built using Motif 2.0 and later, you can also choose a third setting, where but- tons appear in color all the time. By default, the DDD tool bars are located on top of the window. If you prefer the tool bar being located at the bottom, as in DDD 2.x and earlier, enable the `BBoottttoomm' toggle. The bottom setting is only supported for separate tool bars--that is, you must either choose separate win- dows or configure the tool bar to have neither images nor captions. 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 `KKeeyybbooaarrdd FFooccuuss' option on `CClliicckk ttoo TTyyppee'. 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 `DDaattaa SSccrroolllliinngg' option to `PPaannnneerr'. See also the `----ppaannnneedd-- ggrraapphh--eeddiittoorr' and `----ssccrroolllleedd--ggrraapphh--eeddiittoorr' options, below. By default, DDD determines the inferior debugger automati- cally. To change this default, unset `DDeetteerrmmiinnee AAuuttoommaattii-- ccaallllyy' and set the `DDeebbuuggggeerr TTyyppee' option to a specific debugger. See also the `----ggddbb', `----ddbbxx', `----xxddbb', `----jjddbb', `----ppyyddbb', and `----ppeerrll' options, below. If you want the DDD splash screen shown upon startup, enable `DDDDDD SSppllaasshh SSccrreeeenn'. If you want the DDD tips of the day displayed upon startup, enable `TTiipp ooff tthhee DDaayy'. The `RReesseett' button restores the most recently saved pref- erences. DDD 3.1.1 1998-12-06 45 ddd(1) ddd(1) FFoonnttss You can configure the basic DDD fonts at run-time. Each font is specified using two members: +o The _f_o_n_t _f_a_m_i_l_y is an X font specifications, where the initial specification after `_F_a_m_i_l_y'. Thus, a pair `_f_a_m_i_l_y--_w_e_i_g_h_t' usually suffices. +o The _f_o_n_t _s_i_z_e is given as (resolution-independent) 1/10 points. The `BBrroowwssee' button opens a font selection program, where you can select fonts and attributes interactively. Click- ing `qquuiitt' or `sseelleecctt' in the font selector causes all non-default values to be transferred to the DDD font pref- erences panel. The following fonts can be set using the preferences panel: DDeeffaauulltt FFoonntt The default DDD font to use for labels, menus, and buttons. Default is `hheellvveettiiccaa--bboolldd'. VVaarriiaabbllee WWiiddtthh The variable width DDD font to use for help texts and messages. Default is `hheellvveettiiccaa--mmeeddiiuumm'. FFiixxeedd WWiiddtthh The fixed width DDD font to use for source code, the debugger console, text fields, data displays, and the execution window. Default is `lluucciiddaattyyppee-- wwrriitteerr--mmeeddiiuumm'. Just like startup preferences, changes in this panel will not take effect immediately. Instead, you can +o save options (using `EEddiitt-->>SSaavvee OOppttiioonnss') to make the change effective for future DDD sessions, +o or restart DDD (using `FFiillee-->>RReessttaarrtt DDDDDD') to make it effective for the restarted DDD session. After having made changes in the panel, DDD will automati- cally offer you to restart itself, such that you can see the changes taking effect. Note that even after restart- ing, you still must save options to make the changes per- manent. The `RReesseett' button restores the most recently saved pref- erences. DDD 3.1.1 1998-12-06 46 ddd(1) ddd(1) HHeellppeerrss DDD relies on some external applications (called _h_e_l_p_e_r_s) for specific tasks. Through the `HHeellppeerrss' panel, you can choose and customize these applications. In `EEddiitt SSoouurrcceess', you can select an X editor to be invoked via the DDD `EEddiitt' button. `@@FFIILLEE@@' is replaced by the current file name; `@@LLIINNEE@@' is replaced by the cur- rent line. Typical values include `xxeeddiitt @@FFIILLEE@@' or `ggnnuu-- cclliieenntt ++@@LLIINNEE@@ @@FFIILLEE@@'. See also the `eeddiittCCoommmmaanndd' resource, below. In `GGeett CCoorree FFiillee', you can enter a command to get a core file from a running process. `@@FFIILLEE@@' is replaced by the name of the target core file; `@@PPIIDD@@' is replaced by the process ID. A typical value is `ggccoorree --oo @@FFIILLEE@@ @@PPIIDD@@'. If you don't have an appropriate command, leave this value empty: DDD will then kill the debuggee in order to get a core file. See also the `ggeettCCoorreeCCoommmmaanndd' resource, below. `LLiisstt PPrroocceesssseess' is a command to get a list of processes, like `ppss'. The output of this command is shown in the `FFiillee-->>AAttttaacchh ttoo PPrroocceessss' dialog. See also the `ppssCCoomm-- mmaanndd' resource, below. In `EExxeeccuuttiioonn WWiinnddooww', you can enter a command to start a terminal emulator. To this command, DDD appends Bourne shell commands to be executed within the execution window. A simple value is `xxtteerrmm --ee //bbiinn//sshh --cc'. See also the `tteerrmmCCoommmmaanndd' resource, below. `UUnnccoommpprreessss' is the uncompression command used by DDD to uncompress the DDD license and manual pages. The uncom- pression command should be invoked such that it reads from standard input and writes to standard output. A typical value is `gguunnzziipp --cc'. See also the `uunnccoommpprreessssCCoommmmaanndd' resource, below. `WWeebb BBrroowwsseerr' is the command to invoke a WWW browser for the DDD WWW page. `@@UURRLL@@' is replaced by the URL (web page) to be shown. A simple value is `nneettssccaappee @@UURRLL@@'. See also the `wwwwwwCCoommmmaanndd' resource, below. `PPlloott' is the name of a Gnuplot program to invoke. DDD can run Gnuplot in two ways: +o DDD can use an EExxtteerrnnaall PPlloott WWiinnddooww, i.e. the plot win- dow as supplied by Gnuplot. DDD "swallows" the Gnuplot output window into its own user interface. Unfortu- nately, some window managers, notably MWM, have trouble with swallowing techniques. +o DDD can supply a BBuuiillttiinn PPlloott WWiinnddooww instead. This DDD 3.1.1 1998-12-06 47 ddd(1) ddd(1) works with all window managers, but plots are less cus- tomizable (Gnuplot resources are not understood). Pick your choice from the menu. See also the `pplloottCCoomm-- mmaanndd' and `pplloottTTeerrmmTTyyppee' resources, below. SSaavviinngg OOppttiioonnss You can save the current option settings by selecting `EEddiitt-->>SSaavvee OOppttiioonnss'. Options are saved in a file named `..dddddd//iinniitt' in your home directory. If a session _s_e_s_s_i_o_n is active, options will be saved in `$$HHOOMMEE//..dddddd//sseessssiioonnss//_s_e_s_s_i_o_n//iinniitt' instead. OOtthheerr CCuussttoommiizzaattiioonnss Other personal DDD resources can also be set in your `..dddddd//iinniitt' file. See the `RREESSOOUURRCCEESS' section, below. The inferior debugger can be customized via `EEddiitt-->>SSeettttiinnggss'. See the `DDEEBBUUGGGGEERR SSEETTTTIINNGGSS' section, below. DDEEBBUUGGGGEERR SSEETTTTIINNGGSS For most inferior debuggers, you can change its settings using `EEddiitt-->>SSeettttiinnggss'. Using the settings editor, you can determine whether C++ names are to be demangled, how many array elements are to print, and so on. The capabilities of the settings editor depend on the capabilities of your inferior debugger. Clicking on `??' gives an an explanation on the specific item; the GDB doc- umentation gives more details. Use `EEddiitt-->>UUnnddoo' to undo changes. Clicking on `RReesseett' restores the most recently saved settings. Some debugger settings are insensitive and cannot be changed, because doing so would endanger DDD operation. See the `ggddbbIInniittCCoommmmaannddss' and `ddbbxxIInniittCCoommmmaannddss' resources for details. All debugger settings (except source and object paths) are saved with DDD options. UUSSEERR--DDEEFFIINNEEDD AACCTTIIOONNSS DDeeffiinniinngg BBuuttttoonnss To facilitate interaction, you can add own command buttons to DDD. These buttons can be added below the debugger console (`CCoonnssoollee BBuuttttoonnss'), the source window (`SSoouurrccee BBuuttttoonnss'), or the data window (`DDaattaa BBuuttttoonnss'). To define individual buttons, use the _B_u_t_t_o_n _E_d_i_t_o_r, invoked via `CCoommmmaannddss-->>EEddiitt BBuuttttoonnss'. The button editor displays a text, where each line contains the command for DDD 3.1.1 1998-12-06 48 ddd(1) ddd(1) exactly one button. Clicking on `OOKK' creates the appro- priate buttons from the text. If the text is empty (the default), no button is created. As a simple example, assume you want to create a `pprriinntt ii' button. Invoke `CCoommmmaannddss-->>EEddiitt BBuuttttoonnss' and enter a line saying `pprriinntt ii' in the button editor. Then click on `OOKK'. A button named `PPrriinntt ii' will now appear below the debugger console--try it! To remove the button, reopen the button editor, clear the `pprriinntt ii' line and press `OOKK' again. If a button command contains `(())', the string `(())' will automatically be replaced by the contents of the argument field. For instance, a button named `rreettuurrnn (())' will exe- cute the GDB `rreettuurrnn' command with the current content of the argument field as argument. By default, DDD disables buttons whose commands are not supported by the inferior debugger. To enable such but- tons, unset the `EEnnaabbllee ssuuppppoorrtteedd bbuuttttoonnss oonnllyy' toggle in the button editor. DDD also allows you to specify control sequences and spe- cial labels for user-defined buttons. See the examples in `UUsseerr--ddeeffiinneedd BBuuttttoonnss' in the `RREESSOOUURRCCEESS' section, below. DDeeffiinniinngg SSiimmppllee CCoommmmaannddss uussiinngg GGDDBB Aside from breakpoint commands (see `BBrreeaakkppooiinntt ccoommmmaannddss', above), DDD also allows you to store sequences of commands as a user-defined GDB command. A _u_s_e_r_-_d_e_f_i_n_e_d _c_o_m_m_a_n_d is a sequence of GDB commands to which you assign a new name as a command. Using DDD, this is done via the _C_o_m_m_a_n_d _E_d_i_t_o_r, invoked via `CCoommmmaannddss-->>DDeeffiinnee CCoommmmaanndd'. A GDB command is created in five steps: +o Enter the name of the command in the `CCoommmmaanndd' field. Use the drop-down list on the right to select from already defined commands. +o Click on `RReeccoorrdd' to begin the recording of the command sequence. +o Now interact with DDD. While recording, DDD does not execute commands, but simply records them to be executed when the breakpoint is hit. The recorded debugger com- mands are shown in the debugger console. +o To stop the recording, click on `EEnndd' or enter `eenndd' at the GDB prompt. To _c_a_n_c_e_l the recording, click on `IInntteerrrruupptt' or press EESSCC. DDD 3.1.1 1998-12-06 49 ddd(1) ddd(1) +o Click on `EEddiitt >>>>' to edit the recorded commands. When done with editing, click on `EEddiitt <<<<' to close the com- mands editor. After the command is defined, you can enter it at the GDB prompt. You may also click on `AAppppllyy' to apply the given user-defined command. For convenience, you can assign a button to the defined command. Enabling one of the `BBuuttttoonn' locations will add a button with the given command to the specified location. If you want to edit the button, select `CCoommmmaannddss-->>EEddiitt BBuuttttoonnss'; see also `DDeeffiinniinngg BBuuttttoonnss', above. When user-defined GDB commands are executed, the commands of the definition are not printed. An error in any com- mand stops execution of the user-defined command. If used interactively, commands that would ask for confir- mation proceed without asking when used inside a user- defined command. Many GDB commands that normally print messages to say what they are doing omit the messages when used in a user-defined command. To save all command definitions, use `EEddiitt-->>SSaavvee OOppttiioonnss'. DDeeffiinniinngg AArrgguummeenntt CCoommmmaannddss uussiinngg GGDDBB If you want to pass arguments to user-defined commands, you can enable the `(())' toggle button in the Command Edi- tor. Enabling `(())' has two effects: +o While recording commands, all references to the argument field are taken _s_y_m_b_o_l_i_c_a_l_l_y instead of literally. The argument field value is frozen to `$$aarrgg00', which is how GDB denotes the argument of a user-defined command. When GDB executes the command, it will replace `$$aarrgg00' by the current command argument. +o When assigning a button to the command, the command will be suffixed by the current contents of the argument field. While defining a command, you can toggle the `(())' button as you wish to switch between using the argument field symbolically and literally. As an example, let us define a command `ccoonnttuunnttiill' that will set a breakpoint in the given argument and continue execution. +o Enter `ccoonnttuunnttiill' in the `DDeeffiinniittiioonn' field. +o Enable the `(())' toggle button. DDD 3.1.1 1998-12-06 50 ddd(1) ddd(1) +o Now click on `RReeccoorrdd' to start recording. Note that the contents of the argument field change to `$$aarrgg00'. +o Click on `BBrreeaakk aatt (())' to create a breakpoint. Note that the recorded breakpoint command refers to `$$aarrgg00'. +o Click on `CCoonntt' to continue execution. +o Click on `EEnndd' to end recording. Note that the argument field is restored to its original value. +o Finally, click on one of the `BBuuttttoonn' locations. This creates a `CCoonnttuunnttiill (())' button where `(())' will be replaced by the current contents of the argument field-- and thus passed to the `ccoonnttuunnttiill' command. +o You can now either use the `CCoonnttuunnttiill (())' button or enter a `ccoonnttuunnttiill' command at the GDB prompt. (If you plan to use the command frequently, you may wish to define a `ccuu' command, which again calls `ccoonnttuunnttiill' with its argument. This is a nice exercise.) There is a little drawback with argument commands: a user- defined command in GDB has no means to access the argument list as a whole; only the first argument (up to whites- pace) is processed. This may change in future GDB releases. DDeeffiinniinngg CCoommmmaannddss uussiinngg OOtthheerr DDeebbuuggggeerrss If your inferior debugger allows you to define own command sequences, you can also use these user-defined commands within DDD; just enter them at the debugger prompt. However, you may encounter some problems: +o In contrast to the well-documented commands of the infe- rior debugger, DDD does not know what a user-defined command does. This may lead to inconsistencies between DDD and the inferior debugger. For instance, if your the user-defined command `bbpp' sets a breakpoint, DDD may not display it immediately, because DDD does not know that `bbpp' changes the breakpoint state. +o You cannot use DDD ggrraapphh commands within user-defined commands. This is only natural, because user-defined commands are interpreted by the inferior debugger, which does not know about DDD commands. As a solution, DDD provides a simple facility called _a_u_t_o_- _c_o_m_m_a_n_d_s. If DDD receives any output from the inferior debugger in the form `_p_r_e_f_i_x _c_o_m_m_a_n_d', it will interpret _c_o_m_m_a_n_d as if it had been entered at the debugger prompt. _p_r_e_f_i_x is a user-defined string, for example `dddddd:: DDD 3.1.1 1998-12-06 51 ddd(1) ddd(1) Suppose you want to define a command `ggdd' that serves as abbreviation for `ggrraapphh ddiissppllaayy'. All the command ggdd has to do is to issue a string dddddd:: ggrraapphh ddiissppllaayy _a_r_g_u_m_e_n_t where _a_r_g_u_m_e_n_t is the argument given to `ggdd'. Using GDB, this can be achieved using the eecchhoo command. In your $$HHOOMMEE//..ggddbbiinniitt file, insert the lines ddeeffiinnee ggdd eecchhoo dddddd:: ggrraapphh ddiissppllaayy $$aarrgg00\\nn eenndd To complete the setting, you must also set the `aauuttooCCoomm-- mmaannddPPrreeffiixx' resource to the `dddddd:: ' prefix you gave in your command. In `$$HHOOMMEE//..dddddd//iinniitt', write: DDdddd**aauuttooCCoommmmaannddPPrreeffiixx:: dddddd::\\ (Be sure to leave a space after the trailing backslash.) Entering `ggdd ffoooo' will now have the same effect as enter- ing `ggrraapphh ddiissppllaayy ffoooo' at the debugger prompt. Please note: In your commands, you should choose some other prefix than `dddddd:: '. This is because auto-commands raise a security problem, since arbitrary commands can be executed. Just imagine some malicious program issuing a string like `_p_r_e_f_i_x sshheellll rrmm --ffrr $$HHOOMMEE' when being debugged! As a consequence, be sure to choose your own _p_r_e_f_i_x; it must be at least three characters long. QQUUIITTTTIINNGG DDDDDD To exit DDD, select `FFiillee-->>EExxiitt'. You may also type the `qquuiitt' command at the debugger prompt or press CCttrrll++QQ. GDB and XDB also accept the `qq' command or an end-of-file character (usually CCttrrll++DD). Closing the last DDD window will also exit DDD. An interrupt (EESSCC or IInntteerrrruupptt) does not exit from DDD, but rather terminates the action of any debugger command that is in progress and returns to the debugger command level. It is safe to type the interrupt character at any time because the debugger does not allow it to take effect until a time when it is safe. In case an ordinary interrupt does not succeed, you can also use an abort (CCttrrll++\\ or AAbboorrtt), which sends a QUIT signal to the inferior debugger. Use this in emergencies only; the inferior debugger may be left inconsistent or even exit after a QUIT signal. As a last resort--if DDD hangs, for example--, you may DDD 3.1.1 1998-12-06 52 ddd(1) ddd(1) also interrupt DDD itself using an interrupt signal (SIG- INT). This can be done by typing the interrupt character (usually CCttrrll++CC) in the shell DDD was started from, or by using the UNIX `kkiillll' command. An interrupt signal inter- rupts any DDD action; the inferior debugger is interrupted as well. Since this interrupt signal can result in inter- nal inconsistencies, use this as a last resort in emergen- cies only; save your work as soon as possible and restart DDD. PPEERRSSIISSTTEENNTT SSEESSSSIIOONNSS Note: Persistent sessions are supported with GDB running on the local machine only. Support for other DBX, XDB, and JDB is partially implemented; your mileage may vary. If you want to interrupt your current DDD session, you can save its entire DDD state in a file and restore it later. SSaavviinngg SSeessssiioonnss To save a session, select `FFiillee-->>SSaavvee SSeessssiioonn AAss'. You will be asked for +o a symbolic session name _s_e_s_s_i_o_n and +o whether to include a core dump of the debugged program. Including a core dump is necessary for restoring memory contents and the current execution position. After clicking on `SSaavvee', the session is saved in `$$HHOOMMEE//..dddddd//sseessssiioonnss//_s_e_s_s_i_o_n'. After saving the current state as a session, the session becomes _a_c_t_i_v_e. This means that DDD state will be saved as session defaults: +o User options will be saved in `$$HHOOMMEE//..dddddd//sseessssiioonnss//_s_e_s_s_i_o_n//iinniitt' instead of `$$HHOOMMEE//..dddddd//iinniitt'; see `SSaavviinngg OOppttiioonnss', below, for details. +o The DDD command history will be saved in `$$HHOOMMEE//..dddddd//sseessssiioonnss//_s_e_s_s_i_o_n//hhiissttoorryy' instead of `$$HHOOMMEE//..dddddd//hhiissttoorryy'; see `EEnntteerriinngg CCoommmmaannddss', above, for details. To make the current session inactive, open the _d_e_f_a_u_l_t _s_e_s_s_i_o_n named `[[NNoonnee]]'; see below for details on opening sessions. If your program is running, or if you have opened a core file, DDD can include a core file in the session such that the debuggee data will be restored when re-opening it. To get a core file, DDD typically must kill the debuggee. This means that you cannot resume program execution after DDD 3.1.1 1998-12-06 53 ddd(1) ddd(1) saving a session. Depending on your architecture, other options for getting a core file may also be available. If a core file is _n_o_t to be included in the session, DDD data displays are saved as _d_e_f_e_r_r_e_d; that is, they will be restored as soon as program execution reaches the scope in which they were created. OOppeenniinngg SSeessssiioonnss To resume a previously saved session, select `FFiillee-->>OOppeenn SSeessssiioonn' and choose a session name from the list. After clicking on `OOppeenn', the entire DDD state will be restored from the given session. The session named `[[NNoonnee]]' is the _d_e_f_a_u_l_t _s_e_s_s_i_o_n which is active when starting DDD. To save options for default sessions, open the default session and save options; see `SSaavviinngg OOppttiioonnss' below for details. If a the restored session includes a core dump, the pro- gram being debugged will be in the same state at the time the session was saved; in particular, you can examine the program data. However, you will not be able to resume program execution since the environment (open files, resources, etc.) will be lost. However, you can restart the program, re-using the restored breakpoints and data displays. Opening sessions also restores command definitions, but- tons, display shortcuts and the source tab width. This way, you can maintain a different set of definitions for each session. DDeelleettiinngg SSeessssiioonnss To delete sessions that are no longer needed, select `FFiillee-->>OOppeenn SSeessssiioonn' or `FFiillee-->>SSaavvee SSeessssiioonn'. Select the sessions you want to delete and click on `DDeelleettee'. The default session cannot be deleted. SSttaarrttiinngg DDDDDD wwiitthh aa SSeessssiioonn To start-up DDD with a given session named _s_e_s_s_i_o_n instead of the default session, use dddddd ----sseessssiioonn _s_e_s_s_i_o_n There is also a shortcut that opens the session _s_e_s_s_i_o_n and also invokes the inferior debugger on an executable named _s_e_s_s_i_o_n (in case _s_e_s_s_i_o_n cannot be opened): dddddd ==_s_e_s_s_i_o_n DDD 3.1.1 1998-12-06 54 ddd(1) ddd(1) There is no need to give further command-line options when restarting a session, as they will be overridden by the options saved in the session. IINNTTEEGGRRAATTIINNGG DDDDDD You can run DDD as an inferior debugger in other debugger front-ends, combining their special abilities with those of DDD. GGeenneerraall IInnffoorrmmaattiioonn To have DDD run as an inferior debugger in other front- ends, set up your debugger front-end such that `dddddd ----ttttyy' is invoked instead of the inferior debugger. When DDD is invoked using the `----ttttyy' option, it enables its _T_T_Y _i_n_t_e_r_f_a_c_e, taking additional debugger commands from stan- dard input and forwarding debugger output to standard out- put, 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 `--ffuullllnnaammee' option to have GDB report source code positions, the `----ttttyy' option is not required. DDD recognizes the `--ffuullllnnaammee' option, finds that it has been invoked from a debugger front-end and automatically enables the TTY interface. You may also invoke `dddddd ----ttttyy' 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 detects an EOF condition on its standard input. Also, do not try to run DDD with DDD as inferior debugger. Using DDD in TTY mode automatically disables some DDD win- dows, because it is assumed that their facilities are pro- vided by the remote program: +o If DDD is invoked with the `----ttttyy' option, the debugger console is initially disabled, as its facilities are supposed to be provided by the integrating front-end. +o If DDD is invoked with the `--ffuullllnnaammee' option, the debugger console and the source window are initially disabled, as their facilities are supposed to be pro- vided by the integrating front-end. In case of need, you can use the `VViieeww' menu to re-enable these windows. UUssiinngg DDDDDD wwiitthh GGNNUU EEmmaaccss Use `MM--xx ggddbb' or `MM--xx ddbbxx' to start a debugging session. At the prompt, enter `dddddd ----ttttyy', followed by `----ddbbxx' or DDD 3.1.1 1998-12-06 55 ddd(1) ddd(1) `----ggddbb', if required, and the name of the program to be debugged. Proceed as usual. UUssiinngg DDDDDD wwiitthh XXEEmmaaccss Set the variable ggddbb--ccoommmmaanndd--nnaammee to ""dddddd"", by inserting the following line in your $$HHOOMMEE//..eemmaaccss file or evaluating it by pressing EESSCC :: (EESSCC EESSCC for XEmacs 19.13 and ear- lier): ((sseettqq ggddbb--ccoommmmaanndd--nnaammee ""dddddd"")) Use `MM--xx ggddbb' or `MM--xx ggddbbssrrcc' to start a debugging ses- sion. Proceed as usual. UUssiinngg DDDDDD wwiitthh XXXXGGDDBB Invoke xxxxggddbb as xxxxggddbb --ddbb__nnaammee dddddd --ddbb__pprroommpptt ''((ggddbb)) '' UUSSIINNGG DDDDDD WWIITTHH LLEESSSSTTIIFF DDD 2.1.1 and later include a number of hacks that make DDD run with _L_e_s_s_T_i_f_, a free Motif clone, without loss of functionality. Since a DDD binary may be dynamically bound and used with either an OSF/Motif or LessTif library, these _l_e_s_s_t_i_f _h_a_c_k_s can be enabled and disabled at run time. Whether the _l_e_s_s_t_i_f _h_a_c_k_s are included at run-time depends on the setting of the `lleessssTTiiffVVeerrssiioonn' resource. `lleessss-- TTiiffVVeerrssiioonn' indicates the LessTif version against which DDD is linked. For LessTif version _x_._y, its value is _x multiplied by 1000 plus _y--for instance, the value 9955 stands for LessTif 0.95 and the value 11000000 stands for LessTif 1.0. To specify the version number of the LessTif library at DDD invocation, you can also use the option `----lleessssttiiff--vveerrssiioonn _v_e_r_s_i_o_n'. The default value of the `lleessssTTiiffVVeerrssiioonn' resource is derived from the LessTif library DDD was compiled against (or 11000000 when compiled against OSF/Motif). Hence, you normally don't need to worry about the value of this resource. However, if you use a dynamically linked DDD binary with a library other than the one DDD was compiled against, you must specify the version number of the library using this resource. (Unfortunately, DDD cannot detect this at run-time.) Here are a few scenarios to illustrate this scheme: +o Your DDD binary was compiled against OSF/Motif, but you use a LessTif 0.85 dynamic library instead. Invoke DDD with `----lleessssttiiff--vveerrssiioonn 8855'. DDD 3.1.1 1998-12-06 56 ddd(1) ddd(1) +o Your DDD binary was compiled against LessTif, but you use a OSF/Motif dynamic library instead. Invoke DDD with `----lleessssttiiff--vveerrssiioonn 11000000'. +o Your DDD binary was compiled against LessTif 0.85, and you have upgraded to LessTif 0.90. Invoke DDD with `----lleessssttiiff--vveerrssiioonn 9900'. To find out the LessTif or OSF/Motif version DDD was com- piled against, invoke DDD with the `----ccoonnffiigguurraattiioonn' option. In the DDD source, LessTif-specific hacks are controlled by the string `lleessssttiiff__vveerrssiioonn'. RREEMMOOTTEE DDEEBBUUGGGGIINNGG It is possible to have the inferior debugger run on a remote UNIX host. This is useful when the remote host has a slow network connection or when DDD is available on the local host only. Furthermore, the inferior debugger may support debugging a program on a remote host. This is useful when the infe- rior debugger is not available on the remote host--for instance, because the remote system does not have a gen- eral purpose operating system powerful enough to run a full-featured debugger. UUssiinngg DDDDDD wwiitthh aa RReemmoottee DDeebbuuggggeerr In order to run the inferior debugger on a remote host, you need `rreemmsshh' (called `rrsshh' 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 dddddd ----hhoosstt _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 dddddd ----hhoosstt _h_o_s_t_n_a_m_e ----llooggiinn _u_s_e_r_n_a_m_e _r_e_m_o_t_e_-_p_r_o_g_r_a_m or dddddd ----hhoosstt _u_s_e_r_n_a_m_e@@_h_o_s_t_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 DDD 3.1.1 1998-12-06 57 ddd(1) ddd(1) remote home directory). Same applies to remote core files. Also, be sure to specify a remote process id when debugging a running program. +o 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 `----rrhhoosstt' option instead of `----hhoosstt'. This will invoke the remote debugger via an interactive shell on the remote host, which may lead to better results. Note: using `----rrhhoosstt', 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. +o To run the remote program, DDD invokes an `xxtteerrmm' termi- nal emulator on the remote host, giving your current `DDIISSPPLLAAYY' environment variable as address. If the remote host cannot invoke `xxtteerrmm', or does not have access to your X display, start DDD with the `----nnoo--eexxeecc-- wwiinnddooww' option. The program input/output will then go through the DDD debugger console. +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 `----ttrraaccee' option. This prints the shell commands issued by DDD on standard error. +o See also the `rrsshhCCoommmmaanndd' resource, below. UUssiinngg DDDDDD wwiitthh aa RReemmoottee PPrrooggrraamm The GDB debugger allows you to run the _d_e_b_u_g_g_e_d _p_r_o_g_r_a_m on a remote machine (called _r_e_m_o_t_e _t_a_r_g_e_t), while GDB runs on the local machine. The section `RReemmoottee ddeebbuuggggiinngg' in the GDB documentation contains all the details. Basically, the following steps are required: +o Transfer the executable to the remote target. +o Start `ggddbbsseerrvveerr' on the remote target. +o Start DDD using GDB on the local machine, and load the same executable using the 'ffiillee' command. +o Attach to the remote `ggddbbsseerrvveerr' using the 'ttaarrggeett rreemmoottee' command. DDD 3.1.1 1998-12-06 58 ddd(1) ddd(1) The local `..ggddbbiinniitt' file is useful for setting up direc- tory search paths, etc. Of course, you can also combine DDD remote mode and GDB remote mode, running DDD, GDB, and the debugged program each on a different machine. RROOOOTT DDEEBBUUGGGGIINNGG 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; DDD invokes shell commands and even shell scripts, such that all known problems of setuid shell scripts apply. Instead, you should invoke DDD such that a _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 `rroooottggddbb'. Then invoke dddddd ----ddeebbuuggggeerr rroooottggddbb to debug programs with root privileges. Since a program like `rroooottggddbb' grants root privileges to any invoking user, you should give it very limited access. RREESSOOUURRCCEESS DDD understands all of the core X Toolkit resource names and classes. The following resources are specific to DDD. SSeettttiinngg DDDDDD FFoonnttss DDD uses the following resources to set up its fonts: ddeeffaauullttFFoonntt ((class Font) The default DDD font to use for labels, menus, but- tons, etc. The font is specified as an X font spec, where the initial specification after `_F_a_m_- _i_l_y'. Default value is `hheellvveettiiccaa--bboolldd'. To set the default DDD font to, say, hheellvveettiiccaa mmeeddiiuumm, insert a line DDdddd**ddeeffaauullttFFoonntt:: hheellvveettiiccaa--mmeeddiiuumm in your `$$HHOOMMEE//..dddddd//iinniitt' file. ddeeffaauullttFFoonnttSSiizzee ((class FontSize) The size of the default DDD font, in 1/10 points. This resource overrides any font size specification in the `ddeeffaauullttFFoonntt' resource (see above). The default value is 112200 for a 12.0 point font. DDD 3.1.1 1998-12-06 59 ddd(1) ddd(1) vvaarriiaabblleeWWiiddtthhFFoonntt ((class Font) The variable width DDD font to use for help texts and messages. The font is specified as an X font spec, where the initial specification after `_F_a_m_- _i_l_y'. Defaults to `hheellvveettiiccaa--mmeeddiiuumm--rr'. To set the variable width DDD font family to, say, ttiimmeess, insert a line DDdddd**ffiixxeeddWWiiddtthhFFoonntt:: ttiimmeess--mmeeddiiuumm in your `$$HHOOMMEE//..dddddd//iinniitt' file. vvaarriiaabblleeWWiiddtthhFFoonnttSSiizzee ((class FontSize) The size of the variable width DDD font, in 1/10 points. This resource overrides any font size specification in the `vvaarriiaabblleeWWiiddtthhFFoonntt' resource (see above). The default value is 112200 for a 12.0 point font. ffiixxeeddWWiiddtthhFFoonntt ((class Font) The fixed width DDD font to use for source code, the debugger console, text fields, data displays, and the execution window. The font is specified as an X font spec, where the initial specification after `_F_a_m_i_l_y'. Defaults to `lluucciiddaattyyppeewwrriitteerr-- mmeeddiiuumm'. To set the fixed width DDD font family to, say, ccoouurriieerr, insert a line DDdddd**ffiixxeeddWWiiddtthhFFoonntt:: ccoouurriieerr--mmeeddiiuumm in your `$$HHOOMMEE//..dddddd//iinniitt' file. ffiixxeeddWWiiddtthhFFoonnttSSiizzee ((class FontSize) The size of the fixed width DDD font, in 1/10 points. This resource overrides any font size specification in the `ffiixxeeddWWiiddtthhFFoonntt' resource (see above). The default value is 112200 for a 12.0 point font. As all font size resources have the same class (and by default the same value), you can easily change the default DDD font size to, say, 9.0 points by inserting a line DDdddd**FFoonnttSSiizzee:: 9900 in your `$$HHOOMMEE//..dddddd//iinniitt' file. To find out your favorite font size, try `----ffoonnttssiizzee _S_I_Z_E'. This also sets all font sizes to _S_I_Z_E. If you want to set the fonts of specific items, see the DDD 3.1.1 1998-12-06 60 ddd(1) ddd(1) `DDdddd' application defaults file for instructions. SSeettttiinngg DDDDDD CCoolloorrss These are the most important color resources used in DDD: DDdddd**ffoorreeggrroouunndd:: bbllaacckk DDdddd**bbaacckkggrroouunndd:: ggrreeyy DDdddd**XXmmTTeexxtt..bbaacckkggrroouunndd:: ggrreeyy9966 DDdddd**XXmmTTeexxttFFiieelldd..bbaacckkggrroouunndd:: ggrreeyy9966 DDdddd**GGrraapphhEEddiitt..bbaacckkggrroouunndd:: ggrreeyy9966 DDdddd**XXmmLLiisstt..bbaacckkggrroouunndd:: ggrreeyy9966 DDdddd**ggrraapphh__eeddiitt..nnooddeeCCoolloorr:: bbllaacckk DDdddd**ggrraapphh__eeddiitt..eeddggeeCCoolloorr:: bblluuee44 DDdddd**ggrraapphh__eeddiitt..sseelleeccttCCoolloorr:: bbllaacckk DDdddd**ggrraapphh__eeddiitt..ggrriiddCCoolloorr:: bbllaacckk DDdddd**ggrraapphh__eeddiitt..ffrraammeeCCoolloorr:: ggrreeyy5500 DDdddd**ggrraapphh__eeddiitt..oouuttlliinneeCCoolloorr:: ggrreeyy5500 You can copy and modify the appropriate resources to your `$$HHOOMMEE//..dddddd//iinniitt' file. For colors within the data dis- play, things are slightly more complicated--see the `vvssllDDeeffss' resource, below. GGeenneerraall PPrreeffeerreenncceess The following resources determine DDD general behavior. bbuuttttoonnTTiippss ((class TTiippss)) Whether button tips are enabled (`oonn', default) or not (`ooffff'). Button tips are helpful for novices, but may be distracting for experienced users. bbuuttttoonnDDooccss ((class DDooccss)) Whether the display of button hints in the status line is enabled (`oonn', default) or not (`ooffff'). cchheecckkGGrraabbss ((class CChheecckkGGrraabbss)) When debugging a modal X application, DDD may interrupt it while it has grabbed the pointer, mak- ing further interaction impossible. If this is `oonn' (default), DDD will check after each interac- tion whether the pointer is grabbed. If this is so, DDD will automatically continue execution of debugged program. DDD 3.1.1 1998-12-06 61 ddd(1) ddd(1) cchheecckkGGrraabbDDeellaayy ((class CChheecckkGGrraabbDDeellaayy)) The time to wait (in ms) after a debugger command before checking for a grabbed pointer. If DDD sees some pointer event within this delay, the pointer cannot be grabbed and an explicit check for a grabbed pointer is unnecessary. Default is 55000000, or 5 seconds. cchheecckkOOppttiioonnss ((class CChheecckkOOppttiioonnss)) Every _N seconds, where _N is the value of this resource, DDD checks whether the options file has changed. Default is 3300, which means that every 30 seconds, DDD checks for the options file. Setting this resource to 00 disables checking for changed option files. ccuuttCCooppyyPPaasstteeBBiinnddiinnggss ((class BBiinnddiinnggSSttyyllee)) Controls the key bindings for cut, copy, and paste operations. +o If this is `MMoottiiff' (default), Cut/Copy/Paste is on SShhiifftt++DDeell/CCttrrll++IInnss/SShhiifftt++IInnss. This is confor- mant to the Motif style guide. +o If this is `KKDDEE', Cut/Copy/Paste is on CCttrrll++XX/CCttrrll++CC/CCttrrll++VV. This is conformant to the KDE style guide. Note that this means that CCttrrll++CC no longer interrupts the debuggee; use EESSCC instead. ffiilltteerrFFiilleess ((class FFiilltteerrFFiilleess)) If this is `oonn' (default), DDD filters files when opening execution files, core dumps, or source files, such that the selection shows only suitable files. This requires that DDD opens each file, which may take time. If this is `ooffff', DDD always presents all available files. gglloobbaallTTaabbCCoommpplleettiioonn ((class GGlloobbaallTTaabbCCoommpplleettiioonn)) If this is `oonn' (default), the TTAABB key completes arguments in all windows. If this is `ooffff', the TTAABB key completes arguments in the debugger console only. ggrraabbAAccttiioonn ((class ggrraabbAAccttiioonn)) The action to take after having detected a grabbed mouse pointer. This is a list of newline-separated commands. Default is `ccoonntt', meaning to continue the debuggee. Other possible choices include `kkiillll' (killing the debuggee) or `qquuiitt' (exiting DDD). ggrraabbAAccttiioonnDDeellaayy ((class ggrraabbAAccttiioonnDDeellaayy)) The time to wait (in ms) before taking an action DDD 3.1.1 1998-12-06 62 ddd(1) ddd(1) due to having detected a grabbed pointer. During this delay, a working dialog pops up telling the user about imminent execution of the grab action (see the `ggrraabbAAccttiioonn' resource, above). If the pointer grab is released within this delay, the working dialog pops down and no action is taken. This is done to exclude pointer grabs from sources other than the debugged program (including DDD). Default is 1100000000, or 10 seconds. ggrroouuppIIccoonniiffyy ((class GGrroouuppIIccoonniiffyy)) If this is `oonn', (un)iconifying any DDD window causes all other DDD windows to (un)iconify as well. Default is `ooffff', meaning that each DDD win- dow can be iconified on its own. ssaavveeHHiissttoorryyOOnnEExxiitt ((class SSaavveeHHiissttoorryyOOnnEExxiitt)) If `oonn' (default), the command history is automati- cally saved when DDD exits. sseelleeccttAAllllBBiinnddiinnggss ((class BBiinnddiinnggSSttyyllee)) Controls the key bindings for the select all opera- tion. +o If this is `MMoottiiff', Select All on SShhiifftt++CCttrrll++AA. +o If this is `KKDDEE' (default), Select All is on CCttrrll++AA. This is conformant to the KDE style guide. Note that this means that CCttrrll++AA no longer moves the cursor to the beginning of a line; use the HHOOMMEE key instead. ssppllaasshhSSccrreeeenn ((class SSppllaasshhSSccrreeeenn)) If `oonn' (default), show a DDD splash screen upon start-up. ssppllaasshhSSccrreeeennCCoolloorrKKeeyy ((class CCoolloorrKKeeyy)) The color key to use for the DDD splash screen. Possible values include: +o `cc' (default) for a color visual, +o `gg' for a multi-level greyscale visual, +o `gg44' for a 4-level greyscale visual, and +o `mm' for a dithered monochrome visual. +o `bbeesstt' chooses the best visual available for your display. Note: if DDD runs on a monochrome display, or if DDD was compiled without the XPM library, only the monochrome version (`mm') can be shown. DDD 3.1.1 1998-12-06 63 ddd(1) ddd(1) ssttaarrttuuppTTiippss ((class SSttaarrttuuppTTiippss)) Whether a tip of the day is to be shown at startup (`oonn', default) or not (`ooffff'). ssttaarrttuuppTTiippCCoouunntt ((class SSttaarrttuuppTTiippCCoouunntt)) The number _n of the tip of the day to be shown at startup. See also the `ttiipp_n' resources. ssuupppprreessssWWaarrnniinnggss ((class SSuupppprreessssWWaarrnniinnggss)) If `oonn', 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 `ooffff'. ttiipp_n (_c_l_a_s_s TTiipp)) The tip of the day numbered _n (a string). mmaaxxUUnnddooDDeepptthh ((class MMaaxxUUnnddooDDeepptthh)) The maximum number of entries in the undo buffer. This limits the number of actions that can be undone, and the number of states that can be shown in historic mode. Useful for limiting DDD memory usage. A negative value (default) means to place no limit. mmaaxxUUnnddooSSiizzee ((class MMaaxxUUnnddooSSiizzee)) The maximum memory usage (in bytes) of the undo buffer. Useful for limiting DDD memory usage. A negative value means to place no limit. Default is 22000000000000. uunniiccoonniiffyyWWhheennRReeaaddyy ((class UUnniiccoonniiffyyWWhheennRReeaaddyy)) If this is `oonn' (default), the DDD windows are uni- conified automatically whenever GDB becomes ready. This way, you can iconify DDD during some longer operation and have it uniconify itself as soon as the program stops. Setting this to `ooffff' leaves the DDD windows iconified. vvaalluueeTTiippss ((class TTiippss)) Whether value tips are enabled (`oonn', default) or not (`ooffff'). Value tips affect DDD performance and may be distracting for some experienced users. vvaalluueeDDooccss ((class DDooccss)) Whether the display of variable values in the sta- tus line is enabled (`oonn', default) or not (`ooffff'). wwaarrnnIIffLLoocckkeedd ((class WWaarrnnIIffLLoocckkeedd)) Whether to warn if multiple DDD instances are run- ning (`oonn') or not (`ooffff', default). SSoouurrccee WWiinnddooww The following resources determine the DDD source window. DDD 3.1.1 1998-12-06 64 ddd(1) ddd(1) ccaacchheeGGllyypphhIImmaaggeess ((class CCaacchheeMMaacchhiinneeCCooddee)) Whether to cache (share) glyph images (`oonn') or not (`ooffff'). Caching glyph images requires less X resources, but has been reported to fail with Motif 2.1 on XFree86 servers. Default is `ooffff' for Motif 2.1 or later on Linux machines, and `oonn' otherwise. ccaacchheeMMaacchhiinneeCCooddee ((class CCaacchheeMMaacchhiinneeCCooddee)) Whether to cache disassembled machine code (`oonn', default) or not (`ooffff'). Caching machine code requires more memory, but makes DDD run faster. ccaacchheeSSoouurrcceeFFiilleess ((class CCaacchheeSSoouurrcceeFFiilleess)) Whether to cache source files (`oonn', default) or not (`ooffff'). Caching source files requires more memory, but makes DDD run faster. ddiissaasssseemmbbllee ((class DDiissaasssseemmbbllee)) If this is `oonn', the source code is automatically disassembled. The default is `ooffff'. See also the `----ddiissaasssseemmbbllee' and `----nnoo--ddiissaasssseemmbbllee' options, below. ddiissppllaayyGGllyypphhss ((class DDiissppllaayyGGllyypphhss)) If this is `oonn', the current execution position and breakpoints are displayed as glyphs; otherwise, they are shown through characters in the text. The default is `oonn'. See also the `----ggllyypphhss' and `----nnoo--ggllyypphhss' options, below. ddiissppllaayyLLiinneeNNuummbbeerrss ((class DDiissppllaayyLLiinneeNNuummbbeerrss)) If this is `oonn', lines in the source text are pre- fixed with their respective line number. The default is `ooffff'. ffiinnddCCaasseeSSeennssiittiivvee ((class FFiinnddCCaasseeSSeennssiittiivvee)) If this is `oonn' (default), the `FFiinndd' commands are case-sensitive. Otherwise, occurrences are found regardless of case. ffiinnddWWoorrddssOOnnllyy ((class FFiinnddWWoorrddssOOnnllyy)) If this is `oonn' (default), the `FFiinndd' commands find complete words only. Otherwise, arbitrary occur- rences are found. ggllyypphhUUppddaatteeDDeellaayy ((class GGllyypphhUUppddaatteeDDeellaayy)) A delay (in ms) that says how much time to wait before updating glyphs while scrolling the source text. A small value results in glyphs being scrolled with the text, a large value disables glyphs while scrolling and makes scrolling faster. Default: 1100. DDD 3.1.1 1998-12-06 65 ddd(1) ddd(1) iinnddeennttCCooddee ((class IInnddeenntt)) The number of columns to indent the machine code, such that there is enough place to display break- point locations. Default: 44. iinnddeennttSSoouurrccee ((class IInnddeenntt)) The number of columns to indent the source code, such that there is enough place to display break- point locations. Default: 00. iinnddeennttSSccrriipptt ((class IInnddeenntt)) The minimum indentation for script languages, such as Perl and Python. Default: 44. lliinneeNNuummbbeerrWWiiddtthh ((class LLiinneeNNuummbbeerrWWiiddtthh)) The number of columns to use for line numbers (if displaying line numbers is enabled). Line numbers wider than this value extend into the breakpoint space. Default: 44. lliinneessAAbboovveeCCuurrssoorr ((class LLiinneessAAbboovveeCCuurrssoorr)) The minimum number of lines to show before the cur- rent location. Default is 22. lliinneessBBeelloowwCCuurrssoorr ((class LLiinneessBBeelloowwCCuurrssoorr)) The minimum number of lines to show after the cur- rent location. Default is 33. mmaaxxDDiissaasssseemmbbllee ((class MMaaxxDDiissaasssseemmbbllee)) Maximum number of bytes to disassemble (default: 225566). If this is zero, the entire current function is disassembled. mmaaxxGGllyypphhss ((class MMaaxxGGllyypphhss)) The maximum number of glyphs to be displayed (default: 1100). Raising this value causes more glyphs to be allocated, possibly wasting resources that are never needed. ssoouurrcceeEEddiittiinngg ((class SSoouurrcceeEEddiittiinngg)) If this is `oonn', the displayed source code becomes editable. This is an experimental feature and may become obsolete in future DDD releases. Default if `ooffff'. ttaabbWWiiddtthh ((class TTaabbWWiiddtthh)) The tab width used in the source window (default: 88) uusseeSSoouurrcceePPaatthh ((class UUsseeSSoouurrcceePPaatthh)) If this is `ooffff' (default), the inferior debugger refers to source code locations only by their base names. If this is `oonn' (default), DDD uses the full source code paths. DDD 3.1.1 1998-12-06 66 ddd(1) ddd(1) WWiinnddooww CCrreeaattiioonn aanndd LLaayyoouutt The following resources determine DDD window creation and layout as well as the interaction with the X window man- ager. aauuttooRRaaiisseeTTooooll ((class AAuuttooRRaaiisseeTTooooll)) If `oonn' (default), DDD will always keep the command tool on top of other DDD windows. If this setting interferes with your window manager, or if your window manager keeps the command tool on top any- way, set this resource to `ooffff'. aauuttooRRaaiisseeMMeennuu ((class AAuuttooRRaaiisseeMMeennuu)) If `oonn' (default), DDD will always keep the pull down menu on top of the DDD main window. If this setting interferes with your window manager, or if your window manager does not auto-raise windows, set this resource to `ooffff': DDdddd**aauuttooRRaaiisseeMMeennuu:: ooffff ccoolloorrWWMMIIccoonnss ((class CCoolloorrWWMMIIccoonnss)) If `oonn' (default), DDD uses multi-color icons. If your window manager has trouble with multi-color icons, set this resource to `ooffff' and DDD will use black-and-white icons instead. ddeeccoorraatteeTTooooll ((class DDeeccoorraattee)) This resource controls the decoration of the com- mand tool. +o If this is `ooffff', the command tool is created as a _t_r_a_n_s_i_e_n_t _w_i_n_d_o_w. Several window managers keep transient windows automatically on top of their parents, which is appropriate for the command tool. However, your window manager may be con- figured not to decorate transient windows, which means that you cannot easily move the command tool around. +o If this is `oonn', DDD realizes the command tool as a _t_o_p_-_l_e_v_e_l _w_i_n_d_o_w. Such windows are always dec- orated by the window manager. However, top-level windows are not automatically kept on top of other windows, such that you may wish to set the `aauuttooRRaaiisseeTTooooll' resource, too. +o If this is `aauuttoo' (default), DDD checks whether the window manager decorates transients. If yes, the command tool is realized as a transient win- dow (as in the `ooffff' setting); if no, the command tool is realized as a top-level window (as in the `oonn' setting). Hence, the command tool is always DDD 3.1.1 1998-12-06 67 ddd(1) ddd(1) decorated using the "best" method, but the extra check takes some time. ooppeennDDaattaaWWiinnddooww ((class WWiinnddooww)) If `ooffff' (default), the data window is closed upon start-up. ooppeennDDeebbuuggggeerrCCoonnssoollee ((class WWiinnddooww)) If `ooffff', the debugger console is closed upon start-up. ooppeennSSoouurrcceeWWiinnddooww ((class WWiinnddooww)) If `ooffff', the source window is closed upon start- up. sseeppaarraatteeDDaattaaWWiinnddooww ((class SSeeppaarraattee)) If `oonn', the data window and the debugger console are realized in different top-level windows. If `ooffff' (default), the data window is attached to the debugger console. See also the `----aattttaacchh--wwiinnddoowwss' and `----aattttaacchh--ddaattaa--wwiinnddooww' options, below. sseeppaarraatteeEExxeeccWWiinnddooww ((class SSeeppaarraattee)) If `oonn', the debugged program is executed in a sep- arate execution window. If `ooffff' (default), the debugged program is executed in the console window. See also the `----eexxeecc--wwiinnddooww' and `----nnoo--eexxeecc--wwiinnddooww' options, below. sseeppaarraatteeSSoouurrcceeWWiinnddooww ((class SSeeppaarraattee)) If `oonn', the source window and the debugger console are realized in different top-level windows. If `ooffff' (default), the source window is attached to the debugger console. See also the `----aattttaacchh-- wwiinnddoowwss' and `----aattttaacchh--ssoouurrccee--wwiinnddooww' options, below. ssttaattuussAAttBBoottttoomm ((class SSttaattuussAAttBBoottttoomm)) If `oonn' (default), the status line is placed at the bottom of the DDD source window. If `ooffff', the status line is placed at the top of the DDD source window (as in DDD 1.x). See also the `----ssttaattuuss--aatt-- bboottttoomm' and `----ssttaattuuss--aatt--ttoopp' options, below. ssttiicckkyyTTooooll ((class SSttiicckkyyTTooooll)) If `oonn' (default), the command tool automatically follows every movement of the source window. When- ever the source window is moved, the command tool is moved by the same offset such that its position relative to the source window remains unchanged. If `ooffff', the command tool does not follow source window movements. DDD 3.1.1 1998-12-06 68 ddd(1) ddd(1) ttrraannssiieennttDDiiaallooggss ((class TTrraannssiieennttDDiiaallooggss)) If `oonn' (default), all dialogs are created as tran- sient windows--that is, they always stay on top of the main DDD windows, and they iconify with it. If `ooffff', the important selection dialogs, such as the breakpoint and display editors, are created as top- level windows on their own, and may be obscured by the DDD main windows. DDeebbuuggggeerr SSeettttiinnggss The following resources determine the inferior debugger. aauuttooCCoommmmaannddss ((class AAuuttooCCoommmmaannddss)) If this is `oonn' (default), each line output by the inferior debugger beginning with the value of the `aauuttooCCoommmmaannddPPrreeffiixx' resource (see below) will be interpreted as DDD command and executed. Useful for user-defined commands; see `UUSSEERR--DDEEFFIINNEEDD CCOOMM-- MMAANNDDSS', above. aauuttooCCoommmmaannddPPrreeffiixx ((class AAuuttooCCoommmmaannddPPrreeffiixx)) The prefix for auto-commands. By default, an empty string, meaning to generate a new prefix for each DDD session. If this is set to `dddddd:: ', for exam- ple, each GDB output in the form `dddddd:: _c_o_m_m_a_n_d' will cause DDD to execute _c_o_m_m_a_n_d. aauuttooDDeebbuuggggeerr ((class AAuuttooDDeebbuuggggeerr)) If this is `oonn' (default), DDD will attempt to determine the debugger type from its arguments, possibly overriding the `ddeebbuuggggeerr' resource (see below). If this is `ooffff', DDD will invoke the debugger specified by the `ddeebbuuggggeerr' resource regardless of DDD arguments. bblloocckkTTTTYYIInnppuutt ((class BBlloocckkTTTTYYIInnppuutt)) Whether DDD should block when reading data from the inferior debugger via the pseudo-tty interface. Some systems _r_e_q_u_i_r_e this, such as Linux with libc 5.4.33 and earlier; set it to `oonn'. Some other systems _p_r_o_h_i_b_i_t this, such as Linux with GNU libc 6 and later; set it to `ooffff'. The value `aauuttoo' (default) will always select the "best" choice (that is, the best choice known to the DDD develop- ers). ddbbxxIInniittCCoommmmaannddss ((class IInniittCCoommmmaannddss)) This string contains a list of newline-separated commands that are initially sent to DBX. By default, it is empty. Do not use this resource to customize DBX; instead, use a personal `$$HHOOMMEE//..ddbbxxiinniitt' or `$$HHOOMMEE//..ddbbxxrrcc' file. See your DBX documentation for details. DDD 3.1.1 1998-12-06 69 ddd(1) ddd(1) ddbbxxSSeettttiinnggss ((class SSeettttiinnggss)) This string contains a list of newline-separated commands that are also initially sent to DBX. By default, it is empty. ddeebbuuggggeerr ((class DDeebbuuggggeerr)) The type of the inferior debugger to invoke (`ggddbb', `ddbbxx', `xxddbb', `jjddbb', `ppyyddbb', or `ppeerrll'). This resource is usually set through the `----ggddbb', `----ddbbxx', `----xxddbb', `----jjddbb', `----ppyyddbb', and `----ppeerrll', options; see below for details. ddeebbuuggggeerrCCoommmmaanndd ((class DDeebbuuggggeerrCCoommmmaanndd)) The name under which the inferior debugger is to be invoked. If this string is empty, the debugger type (`ddeebbuuggggeerr' resource) is used. This resource is usually set through the `----ddeebbuuggggeerr' option; see below for details. ddeebbuuggggeerrHHoosstt ((class DDeebbuuggggeerrHHoosstt)) The host where the inferior debugger is to be exe- cuted; an empty string (default) means the local host. See the `----hhoosstt' option, below, and `RREEMMOOTTEE DDEEBBUUGGGGIINNGG', above. ddeebbuuggggeerrHHoossttLLooggiinn ((class DDeebbuuggggeerrHHoossttLLooggiinn)) The login user name on the remote host; an empty string (default) means using the local user name. See the `----llooggiinn' option, below, and `RREEMMOOTTEE DDEEBBUUGG-- GGIINNGG', above. ddeebbuuggggeerrRRHHoosstt ((class DDeebbuuggggeerrRRHHoosstt)) The host where the inferior debugger is to be exe- cuted; an empty string (default) means to use the `ddeebbuuggggeerrHHoosstt' resource. In contrast to `ddeebbuuggggeerr-- HHoosstt', using this resource causes DDD to login interactively to the remote host and invoke the inferior debugger from the remote shell. See also the `----rrhhoosstt' option, below, and `RREEMMOOTTEE DDEEBBUUGG-- GGIINNGG', above. ddiissppllaayyTTiimmeeoouutt ((class DDiissppllaayyTTiimmeeoouutt)) The time (in ms) to wait for the inferior debugger to finish a partial display information. Default is 22000000. ffuullllNNaammeeMMooddee ((class TTTTYYMMooddee)) If this is `oonn', DDD reports the current source position on standard output in GDB `--ffuullllnnaammee' for- mat. As a side effect, the source window is dis- abled by default. See also the `----ffuullllnnaammee' option, below. DDD 3.1.1 1998-12-06 70 ddd(1) ddd(1) ggddbbIInniittCCoommmmaannddss ((class IInniittCCoommmmaannddss)) This string contains a list of newline-separated commands that are initially sent to GDB. As a side-effect, all settings specified in this resource are considered fixed and cannot be changed through the GDB settings panel, unless preceded by white space. By default, the `ggddbbIInniittCCoommmmaannddss' resource contains some settings vital to DDD: DDdddd**ggddbbIInniittCCoommmmaannddss:: \\ sseett hheeiigghhtt 00\\nn\\ sseett wwiiddtthh 00\\nn\\ sseett vveerrbboossee ooffff\\nn\\ sseett pprroommpptt ((ggddbb)) \\nn While the `sseett hheeiigghhtt', `sseett wwiiddtthh', and `sseett pprroommpptt' settings are fixed, the `sseett vveerrbboossee' set- tings can be changed through the GDB settings panel (although being reset upon each new DDD invoca- tion). Do not use this resource to customize GDB; instead, use a personal `$$HHOOMMEE//..ggddbbiinniitt' file. See your GDB documentation for details. ggddbbSSeettttiinnggss ((class SSeettttiinnggss)) This string contains a list of newline-separated commands that are also initially sent to GDB. Its default value is DDdddd**ggddbbSSeettttiinnggss:: \\ sseett pprriinntt aassmm--ddeemmaannggllee oonn\\nn This resource is used to save and restore the debugger settings. jjddbbIInniittCCoommmmaannddss ((class IInniittCCoommmmaannddss)) This string contains a list of newline-separated commands that are initially sent to JDB. This resource may be used to customize JDB. By default, it is empty. jjddbbSSeettttiinnggss ((class SSeettttiinnggss)) This string contains a list of newline-separated commands that are also initially sent to JDB. By default, it is empty. This resource is used by DDD to save and restore JDB settings. ooppeennSSeelleeccttiioonn ((class OOppeennSSeelleeccttiioonn)) If this is `oonn', DDD invoked without argument checks whether the current selection or clipboard contains the file name or URL of an executable pro- gram. If this is so, DDD will automatically open DDD 3.1.1 1998-12-06 71 ddd(1) ddd(1) this program for debugging. If this resource is `ooffff' (default), DDD invoked without arguments will always start without a debugged program. ppeerrllIInniittCCoommmmaannddss ((class IInniittCCoommmmaannddss)) This string contains a list of newline-separated commands that are initially sent to the Perl debug- ger. By default, it is empty. This resource may be used to customize the Perl debugger. ppyyddbbSSeettttiinnggss ((class SSeettttiinnggss)) This string contains a list of newline-separated commands that are also initially sent to the Perl debugger. By default, it is empty. This resource is used by DDD to save and restore Perl debugger settings. ppyyddbbIInniittCCoommmmaannddss ((class IInniittCCoommmmaannddss)) This string contains a list of newline-separated commands that are initially sent to PYDB. By default, it is empty. This resource may be used to customize PYDB. ppyyddbbSSeettttiinnggss ((class SSeettttiinnggss)) This string contains a list of newline-separated commands that are also initially sent to PYDB. By default, it is empty. This resource is used by DDD to save and restore PYDB settings. ppoossiittiioonnTTiimmeeoouutt ((class PPoossiittiioonnTTiimmeeoouutt)) The time (in ms) to wait for the inferior debugger to finish a partial position information. Default is 550000. qquueessttiioonnTTiimmeeoouutt ((class QQuueessttiioonnTTiimmeeoouutt)) The time (in seconds) to wait for the inferior debugger to reply. Default is 1100. rrHHoossttIInniittCCoommmmaannddss ((class RRHHoossttIInniittCCoommmmaannddss)) These commands are initially executed in a remote interactive session, using the `----rrhhoosstt' option. By default, it sets up the remote terminal such that it suits DDD: DDdddd**rrHHoossttIInniittCCoommmmaannddss:: ssttttyy --eecchhoo --oonnllccrr You may add other commands here--for instance, to set the executable path or to invoke a suitable shell. DDD 3.1.1 1998-12-06 72 ddd(1) ddd(1) ssoouurrcceeIInniittCCoommmmaannddss ((class SSoouurrcceeIInniittCCoommmmaannddss)) If `oonn' (default), DDD writes all GDB initializa- tion commands into a temporary file and makes GDB read this file, rather than sending each initial- ization command separately. This results in faster startup (especially if you have several user- defined commands). If `ooffff', DDD makes GDB process each command separately. ssyynncchhrroonnoouussDDeebbuuggggeerr ((class SSyynncchhrroonnoouussDDeebbuuggggeerr)) If `oonn', X events are not processed while the debugger is busy. This may result in slightly bet- ter performance on single-processor systems. See also the `----ssyynncc--ddeebbuuggggeerr' option, below. tteerrmmiinnaatteeOOnnEEOOFF ((class TTeerrmmiinnaatteeOOnnEEOOFF)) If `oonn', DDD terminates the inferior debugger when DDD detects an EOF condition (that is, as soon as the inferior debugger closes its output channel). This was the default behavior in DDD 2.x and ear- lier. If `ooffff' (default), DDD takes no special action. ttttyyMMooddee ((class TTTTYYMMooddee)) If `oonn', enable TTY interface, taking additional debugger commands from standard input and forward- ing debugger output on standard output. As a side effect, the debugger console is disabled by default. See also the `----ttttyy' and `----ffuullllnnaammee' options, below. uusseeTTTTYYCCoommmmaanndd ((class UUsseeTTTTYYCCoommmmaanndd)) If `oonn', use the GDB `ttttyy' command for redirecting input/output to the separate execution window. If `ooffff', use explicit redirection through shell redi- rection operators `<<' and `>>'. The default is `ooffff' (explicit redirection), since on some sys- tems, the `ttttyy' command does not work properly on some GDB versions. xxddbbIInniittCCoommmmaannddss ((class IInniittCCoommmmaannddss)) This string contains a list of newline-separated commands that are initially sent to XDB. By default, it is empty. Do not use this resource to customize DBX; instead, use a personal `$$HHOOMMEE//..xxddbbrrcc' file. See your XDB documentation for details. xxddbbSSeettttiinnggss ((class SSeettttiinnggss)) This string contains a list of newline-separated commands that are also initially sent to XDB. By default, it is empty. DDD 3.1.1 1998-12-06 73 ddd(1) ddd(1) UUsseerr--ddeeffiinneedd BBuuttttoonnss The following resources can be used to create and control tool bars and user-defined buttons. aaccttiivveeBBuuttttoonnCCoolloorrKKeeyy ((class CCoolloorrKKeeyy)) The XPM color key to use for the images of active buttons (entered or armed). `cc' means color, `gg' (default) means grey, and `mm' means monochrome. bbuuttttoonnCCaappttiioonnss ((class BBuuttttoonnCCaappttiioonnss)) Whether the tool bar buttons should be shown using captions (`oonn', default) or not (`ooffff'). If nei- ther captions nor images are enabled, tool bar but- tons are shown using ordinary labels. See also `bbuuttttoonnIImmaaggeess', below. bbuuttttoonnCCaappttiioonnGGeeoommeettrryy ((class BBuuttttoonnCCaappttiioonnGGeeoommeettrryy)) The geometry of the caption subimage within the button icons. Default is `2299xx77++00--00'. bbuuttttoonnIImmaaggeess ((class BBuuttttoonnIImmaaggeess)) Whether the tool bar buttons should be shown using images (`oonn', default) or not (`ooffff'). If neither captions nor images are enabled, tool bar buttons are shown using ordinary labels. See also `bbuuttttoonn-- CCaappttiioonnss', above. bbuuttttoonnIImmaaggeeGGeeoommeettrryy ((class BBuuttttoonnIImmaaggeeGGeeoommeettrryy)) The geometry of the image within the button icon. Default is `2255xx2211++22++00'. bbuuttttoonnCCoolloorrKKeeyy ((class CCoolloorrKKeeyy)) The XPM color key to use for the images of inactive buttons (non-entered or insensitive). `cc' means color, `gg' (default) means grey, and `mm' means monochrome. ccoommmmaannddTToooollBBaarr ((class TToooollBBaarr)) Whether the tool buttons (see the `ttoooollBBuuttttoonnss' resource, below) should be shown in a tool bar above the source window (`oonn') or within the com- mand tool (`ooffff', default). Enabling the command tool bar disables the command tool and vice versa. ccoommmmoonnTToooollBBaarr ((class TToooollBBaarr)) Whether the tool bar buttons should be shown in one common tool bar at the top of the common DDD window (`oonn', default), or whether they should be placed in two separate tool bars, one for data, and one for source operations, as in DDD 2.x (`ooffff'). ccoonnssoolleeBBuuttttoonnss ((class BBuuttttoonnss)) A newline-separated list of buttons to be added under the debugger console. Each button issues the DDD 3.1.1 1998-12-06 74 ddd(1) ddd(1) command given by its name. The following characters have special meanings: +o Commands ending with '......' insert their name, followed by a space, in the debugger console. +o Commands ending with a control character (that is, `^^' followed by a letter or `??') insert the given control character. +o The string `(())' is replaced by the current con- tents of the argument field `(())'. +o The string specified in the `llaabbeellDDeelliimmiitteerr' resource (usually `////') separates the command name from the button label. If no button label is specified, the capitalized command will be used as button label. The following button names are reserved: AAppppllyy Send the given command to the debugger. BBaacckk Lookup previously selected source posi- tion. CClleeaarr Clear current command CCoommpplleettee Complete current command. EEddiitt Edit current source file. FFoorrwwaarrdd Lookup next selected source position. MMaakkee Invoke the `mmaakkee' program, using the most recently given arguments. NNeexxtt Show next command NNoo Answer current debugger prompt with `nnoo'. This button is visible only if the debug- ger asks a yes/no question. PPrreevv Show previous command RReellooaadd Reload source file. YYeess Answer current debugger prompt with `yyeess'. This button is visible only if the debugger asks a yes/no question. The default resource value is empty--no console DDD 3.1.1 1998-12-06 75 ddd(1) ddd(1) buttons are created. Here are some examples to insert into your `$$HHOOMMEE//..dddddd//iinniitt' file. These are the settings of DDD 1.x: DDdddd**ccoonnssoolleeBBuuttttoonnss:: YYeess\\nnNNoo\\nnbbrreeaakk^^CC This setting creates some more buttons: DDdddd**ccoonnssoolleeBBuuttttoonnss:: \\ YYeess\\nnNNoo\\nnrruunn\\nnCClleeaarr\\nnPPrreevv\\nnNNeexxtt\\nnAAppppllyy\\nnbbrreeaakk^^CC See also the `ddaattaaBBuuttttoonnss', `ssoouurrcceeBBuuttttoonnss' and `ttoooollBBuuttttoonnss' resources, below. ddaattaaBBuuttttoonnss ((class BBuuttttoonnss)) A newline-separated list of buttons to be added under the data display. Each button issues the command given by its name. See the `ccoonnssoolleeBBuutt-- ttoonnss' resource, above, for details on button syn- tax. The default resource value is empty--no source but- tons are created. ffllaattTToooollbbaarrBBuuttttoonnss ((class FFllaattBBuuttttoonnss)) If `oonn' (default), all tool bar buttons with images or captions are given a `flat' appearance--the 3-D border only shows up when the pointer is over the icon. If `ooffff', the 3-D border is shown all the time. ffllaattDDiiaallooggBBuuttttoonnss ((class FFllaattBBuuttttoonnss)) If `oonn' (default), all dialog buttons with images or captions are given a `flat' appearance--the 3-D border only shows up when the pointer is over the icon. If `ooffff', the 3-D border is shown all the time. llaabbeellDDeelliimmiitteerr ((class LLaabbeellDDeelliimmiitteerr)) The string used to separate labels from commands and shortcuts. Default is `////'. ssoouurrcceeBBuuttttoonnss ((class BBuuttttoonnss)) A newline-separated list of buttons to be added under the debugger console. Each button issues the command given by its name. See the `ccoonnssoolleeBBuutt-- ttoonnss' resource, above, for details on button syn- tax. The default resource value is empty--no source but- tons are created. DDD 3.1.1 1998-12-06 76 ddd(1) ddd(1) Here are some example to insert into your `$$HHOOMMEE//..dddddd//iinniitt' file. These are the settings of DDD 1.x: DDdddd**ssoouurrcceeBBuuttttoonnss:: \\ rruunn\\nnsstteepp\\nnnneexxtt\\nnsstteeppii\\nnnneexxttii\\nnccoonntt\\nn\\ ffiinniisshh\\nnkkiillll\\nnuupp\\nnddoowwnn\\nn\\ BBaacckk\\nnFFoorrwwaarrdd\\nnEEddiitt\\nniinntteerrrruupptt^^CC This setting creates some buttons which are not found on the command tool: DDdddd**ssoouurrcceeBBuuttttoonnss:: \\ pprriinntt **(())\\nnggrraapphh ddiissppllaayy **(())\\nnpprriinntt //xx (())\\nn\\ wwhhaattiiss (())\\nnppttyyppee (())\\nnwwaattcchh (())\\nnuunnttiill\\nnsshheellll An even more professional setting uses customized button labels. DDdddd**ssoouurrcceeBBuuttttoonnss:: \\ pprriinntt **(((()))) //// PPrriinntt **(())\\nn\\ ggrraapphh ddiissppllaayy **(((()))) //// DDiissppllaayy **(())\\nn\\ pprriinntt //xx (())\\nn\\ wwhhaattiiss (()) //// WWhhaatt iiss (())\\nn\\ ppttyyppee (())\\nn\\ wwaattcchh (())\\nn\\ uunnttiill\\nn\\ sshheellll See also the `ccoonnssoolleeBBuuttttoonnss' and `ddaattaaBBuuttttoonnss' resources, above, and the `ttoooollBBuuttttoonnss' resource, below. ttoooollbbaarrssAAttBBoottttoomm ((class TToooollbbaarrssAAttBBoottttoomm)) Whether source and data tool bars should be placed above source and data, respectively (`ooffff', default), or below, as in DDD 2.x (`oonn'). See also the `----ttoooollbbaarrss--aatt--bboottttoomm' and `----ttoooollbbaarrss--aatt--ttoopp' options, below. ttoooollBBuuttttoonnss ((class BBuuttttoonnss)) A newline-separated list of buttons to be included in the command tool or the command tool bar (see the `ccoommmmaannddTToooollBBaarr' resource, above). Each button issues the command given by its name. See the `ccoonnssoolleeBBuuttttoonnss' resource, above, for details on button syntax. The default resource value is DDdddd**ttoooollBBuuttttoonnss:: \\ rruunn\\nnbbrreeaakk^^CC\\nnsstteepp\\nnsstteeppii\\nnnneexxtt\\nnnneexxttii\\nn\\ uunnttiill\\nnffiinniisshh\\nnccoonntt\\nn\\kkiillll\\nn\\ uupp\\nnddoowwnn\\nnBBaacckk\\nnFFoorrwwaarrdd\\nnEEddiitt\\nnMMaakkee DDD 3.1.1 1998-12-06 77 ddd(1) ddd(1) For each button, its location in the command tool must be specified using XXmmFFoorrmm constraint resources. See the `DDdddd' application defaults file for instructions. If the `ttoooollBBuuttttoonnss' resource value is empty, the command tool is not created. ttoooollRRiigghhttOOffffsseett ((class OOffffsseett)) The distance between the right border of the com- mand tool and the right border of the source text (in pixels). Default is 8 pixels. ttoooollTTooppOOffffsseett ((class OOffffsseett)) The distance between the upper border of the com- mand tool and the upper border of the source text (in pixels). Default is 8 pixels. vveerriiffyyBBuuttttoonnss ((class VVeerriiffyyBBuuttttoonnss)) If `oonn' (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 `ooffff', no checking is done: all commands are accepted "as is". UUsseerr--DDeeffiinneedd NNeeww DDiissppllaayy MMeennuu The following resources control the user-defined `NNeeww DDiiss-- ppllaayy' menu. ddbbxxDDiissppllaayySShhoorrttccuuttss ((class DDiissppllaayySShhoorrttccuuttss)) A newline-separated list of display expressions to be included in the `NNeeww DDiissppllaayy' menu for DBX. If a line contains a label delimiter (the string `////'; can be changed via the `llaabbeellDDeelliimmiitteerr' resource), the string before the delimiter is used as _e_x_p_r_e_s_- _s_i_o_n, and the string after the delimiter is used as label. Otherwise, the label is `DDiissppllaayy _e_x_p_r_e_s_- _s_i_o_n'. Upon activation, the string `(())' in _e_x_p_r_e_s_- _s_i_o_n is replaced by the name of the currently selected display. ggddbbDDiissppllaayySShhoorrttccuuttss ((class DDiissppllaayySShhoorrttccuuttss)) A newline-separated list of display expressions to be included in the `NNeeww DDiissppllaayy' menu for GDB. See the description of `ddbbxxDDiissppllaayySShhoorrttccuuttss', above. jjddbbDDiissppllaayySShhoorrttccuuttss ((class DDiissppllaayySShhoorrttccuuttss)) A newline-separated list of display expressions to be included in the `NNeeww DDiissppllaayy' menu for JDB. See the description of `ddbbxxDDiissppllaayySShhoorrttccuuttss', above. llaabbeellDDeelliimmiitteerr ((class LLaabbeellDDeelliimmiitteerr)) The string used to separate labels from commands and shortcuts. Default is `////'. DDD 3.1.1 1998-12-06 78 ddd(1) ddd(1) ppeerrllDDiissppllaayySShhoorrttccuuttss ((class DDiissppllaayySShhoorrttccuuttss)) A newline-separated list of display expressions to be included in the `NNeeww DDiissppllaayy' menu for Perl. See the description of `ddbbxxDDiissppllaayySShhoorrttccuuttss', above. ppyyddbbDDiissppllaayySShhoorrttccuuttss ((class DDiissppllaayySShhoorrttccuuttss)) A newline-separated list of display expressions to be included in the `NNeeww DDiissppllaayy' menu for PYDB. See the description of `ddbbxxDDiissppllaayySShhoorrttccuuttss', above. xxddbbDDiissppllaayySShhoorrttccuuttss ((class DDiissppllaayySShhoorrttccuuttss)) A newline-separated list of display expressions to be included in the `NNeeww DDiissppllaayy' menu for XDB. See the description of `ddbbxxDDiissppllaayySShhoorrttccuuttss', above. DDaattaa DDiissppllaayy The following resources control the data display. aalliiggnn22ddAArrrraayyss ((class AAlliiggnn22ddAArrrraayyss)) If `oonn' (default), DDD lays out two-dimensional arrays as tables, such that all array elements are aligned with each other. If `ooffff', DDD treats a two-dimensional array as an array of one- dimensional arrays, each aligned on its own. aauuttooCClloosseeDDaattaaWWiinnddooww ((class AAuuttooCClloossee)) If this is `oonn' (default) and DDD is in stacked window mode, deleting the last display automati- cally closes the data window. If this is `ooffff', the data window stays open even after deleting the last display. bbuummppDDiissppllaayyss ((class BBuummppDDiissppllaayyss)) If some display _D changes size and this resource is `oonn' (default), DDD assigns new positions to dis- plays below and on the right of _D such that the distance between displays remains constant. If this is `ooffff', other displays are not rearranged. cclluusstteerrDDiissppllaayyss ((class CClluusstteerrDDiissppllaayyss)) If `oonn', new independent data displays will auto- matically be clustered. Default is `ooffff', meaning to leave new displays unclustered. ddeelleetteeAAlliiaassDDiissppllaayyss ((class DDeelleetteeAAlliiaassDDiissppllaayyss)) If this is `oonn' (default), the `UUnnddiissppllaayy (())' but- ton also deletes all aliases of the selected dis- plays. If this is `ooffff', only the selected dis- plays are deleted; the aliases remain, and one of the aliases will be unsuppressed. DDD 3.1.1 1998-12-06 79 ddd(1) ddd(1) ddeetteeccttAAlliiaasseess ((class DDeetteeccttAAlliiaasseess)) If `oonn', DDD attempts to recognize shared data structures. See `EExxaammiinniinngg sshhaarreedd ddaattaa ssttrruucc-- ttuurreess', above, for a discussion. The default is `ooffff', meaning that shared data structures are not recognized. eexxppaannddRReeppeeaatteeddVVaalluueess ((class EExxppaannddRReeppeeaatteeddVVaalluueess)) GDB can print repeated array elements as `_V_A_L_U_E <<rreeppeeaatteedd _N ttiimmeess>>'. If `eexxppaannddRReeppeeaatteeddVVaalluueess' is `oonn', DDD will display _N instances of _V_A_L_U_E instead. If `eexxppaannddRReeppeeaatteeddVVaalluueess' is `ooffff' (default), DDD will display _V_A_L_U_E with `<<_Nxx>>'' aappppeennddeedd ttoo iinnddiiccaattee tthhee rreeppeettiittiioonn.. hhiiddeeIInnaaccttiivveeDDiissppllaayyss ((ccllaassss HHiiddeeIInnaaccttiivveeDDiissppllaayyss)) If some display gets out of scope and this resource is `oonn' (default), DDD removes it from the data display. If this is `ooffff', it is simply disabled. ppaannnneeddGGrraapphhEEddiittoorr ((class PPaannnneeddGGrraapphhEEddiittoorr)) The control to scroll the graph. +o If this is `oonn', an Athena panner is used (a kind of two-directional scrollbar). +o If this is `ooffff' (default), two Motif scrollbars are used. See also the `----ssccrroolllleedd--ggrraapphh--eeddiittoorr' and `----ppaannnneedd--ggrraapphh--eeddiittoorr' options, below. ppaappeerrSSiizzee ((class PPaappeerrSSiizzee)) The paper size used for printing, in format _w_i_d_t_h x _h_e_i_g_h_t. The default is A4 format, or `221100mmmm xx 229977mmmm'. sshhoowwBBaasseeDDiissppllaayyTTiittlleess ((class SShhoowwDDiissppllaayyTTiittlleess)) Whether to assign titles to base (independent) dis- plays or not. Default is `oonn'. sshhoowwDDeeppeennddeennttDDiissppllaayyTTiittlleess ((class SShhoowwDDiissppllaayyTTiittlleess)) Whether to assign titles to dependent displays or not. Default is `ooffff'. ttyyppeeddAAlliiaasseess ((class TTyyppeeddAAlliiaasseess)) If `oonn' (default), DDD requires structural equiva- lence in order to recognize shared data structures. If this is `ooffff', two displays at the same address are considered aliases, regardless of their struc- ture. vvssllBBaasseeDDeeffss ((class VVSSLLDDeeffss)) A string with additional VSL definitions that are DDD 3.1.1 1998-12-06 80 ddd(1) ddd(1) appended to the builtin VSL library. This resource is prepended to the `vvssllDDeeffss' resource below and set in the DDD application defaults file; don't change it. vvssllDDeeffss ((class VVSSLLDDeeffss)) A string with additional VSL definitions that are appended to the builtin VSL library. The default value is an empty string. This resource can be used to override specific VSL definitions that affect the data display. The general pattern to replace a function defini- tion _f_u_n_c_t_i_o_n with a new definition _n_e_w___d_e_f is: ##pprraaggmmaa rreeppllaaccee _f_u_n_c_t_i_o_n _f_u_n_c_t_i_o_n((_a_r_g_s...)) == _n_e_w___d_e_f;; The following VSL functions are frequently used: ccoolloorr((_b_o_x,, _f_o_r_e_g_r_o_u_n_d [[,, _b_a_c_k_g_r_o_u_n_d]])) Set the _f_o_r_e_g_r_o_u_n_d and _b_a_c_k_g_r_o_u_n_d colors of _b_o_x. ddiissppllaayy__ccoolloorr((_b_o_x)) The color used in data displays. Default: ccoolloorr((_b_o_x,, ""bbllaacckk"",, ""wwhhiittee"")) ttiittllee__ccoolloorr((_b_o_x)) The color used in the title bar. Default: ccoolloorr((_b_o_x,, ""bbllaacckk"")) ddiissaabblleedd__ccoolloorr((_b_o_x)) The color used for disabled boxes. Default: ccoolloorr((_b_o_x,, ""wwhhiittee"",, ""ggrreeyy5500"")) ssiimmppllee__ccoolloorr((_b_o_x)) The color used for simple values. Default: ccoolloorr((_b_o_x,, ""bbllaacckk"")) ppooiinntteerr__ccoolloorr((_b_o_x)) The color used for pointers. Default: ccoolloorr((_b_o_x,, ""bblluuee44"")) ssttrruucctt__ccoolloorr((_b_o_x)) The color used for structures. Default: ccoolloorr((_b_o_x,, ""bbllaacckk"")) aarrrraayy__ccoolloorr((_b_o_x)) The color used for arrays. Default: ccoolloorr((_b_o_x,, ""bblluuee44"")) rreeffeerreennccee__ccoolloorr((_b_o_x)) The color used for references. Default: DDD 3.1.1 1998-12-06 81 ddd(1) ddd(1) ccoolloorr((_b_o_x,, ""bblluuee44"")) cchhaannggeedd__ccoolloorr((_b_o_x)) The color used for changed values. Default: ccoolloorr((_b_o_x,, ""bbllaacckk"",, ""##ffffffffcccc"")) ssttddffoonnttffaammiillyy(()) The font family used. One of ffaamm-- iillyy__ttiimmeess(()), ffaammiillyy__ccoouurriieerr(()), ffaamm-- iillyy__hheellvveettiiccaa(()), ffaammiillyy__nneeww__cceennttuurryy(()), or ffaammiillyy__ttyyppeewwrriitteerr(()) (default). ssttddffoonnttssiizzee(()) The font size used (in pixels). 00 (default) means to use ssttddffoonnttppooiinnttss(()) instead. ssttddffoonnttppooiinnttss(()) The font size used (in 1/10 points). 00 means to use ssttddffoonnttssiizzee(()) instead. Default value: 9900. ssttddffoonnttwweeiigghhtt(()) The font weight used. Either wweeiigghhtt__mmeeddiiuumm(()) (default) or wweeiigghhtt__bboolldd(()). To set the pointer color to "red4", use DDdddd**vvssllDDeeffss:: \\ ##pprraaggmmaa rreeppllaaccee ppooiinntteerr__ccoolloorr\\nn\\ ppooiinntteerr__ccoolloorr((bbooxx)) == ccoolloorr((bbooxx,, ""rreedd44""));;\\nn To set the default font size to resolution- independent 10.0 points, use DDdddd**vvssllDDeeffss:: \\ ##pprraaggmmaa rreeppllaaccee ssttddffoonnttssiizzee\\nn\\ ##pprraaggmmaa rreeppllaaccee ssttddffoonnttppooiinnttss\\nn\\ ssttddffoonnttssiizzee(()) == 00;;\\nn ssttddffoonnttppooiinnttss(()) == 110000;;\\nn To set the default font to 12-pixel courier, use DDdddd**vvssllDDeeffss:: \\ ##pprraaggmmaa rreeppllaaccee ssttddffoonnttssiizzee\\nn\\ ##pprraaggmmaa rreeppllaaccee ssttddffoonnttffaammiillyy\\nn\\ ssttddffoonnttssiizzee(()) == 1122;;\\nn\\ ssttddffoonnttffaammiillyy(()) == ffaammiillyy__ccoouurriieerr(());;\\nn See the file `dddddd..vvssll' for further definitions to override using the `vvssllDDeeffss' resource. DDD 3.1.1 1998-12-06 82 ddd(1) ddd(1) vvssllLLiibbrraarryy ((class VVSSLLLLiibbrraarryy)) The VSL library to use. `bbuuiillttiinn' (default) means to use the built-in library, any other value is used as file name. vvssllPPaatthh ((class VVSSLLPPaatthh)) 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 `//oopptt//ssrrcc', you can use the following settings to read the VSL library from `//hhoommee//jjooee//dddddd..vvssll': DDdddd**vvssllLLiibbrraarryy:: //hhoommee//jjooee//dddddd..vvssll DDdddd**vvssllPPaatthh:: \\ ..:://oopptt//ssrrcc//dddddd//dddddd:://oopptt//ssrrcc//dddddd//vvsslllliibb VSL include files referenced by `//hhoommee//jjooee//dddddd..vvssll' are searched first in the current directory `..', then in `//oopptt//ssrrcc//dddddd//dddddd//', and then in `//oopptt//ssrrcc//dddddd//vvsslllliibb//'. Instead of supplying another VSL library, it is often easier to specify some minor changes to the built-in library. See the `vvssllDDeeffss' resource, above, for details. PPlloott WWiinnddooww The following resources control the plot window. pplloottTTeerrmmTTyyppee ((class PPlloottTTeerrmmTTyyppee)) The Gnuplot terminal type. Can have one of two values: +o If this is `xx1111', DDD "swallows" the Gnuplot output win- dow into its own user interface. Some window managers, notably MWM, have trouble with swallowing techniques. +o Setting this resource to `xxlliibb' (default) makes DDD pro- vide a _b_u_i_l_t_i_n _p_l_o_t _w_i_n_d_o_w instead. In this mode, plots work well with any window manager, but are less cus- tomizable (Gnuplot resources are not understood). pplloottCCoommmmaanndd ((class PPlloottCCoommmmaanndd)) The name of a Gnuplot executable. Default is `ggnnuupplloott', followed by some options to set up colors and the ini- tial geometry. pplloottWWiinnddoowwCCllaassss ((class PPlloottWWiinnddoowwCCllaassss)) The class of the Gnuplot output window. When invoking Gnuplot, DDD waits for a window with this class and incorporates it into its own user interface (unless `pplloottTTeerrmmTTyyppee' is `xxlliibb'; see above). Default is DDD 3.1.1 1998-12-06 83 ddd(1) ddd(1) `GGnnuupplloott'. pplloottWWiinnddoowwDDeellaayy ((class WWiinnddoowwDDeellaayy)) The time (in ms) to wait for the creation of the Gnuplot window. Before this delay, DDD looks at each newly cre- ated window to see whether this is the plot window to swallow. This is cheap, but unfortunately, some window managers do not pass the creation event to DDD. If this delay has passed, and DDD has not found the plot window, DDD searches _a_l_l existing windows, which is pretty expensive. Default time is 22000000. pplloottIInniittCCoommmmaannddss ((class PPlloottIInniittCCoommmmaannddss)) The initial Gnuplot commands issued by DDD. Default is: sseett ppaarraammeettrriicc sseett uurraannggee [[00::11]] sseett vvrraannggee [[00::11]] sseett ttrraannggee [[00::11]] The `ppaarraammeettrriicc' setting is required to make Gnuplot understand the data files as generated DDD. The range commands are used to plot scalars. pplloott22ddSSeettttiinnggss ((class PPlloottSSeettttiinnggss)) Additional initial settings for 2-D plots. Default is `sseett nnoobboorrddeerr'. Feel free to customize these settings as desired. pplloott33ddSSeettttiinnggss ((class PPlloottSSeettttiinnggss)) Additional initial settings for 3-D plots. Default is `sseett bboorrddeerr'. Feel free to customize these settings as desired. DDeebbuuggggeerr CCoonnssoollee The following resources control the debugger console. lliinneeBBuuffffeerreeddCCoonnssoollee ((class LLiinneeBBuuffffeerreedd)) If this is `oonn' (default), each line from the infe- rior is output on each own, such that the final line is placed at the bottom of the debugger con- sole. If this is `ooffff', all lines are output as a whole. This is faster, but results in a random position of the last line. VVaalluuee HHiissttoorriieess The following resources control the pop-down value histo- ries associated with various text fields. ppooppddoowwnnHHiissttoorryySSiizzee ((class HHiissttoorryySSiizzee)) The maximum number of items to display in pop-down value histories. A value of 00 (default) means an DDD 3.1.1 1998-12-06 84 ddd(1) ddd(1) unlimited number of values. ssoorrttPPooppddoowwnnHHiissttoorryy ((class SSoorrttPPooppddoowwnnHHiissttoorryy)) If `oonn' (default), items in the pop-down value his- tories are sorted alphabetically. If `ooffff', most recently used values will appear at the top. CCuussttoommiizziinngg HHeellppeerrss The following resources determine external programs invoked by DDD. eeddiittCCoommmmaanndd ((class EEddiittCCoommmmaanndd)) A command string to invoke an editor on the spe- cific file. `@@LLIINNEE@@' is replaced by the current line number, `@@FFIILLEE@@' by the file name. The default is to invoke $$XXEEDDIITTOORR first, then $$EEDDIITTOORR, then vvii: DDdddd**eeddiittCCoommmmaanndd:: \\ $${{XXEEDDIITTOORR--ffaallssee}} ++@@LLIINNEE@@ @@FFIILLEE@@ \\ |||| xxtteerrmm --ee $${{EEDDIITTOORR--vvii}} ++@@LLIINNEE@@ @@FFIILLEE@@ This `..dddddd//iinniitt' setting invokes an editing session for an _X_E_m_a_c_s editor running _g_n_u_s_e_r_v: DDdddd**eeddiittCCoommmmaanndd:: ggnnuucclliieenntt ++@@LLIINNEE@@ @@FFIILLEE@@ This `..dddddd//iinniitt' setting invokes an editing session for an _E_m_a_c_s editor running _e_m_a_c_s_s_e_r_v_e_r: DDdddd**eeddiittCCoommmmaanndd:: eemmaaccsscclliieenntt ++@@LLIINNEE@@ @@FFIILLEE@@ ffoonnttSSeelleeccttCCoommmmaanndd ((class FFoonnttSSeelleeccttCCoommmmaanndd)) A command to select from a list of fonts. The string `@@FFOONNTT@@' is replaced by the current DDD default font; the string `@@TTYYPPEE@@' is replaced by a symbolic name of the DDD font to edit. The program must either place the name of the selected font in the PRIMARY selection or print the selected font on standard output. A typical value is: DDdddd**ffoonnttSSeelleeccttCCoommmmaanndd:: xxffoonnttsseell --pprriinntt ggeettCCoorreeCCoommmmaanndd ((class GGeettCCoorreeCCoommmmaanndd)) A command to get a core dump of a running process (typically, `ggccoorree') `@@FFIILLEE@@' is replaced by the base name of the file to create; `@@PPIIDD@@' is replaced by the process id. The output must be written to `@@FFIILLEE@@..@@PPIIDD@@'. Leave this entry empty if you have no `ggccoorree' or similar command. DDD 3.1.1 1998-12-06 85 ddd(1) ddd(1) lleessssTTiiffVVeerrssiioonn ((class LLeessssTTiiffVVeerrssiioonn)) Indicates the LessTif version DDD is running against. For LessTif version _x_._y, the value is _x multiplied by 1000 plus _y--for instance, the value 7799 stands for LessTif 0.79 and the value 11000055 stands for LessTif 1.5. If the value of this resource is less than 1000, indicating LessTif 0.99 or earlier, DDD enables version-specific hacks to make DDD work around LessTif bugs and deficiencies. If DDD was compiled against LessTif, the default value is the value of the `LLeessssTTiiffVVeerrssiioonn' macro in <<XXmm//XXmm..hh>>. If DDD was compiled against OSF/Motif, the default value is 11000000, disabling all LessTif- specific hacks. lliissttCCoorreeCCoommmmaanndd ((class lliissttCCoorreeCCoommmmaanndd)) The command to list all core files on the remote host. The string `@@MMAASSKK@@' is replaced by a file filter. The default setting is: DDdddd**lliissttCCoorreeCCoommmmaanndd:: \\ ffiillee @@MMAASSKK@@ || ggrreepp ''..**::..**ccoorree..**'' \\ || ccuutt --dd:: --ff11 lliissttDDiirrCCoommmmaanndd ((class lliissttDDiirrCCoommmmaanndd)) The command to list all directories on the remote host. The string `@@MMAASSKK@@' is replaced by a file filter. The default setting is: DDdddd**lliissttDDiirrCCoommmmaanndd:: \\ ffiillee @@MMAASSKK@@ || ggrreepp ''..**::..**ddiirreeccttoorryy..**'' \\ || ccuutt --dd:: --ff11 lliissttEExxeeccCCoommmmaanndd ((class lliissttEExxeeccCCoommmmaanndd)) The command to list all executable files on the remote host. The string `@@MMAASSKK@@' is replaced by a file filter. The default setting is: DDdddd**lliissttEExxeeccCCoommmmaanndd:: \\ ffiillee @@MMAASSKK@@ || ggrreepp ''..**::..**eexxeecc..**'' \\ || ggrreepp --vv ''..**::..**ssccrriipptt..**'' \\ || ccuutt --dd:: --ff11 || ggrreepp --vv ''..**\\..oo$$'' lliissttSSoouurrcceeCCoommmmaanndd ((class lliissttSSoouurrcceeCCoommmmaanndd)) The command to list all source files on the remote host. The string `@@MMAASSKK@@' is replaced by a file filter. The default setting is: DDdddd**lliissttSSoouurrcceeCCoommmmaanndd:: \\ ffiillee @@MMAASSKK@@ || ggrreepp ''..**::..**tteexxtt..**'' \\ DDD 3.1.1 1998-12-06 86 ddd(1) ddd(1) || ccuutt --dd:: --ff11 pprriinnttCCoommmmaanndd ((class PPrriinnttCCoommmmaanndd)) The command to print a postscript file. Usually `llpp' or `llpprr'. ppssCCoommmmaanndd ((class PPssCCoommmmaanndd)) The command to get a list of processes. Usually `ppss'. Depending on your system, useful alternate values include `ppss --eeff' and `ppss uuxx'. The first line of the output must either contain a `PPIIDD' title, or each line must begin with a process ID. Note that the output of this command is filtered by DDD; a process is only shown if it can be attached to. The DDD process itself as well as the process of the inferior debugger are suppressed, too. rrsshhCCoommmmaanndd ((class RRsshhCCoommmmaanndd)) The remote shell command to invoke TTY-based com- mands on remote hosts. Usually, `rreemmsshh', `rrsshh', `sssshh', or `oonn'. tteerrmmCCoommmmaanndd ((class TTeerrmmCCoommmmaanndd)) 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 to this string. The string `@@FFOONNTT@@' is replaced by the name of the fixed width font used by DDD. A simple value is DDdddd**tteerrmmCCoommmmaanndd:: xxtteerrmm --ffnn @@FFOONNTT@@ --ee //bbiinn//sshh --cc tteerrmmTTyyppee ((class TTeerrmmTTyyppee)) The terminal type provided by the `tteerrmmCCoommmmaanndd' resource--that is, the value of the TTEERRMM environ- ment variable to be passed to the debugged program. Default: `xxtteerrmm'. uunnccoommpprreessssCCoommmmaanndd ((class UUnnccoommpprreessssCCoommmmaanndd)) The command to uncompress the built-in DDD manual, the DDD license, and the DDD news. Takes a com- pressed text from standard input and writes the uncompressed text to standard output. The default value is `ggzziipp --dd --cc'; typical values include `zzccaatt' and `gguunnzziipp --cc'. wwwwwwCCoommmmaanndd ((class WWWWWWCCoommmmaanndd)) The command to invoke a WWW browser. The string `@@UURRLL@@' is replaced by the URL to open. Default is to try a running Netscape first, then $$WWWWWWBBRROOWWSSEERR, then to invoke a new Netscape process, then to let a running Emacs do the job, then to invoke Mosaic, then to invoke Lynx in an xterm. DDD 3.1.1 1998-12-06 87 ddd(1) ddd(1) To specify `nneettssccaappee--44..00' as browser, use the set- ting: DDdddd**wwwwwwCCoommmmaanndd:: \\ nneettssccaappee--44..00 --rreemmoottee ''ooppeennUURRLL((@@UURRLL@@))'' \\ |||| nneettssccaappee--44..00 ''@@UURRLL@@'' This command first tries to connect to a running nneettssccaappee--44..00 browser; if this fails, it starts a new nneettssccaappee--44..00 process. wwwwwwPPaaggee ((class WWWWWWPPaaggee)) The DDD WWW page. Value: DDdddd**wwwwwwPPaaggee:: hhttttpp::////wwwwww..ccss..ttuu--bbss..ddee//ssoofftteecchh//dddddd// OObbttaaiinniinngg DDiiaaggnnoossttiiccss The following resources are used for debugging DDD and to obtain specific DDD information. aappppDDeeffaauullttssVVeerrssiioonn ((class VVeerrssiioonn)) 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. cchheecckkCCoonnffiigguurraattiioonn ((class CChheecckkCCoonnffiigguurraattiioonn)) If `oonn', check the DDD environment (in particular, the X configuration), report any possible problem causes and exit. See also the `----cchheecckk-- ccoonnffiigguurraattiioonn' option, below. ddddddiinniittVVeerrssiioonn ((class VVeerrssiioonn)) The version of the DDD executable that last wrote the `$$HHOOMMEE//..dddddd//iinniitt' file. If this string does not match the version of the current DDD exe- cutable, DDD issues a warning. ddeebbuuggCCoorreeDDuummppss ((class DDeebbuuggCCoorreeDDuummppss)) If `oonn', DDD invokes a debugger on itself when receiving a fatal signal. dduummppCCoorree ((class DDuummppCCoorree)) If `oonn' (default), DDD dumps core when receiving a fatal signal. mmaaiinntteennaannccee ((class MMaaiinntteennaannccee)) If `oonn', enables a top-level `MMaaiinntteennaannccee' menu with additional options. See also the `----mmaaiinnttee-- nnaannccee' option, below. sshhoowwCCoonnffiigguurraattiioonn ((class SShhoowwCCoonnffiigguurraattiioonn)) If `oonn', show the DDD configuration on standard output and exit. See also the `----ccoonnffiigguurraattiioonn' DDD 3.1.1 1998-12-06 88 ddd(1) ddd(1) option, below. sshhoowwFFoonnttss ((class SShhoowwFFoonnttss)) If `oonn', show the DDD font definitions on standard output and exit. See also the `----ffoonnttss' option, below. sshhoowwIInnvvooccaattiioonn ((class SShhoowwIInnvvooccaattiioonn)) If `oonn', show the DDD invocation options on stan- dard output and exit. See also the `----hheellpp' option, below. sshhoowwLLiicceennssee ((class SShhoowwLLiicceennssee)) If `oonn', show the DDD license on standard output and exit. See also the `----lliicceennssee' option, below. sshhoowwMMaannuuaall ((class SShhoowwMMaannuuaall)) If `oonn', show this DDD manual page on standard out- put and exit. If the standard output is a termi- nal, the manual page is shown in a pager ($$PPAAGGEERR, `lleessss' or `mmoorree'). See also the `----mmaannuuaall' option, below. sshhoowwNNeewwss ((class SShhoowwNNeewwss)) If `oonn', show the DDD news on standard output and exit. See also the `----nneewwss' option, below. sshhoowwVVeerrssiioonn ((class SShhoowwVVeerrssiioonn)) If `oonn', show the DDD version on standard output and exit. See also the `----vveerrssiioonn' option, below. ttrraaccee ((class TTrraaccee)) If `oonn', show the dialog between DDD and the infe- rior debugger on standard output. Default is `ooffff'. MMoorree RReessoouurrcceess The `DDdddd' application defaults file contains even more information about setting DDD resources. The `DDdddd' file comes with the DDD distribution. OOPPTTIIOONNSS 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. DDD also understands the usual X options such as `--ddiissppllaayy' or `--ggeeoommeettrryy'; see XX((11)) for details. All other arguments and options are passed to the inferior debugger. To pass an option to the inferior debugger that conflicts with an X option, or with a DDD option listed here, use the `----ddeebbuuggggeerr' option, below. DDD 3.1.1 1998-12-06 89 ddd(1) ddd(1) ----aattttaacchh--wwiinnddoowwss Attach the source and data windows to the debugger console, creating one single big DDD window. This is the default setting. ----aattttaacchh--ssoouurrccee--wwiinnddooww Attaches only the source window to the debugger console. ----aattttaacchh--ddaattaa--wwiinnddooww Attaches only the source window to the debugger console. ----aauuttoommaattiicc--ddeebbuuggggeerr Determine the inferior debugger automatically. ----bbuuttttoonn--ttiippss Enable button tips. ----ccoonnffiigguurraattiioonn Show the DDD configuration settings and exit. ----cchheecckk--ccoonnffiigguurraattiioonn Check the DDD environment (in particular, the X configuration), report any possible problem causes and exit. ----ddaattaa--wwiinnddooww Create the data window upon start-up. ----ddbbxx Run the DBX debugger as inferior debugger. ----ddeebbuuggggeerr _n_a_m_e Invoke the inferior debugger _n_a_m_e. This is useful if you have several debugger versions around, or if the inferior debugger cannot be invoked as `ggddbb', `ddbbxx', `xxddbb', `jjddbb', `ppyyddbb', or `ppeerrll' respec- tively. This option can also be used to pass options to the inferior debugger that would otherwise conflict with DDD options. For instance, to pass the option `--dd _d_i_r_e_c_t_o_r_y' to XDB, use: dddddd ----ddeebbuuggggeerr ""xxddbb --dd _d_i_r_e_c_t_o_r_y"" If you use the `----ddeebbuuggggeerr' option, be sure that the type of inferior debugger is specified as well. That is, use one of the options `----ggddbb', `----ddbbxx', `----xxddbb', `----jjddbb' `----ppyyddbb', or `----ppeerrll' (unless the default setting works fine). ----ddeebbuuggggeerr--ccoonnssoollee Create the debugger console upon start-up. DDD 3.1.1 1998-12-06 90 ddd(1) ddd(1) ----ddiissaasssseemmbbllee Disassemble the source code. See also the `----nnoo-- ddiissaasssseemmbbllee' option, below. ----eexxeecc--wwiinnddooww 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. ----ffoonnttss Show the font definitions used by DDD on standard output. ----ffoonnttssiizzee _s_i_z_e Set the default font size to _s_i_z_e 1/10 points. To use 12-point fonts, say `----ffoonnttssiizzee 112200'. ----ffuullllnnaammee Enable TTY interface, taking additional debugger commands from standard input and forwarding debug- ger output on standard output. Current positions are issued in GDB `--ffuullllnnaammee' format suitable for debugger front-ends. By default, both the debugger console and source window are disabled. ----ggddbb Run the GDB debugger as inferior debugger. ----ggllyypphhss Display the current execution position and break- points as glyphs. See also the `----nnoo--ggllyypphhss' option, below. ----hheellpp Give a list of frequently used options. Show options of the inferior debugger as well. ----hhoosstt [_u_s_e_r_n_a_m_e@@]_h_o_s_t_n_a_m_e Invoke the inferior debugger directly on the remote host _h_o_s_t_n_a_m_e. If _u_s_e_r_n_a_m_e is given and the `----llooggiinn' option is not used, use _u_s_e_r_n_a_m_e as remote user name. See `RREEMMOOTTEE DDEEBBUUGGGGIINNGG', above. ----jjddbb Run JDB as inferior debugger. ----lleessssttiiff--hhaacckkss Equivalent to `----lleessssttiiff--vveerrssiioonn 999999'. Deprecated. ----lleessssttiiff--vveerrssiioonn _v_e_r_s_i_o_n Enable some hacks to make DDD run properly with LessTif. See the `lleessssTTiiffVVeerrssiioonn' resource and `UUSSIINNGG DDDDDD WWIITTHH LLEESSSSTTIIFF', above, for a discussion. DDD 3.1.1 1998-12-06 91 ddd(1) ddd(1) ----lliicceennssee Show the DDD license and exit. ----llooggiinn _u_s_e_r_n_a_m_e Use _u_s_e_r_n_a_m_e as remote user name. See `RREEMMOOTTEE DDEEBBUUGGGGIINNGG', above. ----mmaaiinntteennaannccee Enable the top-level `MMaaiinntteennaannccee' menu with options for debugging DDD. ----mmaannuuaall Show this manual page and exit. ----nneewwss Show the DDD news and exit. ----nnoo--bbuuttttoonn--ttiippss Disable button tips. ----nnoo--ddaattaa--wwiinnddooww Do not create the data window upon start-up. ----nnoo--ddeebbuuggggeerr--ccoonnssoollee Do not create the debugger console upon start-up. ----nnoo--ddiissaasssseemmbbllee Do not disassemble the source code. ----nnoo--eexxeecc--wwiinnddooww Do not run the debugged program in a specially cre- ated execution window; use the debugger console instead. Useful for programs that have little ter- minal input/output, or for remote debugging. ----nnoo--ggllyypphhss Display the current execution position and break- points as text characters. Do not use glyphs. ----nnoo--lleessssttiiff--hhaacckkss Equivalent to `----lleessssttiiff--vveerrssiioonn 11000000'. Depre- cated. ----nnoo--ssoouurrccee--wwiinnddooww Do not create the source window upon start-up. ----nnoo--vvaalluuee--ttiippss Disable value tips. ----nnww Do not use the X window interface. Start the infe- rior debugger on the local host. ----ppeerrll Run Perl as inferior debugger. ----ppyyddbb Run PYDB as inferior debugger. DDD 3.1.1 1998-12-06 92 ddd(1) ddd(1) ----ppaannnneedd--ggrraapphh--eeddiittoorr 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 ----ssccrroolllleedd--ggrraapphh--eeddiittoorr, below. ----ppllaayy _l_o_g_-_f_i_l_e Recapitulate a previous DDD session. Invoke `ddd ----PPLLAAYY _l_o_g_-_f_i_l_e' as inferior debugger, simulating the inferior debugger given in _l_o_g_-_f_i_l_e (see below). This is useful for debugging DDD. ----PPLLAAYY _l_o_g_-_f_i_l_e Simulate an inferior debugger. _l_o_g_-_f_i_l_e is a `$$HHOOMMEE//..dddddd//lloogg' file as generated by some previous DDD session. When a command is entered, scan the _l_o_g_-_f_i_l_e for this command and re-issue the logged reply; if the command is not found, do nothing. This is used by the `----ppllaayy' option. ----rrhhoosstt [_u_s_e_r_n_a_m_e@@]_h_o_s_t_n_a_m_e Run the inferior debugger interactively on the remote host _h_o_s_t_n_a_m_e. If _u_s_e_r_n_a_m_e is given and the `----llooggiinn' option is not used, use _u_s_e_r_n_a_m_e as remote user name. See `RREEMMOOTTEE DDEEBBUUGGGGIINNGG', above. ----sseeppaarraattee--wwiinnddoowwss Separate the console, source and data windows. See also the `----aattttaacchh' options, above. ----ssccrroolllleedd--ggrraapphh--eeddiittoorr Use Motif scroll bars to scroll the data window. This is the default in most DDD configurations. See also ----ppaannnneedd--ggrraapphh--eeddiittoorr, above. ----ssoouurrccee--wwiinnddooww Create the source window upon start-up. ----ssttaattuuss--aatt--bboottttoomm Place the status line at the bottom of the source window. ----ssttaattuuss--aatt--ttoopp Place the status line at the top of the source win- dow. ----ssyynncc--ddeebbuuggggeerr Do not process X events while the debugger is busy. This may result in slightly better performance on single-processor systems. DDD 3.1.1 1998-12-06 93 ddd(1) ddd(1) ----ttoooollbbaarrss--aatt--bboottttoomm Place the toolbars the bottom of the window. ----ttoooollbbaarrss--aatt--ttoopp Place the toolbars at the top of the window. ----ttrraaccee Show the interaction between DDD and the inferior debugger on standard error. This is useful for debugging DDD. If `----ttrraaccee' is not specified, this information is written into `$$HHOOMMEE//..dddddd//lloogg', such that you can also do a post-mortem debugging. ----ttttyy 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. By default, the debugger console is disabled. ----vvaalluuee--ttiippss Enable value tips. ----vveerrssiioonn Show the DDD version and exit. ----vvssll--lliibbrraarryy _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. ----vvssll--ppaatthh _p_a_t_h Search VSL libraries in _p_a_t_h (a colon-separated directory list). ----vvssll--hheellpp 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. ----xxddbb Run XDB as inferior debugger. AACCTTIIOONNSS The following DDD actions may be used in translation tables. GGeenneerraall AAccttiioonnss These actions are used to assign the keyboard focus. dddddd--ggeett--ffooccuuss (()) Assign focus to the element that just received input. DDD 3.1.1 1998-12-06 94 ddd(1) ddd(1) dddddd--nneexxtt--ttaabb--ggrroouupp (()) Assign focus to the next tab group. dddddd--pprreevv--ttaabb--ggrroouupp (()) Assign focus to the previous tab group. dddddd--pprreevviioouuss--ttaabb--ggrroouupp (()) Assign focus to the previous tab group. DDaattaa DDiissppllaayy AAccttiioonnss These actions are used in the DDD graph editor. eenndd (()) End the action initiated by sseelleecctt. Bound to a button up event. eexxtteenndd (()) Extend the current selection. Bound to a button down event. eexxtteenndd--oorr--mmoovvee (()) Extend the current selection. Bound to a button down event. If the pointer is dragged, move the selection. ffoollllooww (()) Continue the action initiated by sseelleecctt. Bound to a pointer motion event. ggrraapphh--sseelleecctt (()) Equivalent to sseelleecctt, but also updates the current argument. ggrraapphh--sseelleecctt--oorr--mmoovvee (()) Equivalent to sseelleecctt--oorr--mmoovvee, but also updates the current argument. ggrraapphh--eexxtteenndd (()) Equivalent to eexxtteenndd, but also updates the current argument. ggrraapphh--eexxtteenndd--oorr--mmoovvee (()) Equivalent to eexxtteenndd--oorr--mmoovvee, but also updates the current argument. ggrraapphh--ttooggggllee (()) Equivalent to ttooggggllee, but also updates the current argument. ggrraapphh--ttooggggllee--oorr--mmoovvee (()) Equivalent to ttooggggllee--oorr--mmoovvee, but also updates the current argument. ggrraapphh--ppooppuupp--mmeennuu (([ggrraapphh|nnooddee|sshhoorrttccuutt])) Pops up a menu. ggrraapphh pops up a menu with global DDD 3.1.1 1998-12-06 95 ddd(1) ddd(1) graph operations, nnooddee pops up a menu with node operations, and sshhoorrttccuutt pops up a menu with dis- play shortcuts. If no argument is given, pops up a menu depending on the context: when pointing on a node with the SShhiifftt key pressed, behaves like sshhoorrttccuutt; when pointing on a without the SShhiifftt key pressed, behaves like nnooddee; otherwise, behaves as if ggrraapphh was given. ggrraapphh--ddeerreeffeerreennccee (()) Dereference the selected display. ggrraapphh--ddeettaaiill (()) Show or hide detail of the selected display. ggrraapphh--rroottaattee (()) Rotate the selected display. ggrraapphh--ddeeppeennddeenntt (()) Pop up a dialog to create a dependent display. hhiiddee--eeddggeess (([aannyy|bbootthh|ffrroomm|ttoo])) Hide some edges. aannyy means to process all edges where either source or target node are selected. bbootthh means to process all edges where both nodes are selected. ffrroomm means to process all edges where at least the source node is selected. ttoo means to process all edges where at least the target node is selected. Default is aannyy. llaayyoouutt (([rreegguullaarr|ccoommppaacctt],, [[++|--]_d_e_g_r_e_e_s]])) Layout the graph. rreegguullaarr means to use the regular layout algorithm; ccoommppaacctt uses an alternate layout algorithm, where successors are placed next to their parents. Default is rreegguullaarr. _d_e_g_r_e_e_s indi- cates in which direction the graph should be lay- outed. Default is the current graph direction. mmoovvee--sseelleecctteedd ((_x_-_o_f_f_s_e_t,, _y_-_o_f_f_s_e_t)) Move all selected nodes in the direction given by _x_-_o_f_f_s_e_t and _y_-_o_f_f_s_e_t. _x_-_o_f_f_s_e_t and _y_-_o_f_f_s_e_t is either given as a numeric pixel value, or as `++ggrriidd', or `--ggrriidd', meaning the current grid size. nnoorrmmaalliizzee (()) Place all nodes on their positions and redraw the graph. rroottaattee (([[++|--]_d_e_g_r_e_e_s])) Rotate the graph around _d_e_g_r_e_e_s degrees. _d_e_g_r_e_e_s must be a multiple of 90. Default is ++9900. sseelleecctt (()) Select the node pointed at. Clear all other DDD 3.1.1 1998-12-06 96 ddd(1) ddd(1) selections. Bound to a button down event. sseelleecctt--aallll (()) Select all nodes in the graph. sseelleecctt--ffiirrsstt (()) Select the first node in the graph. sseelleecctt--nneexxtt (()) Select the next node in the graph. sseelleecctt--oorr--mmoovvee (()) 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. sseelleecctt--pprreevv (()) Select the previous node in the graph. sshhooww--eeddggeess (([aannyy|bbootthh|ffrroomm|ttoo])) Show some edges. aannyy means to process all edges where either source or target node are selected. bbootthh means to process all edges where both nodes are selected. ffrroomm means to process all edges where at least the source node is selected. ttoo means to process all edges where at least the target node is selected. Default is aannyy. ssnnaapp--ttoo--ggrriidd (()) Place all nodes on the nearest grid position. ttooggggllee (()) Toggle the current selection--if the node pointed at is selected, it will be unselected, and vice versa. Bound to a button down event. ttooggggllee--oorr--mmoovvee (()) 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. uunnsseelleecctt--aallll (()) Clear the selection. DDeebbuuggggeerr CCoonnssoollee AAccttiioonnss These actions are used in the debugger console and other text fields. ggddbb--bbaacckkwwaarrdd--cchhaarraacctteerr (()) Move one character to the left. Bound to LLeefftt. ggddbb--bbeeggiinnnniinngg--ooff--lliinnee (()) Move cursor to the beginning of the current line, DDD 3.1.1 1998-12-06 97 ddd(1) ddd(1) after the prompt. Bound to HHOOMMEE. ggddbb--ccoonnttrrooll ((_c_o_n_t_r_o_l_-_c_h_a_r_a_c_t_e_r)) Send the given _c_o_n_t_r_o_l_-_c_h_a_r_a_c_t_e_r to the inferior debugger. The _c_o_n_t_r_o_l_-_c_h_a_r_a_c_t_e_r must be specified in the form `^^_X', where _X is an upper-case letter or `??'. ggddbb--ccoommmmaanndd ((_c_o_m_m_a_n_d)) Execute _c_o_m_m_a_n_d in the debugger console. The fol- lowing replacements are performed on _c_o_m_m_a_n_d: +o If _c_o_m_m_a_n_d has the form '_n_a_m_e......', insert _n_a_m_e, followed by a space, in the debugger console. +o All occurrences of `(())' are replaced by the cur- rent contents of the argument field `(())'. ggddbb--ccoommpplleettee--aarrgg ((_c_o_m_m_a_n_d)) Complete current argument as if _c_o_m_m_a_n_d was prepended. Bound to CCttrrll++TT. ggddbb--ccoommpplleettee--ccoommmmaanndd (()) Complete current command line in the debugger con- sole. Bound to TTAABB. ggddbb--ccoommpplleettee--ttaabb ((_c_o_m_m_a_n_d)) If global TTAABB completion is enabled, complete cur- rent argument as if _c_o_m_m_a_n_d was prepended. Other- wise, proceed as if the TTAABB key was hit. Bound to TTAABB. ggddbb--ddeelleettee--oorr--ccoonnttrrooll ((_c_o_n_t_r_o_l_-_c_h_a_r_a_c_t_e_r)) Like ggddbb--ccoonnttrrooll, but effective only if the cursor is at the end of a line. Otherwise, _c_o_n_t_r_o_l_- _c_h_a_r_a_c_t_e_r is ignored and the character following the cursor is deleted. Bound to CCttrrll++DD. ggddbb--eenndd--ooff--lliinnee (()) Move cursor to the end of the current line. Bound to EEnndd. ggddbb--ffoorrwwaarrdd--cchhaarraacctteerr (()) Move one character to the right. Bound to RRiigghhtt. ggddbb--iinnsseerrtt--ggrraapphh--aarrgg (()) Insert the contents of the data display argument field `(())'. ggddbb--iinnsseerrtt--ssoouurrccee--aarrgg (()) Insert the contents of the source argument field `(())'. DDD 3.1.1 1998-12-06 98 ddd(1) ddd(1) ggddbb--iinntteerrrruupptt (()) If DDD is in incremental search mode, exit it; oth- erwise call ggddbb--ccoonnttrrooll((^^CC)). ggddbb--iisseeaarrcchh--pprreevv (()) Enter reverse incremental search mode. Bound to CCttrrll++BB. ggddbb--iisseeaarrcchh--nneexxtt (()) Enter incremental search mode. Bound to CCttrrll++FF. ggddbb--iisseeaarrcchh--eexxiitt (()) Exit incremental search mode. Bound to EESSCC. ggddbb--nneexxtt--hhiissttoorryy (()) Recall next command from history. Bound to DDoowwnn. ggddbb--pprreevv--hhiissttoorryy (()) Recall previous command from history. Bound to UUpp. ggddbb--pprreevviioouuss--hhiissttoorryy (()) Recall previous command from history. Bound to UUpp. ggddbb--pprroocceessss (([[_a_c_t_i_o_n[[,, _a_r_g_s_._._.]]]])) Process the given event in the debugger console. Bound to key events in the source and data window. If this action is bound to the source window, and the source window is editable, perform _a_c_t_i_o_n((_a_r_g_s_._._.)) on the source window instead; if _a_c_t_i_o_n is not given, perform `sseellff--iinnsseerrtt(())'. ggddbb--sseelleecctt--aallll (()) If the `sseelleeccttAAllllBBiinnddiinnggss' resource is set to MMoottiiff, perform _b_e_g_i_n_n_i_n_g_-_o_f_-_l_i_n_e. Otherwise, per- form _s_e_l_e_c_t_-_a_l_l. Bound to CCttrrll++AA. ggddbb--sseett--lliinnee ((_v_a_l_u_e)) Set the current line to _v_a_l_u_e. Bound to CCttrrll++UU. SSoouurrccee WWiinnddooww AAccttiioonnss These actions are used in the source and code windows. ssoouurrccee--ddeelleettee--ggllyypphh (()) Delete the breakpoint related to the glyph at cur- sor position. ssoouurrccee--ddoouubbllee--cclliicckk (([[_t_e_x_t_-_a_c_t_i_o_n [,_l_i_n_e_-_a_c_t_i_o_n [,_f_u_n_c_t_i_o_n_- _a_c_t_i_o_n]]])) The double-click action in the source window. +o If this action is taken on a breakpoint glyph, edit the breakpoint properties. +o If this action is taken in the breakpoint area, DDD 3.1.1 1998-12-06 99 ddd(1) ddd(1) invoke `ggddbb--ccoommmmaanndd((_l_i_n_e_-_a_c_t_i_o_n))'. If _l_i_n_e_- _a_c_t_i_o_n is not given, it defaults to `bbrreeaakk (())'. +o If this action is taken in the source text, and the next character following the current selec- tion is a `((', invoke `ggddbb--ccoommmmaanndd((_f_u_n_c_t_i_o_n_- _a_c_t_i_o_n))'. If _f_u_n_c_t_i_o_n_-_a_c_t_i_o_n is not given, it defaults to `lliisstt (())'. +o Otherwise, invoke `ggddbb--ccoommmmaanndd((_t_e_x_t_-_a_c_t_i_o_n))'. If _t_e_x_t_-_a_c_t_i_o_n is not given, it defaults to `ggrraapphh ddiissppllaayy (())'. ssoouurrccee--ddrraagg--ggllyypphh (()) Initiate a drag on the glyph at cursor position. ssoouurrccee--ddrroopp--ggllyypphh (([[_a_c_t_i_o_n]) Drop the dragged glyph at cursor position. _a_c_t_i_o_n is either `mmoovvee', meaning to move the dragged glyph, or `ccooppyy', meaning to copy the dragged glyph. If no _a_c_t_i_o_n is given, `mmoovvee' is assumed. ssoouurrccee--eenndd--sseelleecctt--wwoorrdd (()) End selecting a word. ssoouurrccee--ffoollllooww--ggllyypphh (()) Continue a drag on the glyph at cursor position. Usually bound to some motion event. ssoouurrccee--ppooppuupp--mmeennuu (()) Pop up a menu, depending on the location. ssoouurrccee--sseett--aarrgg (()) Set the argument field to the current selection. Typically bound to some selection operation. ssoouurrccee--ssttaarrtt--sseelleecctt--wwoorrdd (()) Start selecting a word. ssoouurrccee--uuppddaattee--ggllyypphhss (()) Update all visible glyphs. Usually invoked after a scrolling operation. IIMMAAGGEESS DDD installs a number of images that may be used as pixmap resources, simply by giving a symbolic name. For button images, three variants are installed as well: +o The suffix `--hhii' indicates a highlighted variant (Button is entered). +o The suffix `--aarrmm' indicates an armed variant (Button is pushed). DDD 3.1.1 1998-12-06 100 ddd(1) ddd(1) +o The suffix `--xxxx' indicates a disabled (insensitive) variant. bbrreeaakk__aatt `BBrreeaakk aatt (())' button. cclleeaarr__aatt `CClleeaarr aatt (())' button. dddddd DDD icon. ddeelleettee `DDeelleettee (())' button. ddiissaabbllee `DDiissaabbllee' button. ddiisspprreeff `DDiissppllaayy ** (())' button. ddiissppllaayy `DDiissppllaayy (())' button. ddrraagg__aarrrrooww The execution pointer (being dragged). ddrraagg__ccoonndd A conditional breakpoint (being dragged). ddrraagg__ssttoopp A breakpoint (being dragged). ddrraagg__tteemmpp A temporary breakpoint (being dragged). eennaabbllee `EEnnaabbllee' button. ffiinndd__ffoorrwwaarrdd `FFiinndd>>>> (())' button. ffiinndd__bbaacckkwwaarrdd `FFiinndd<<<< (())' button. ggrreeyy__aarrrrooww The execution pointer (not in lowest frame). ggrreeyy__ccoonndd A conditional breakpoint (disabled). ggrreeyy__ssttoopp A breakpoint (disabled). DDD 3.1.1 1998-12-06 101 ddd(1) ddd(1) ggrreeyy__tteemmpp A temporary breakpoint (disabled). hhiiddee `HHiiddee (())' button. llooookkuupp `LLooookkuupp (())' button. mmaakkeetteemmpp `MMaakkee TTeemmppoorraarryy' button. nneeww__bbrreeaakk `NNeeww BBrreeaakkppooiinntt' button. nneeww__ddiissppllaayy `NNeeww DDiissppllaayy' button. nneeww__wwaattcchh `NNeeww WWaattcchhppooiinntt' button. ppllaaiinn__aarrrrooww The execution pointer. ppllaaiinn__ccoonndd A conditional breakpoint (enabled). ppllaaiinn__ssttoopp A breakpoint (enabled). ppllaaiinn__tteemmpp A temporary breakpoint (enabled). pprriinntt `PPrriinntt (())' button. pprrooppeerrttiieess `PPrrooppeerrttiieess' button. rroottaattee `RRoottaattee (())' button. sseett `SSeett (())' button. sshhooww `SShhooww (())' button. ssiiggnnaall__aarrrrooww The execution pointer (stopped by signal). uunnddiissppllaayy `UUnnddiissppllaayy (())' button. DDD 3.1.1 1998-12-06 102 ddd(1) ddd(1) uunnwwaattcchh `UUnnwwaattcchh (())' button. wwaattcchh `WWaattcchh (())' button. EENNVVIIRROONNMMEENNTT DDD is controlled by the following environment variables: DDDDDD__NNOO__SSIIGGNNAALL__HHAANNDDLLEERRSS If set, DDD does not catch fatal errors. This is sometimes useful when debugging DDD. DDDDDD__SSTTAATTEE Root of DDD state directory. Default is `$$HHOOMMEE//..dddddd//'. DDDDDD__SSEESSSSIIOONN If set, indicates a session to start, overriding all options. This is used by DDD when restarting itself. DDDDDD__SSEESSSSIIOONNSS DDD session directory. Default is `$$DDDDDD__SSTTAATTEE//sseessssiioonnss//'. EEDDIITTOORR The text editor to invoke for editing source code. See the `eeddiittCCoommmmaanndd' resource, above. VVSSLL__IINNCCLLUUDDEE Where to search for VSL include files. Default is the current directory. WWWWWWBBRROOWWSSEERR The WWW browser to invoke for viewing the DDD WWW page. See the `wwwwwwCCoomm-- mmaanndd' resource, above. XXEEDDIITTOORR The X editor to invoke for editing source code. See the `eeddiittCCoommmmaanndd' resource, above. The following environment variables are set by DDD: DDDDDD Set to a string indicating the DDD version. By testing whether DDDDDD is set, a debuggee (or inferior debugger) can determine whether it was invoked by DDD. TTEERRMM Set to `dduummbb', the DDD terminal type. This is set for the inferior debugger only. If the debuggee runs in a sepa- rate execution window, the debuggee's DDD 3.1.1 1998-12-06 103 ddd(1) ddd(1) TTEERRMM value is set according to the `tteerrmmTTyyppee' resource (see `RREESSOOUURRCCEESS', above). TTEERRMMCCAAPP Set to `' (none), the DDD terminal capabilities. PPAAGGEERR Set to `ccaatt', the preferred DDD pager. FFIILLEESS $$HHOOMMEE//..dddddd// DDD state directory. $$HHOOMMEE//..dddddd//iinniitt Individual DDD resource file. DDD options are saved here. $$HHOOMMEE//..dddddd//hhiissttoorryy Default DDD command history file. $$HHOOMMEE//..dddddd//lloocckk DDD lock file; indicates that a DDD is running. $$HHOOMMEE//..dddddd//lloogg Trace of the current interaction between DDD and the inferior debugger. $$HHOOMMEE//..dddddd//sseessssiioonnss// DDD session directory. One subdirec- tory per session. $$HHOOMMEE//..dddddd//sseessssiioonnss//_s_e_s_s_i_o_n//ddddddccoorree DDD core file for _s_e_s_s_i_o_n. $$HHOOMMEE//..dddddd//sseessssiioonnss//_s_e_s_s_i_o_n//iinniitt DDD resource file for _s_e_s_s_i_o_n. $$HHOOMMEE//..dddddd//sseessssiioonnss//_s_e_s_s_i_o_n//hhiissttoorryy DDD command history for _s_e_s_s_i_o_n. $$HHOOMMEE//..dddddd//sseessssiioonnss//..dddddd// The DDD `restart' session. $$HHOOMMEE//..dddddd//ttiippss DDD tips resource file. Contains the number of the next tip of the day. $$HHOOMMEE//..ggddbbiinniitt GDB initialization file. $$HHOOMMEE//..ddbbxxiinniitt DBX initialization file. $$HHOOMMEE//..ddbbxxrrcc Alternate DBX initialization file. $$HHOOMMEE//..xxddbbrrcc XDB initialization file. $$HHOOMMEE//..ggnnuupplloott Gnuplot initialization file. $$HHOOMMEE//..ddddddiinniitt Old-style DDD initialization file; used only if $$HHOOMMEE//..dddddd//iinniitt does not exist. SSEEEE AALLSSOO XX(1), ggddbb(1), ddbbxx(1), xxddbb(1), ppeerrllddeebbuugg(1), rreemmsshh(1), rrsshh(1), ggnnuupplloott(1), `ggddbb' entry in iinnffoo. _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. _j_d_b_-_-_T_h_e _J_a_v_a _D_e_b_u_g_g_e_r, at hhttttpp::////jjaavvaa..ssuunn..ccoomm// (and its mirrors) in //pprroodd-- uuccttss//jjddkk//11..11//ddooccss//ttoooollddooccss//ssoollaarriiss//jjddbb..hhttmmll _J_a_v_a _L_a_n_g_u_a_g_e _D_e_b_u_g_g_i_n_g, at hhttttpp::////jjaavvaa..ssuunn..ccoomm// (and its DDD 3.1.1 1998-12-06 104 ddd(1) ddd(1) mirrors) in //pprroodduuccttss//jjddkk//11..11//ddeebbuuggggiinngg// _T_h_e _P_y_t_h_o_n _L_a_n_g_u_a_g_e, at hhttttpp::////wwwwww..ppyytthhoonn..oorrgg// and its mirrors. _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 Lⁿtkehaus, Computer Science Report 95-07, Technische UniversitΣt 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 Lⁿtkehaus, Diploma Thesis, Technische UniversitΣt Braunschweig, 1994. The DDD _F_T_P _s_i_t_e_, ffttpp::////ffttpp..iippss..ccss..ttuu--bbss..ddee//ppuubb//llooccaall//ssoofftteecchh//dddddd// The DDD _W_W_W _p_a_g_e_, hhttttpp::////wwwwww..ccss..ttuu--bbss..ddee//ssoofftteecchh//dddddd// The DDD _M_a_i_l_i_n_g _L_i_s_t_, dddddd--uusseerrss@@iippss..ccss..ttuu--bbss..ddee For more information on this list, send a mail to dddddd--uusseerrss--rreeqquueesstt@@iippss..ccss..ttuu--bbss..ddee . LLIIMMIITTAATTIIOONNSS GGeenneerraall LLiimmiittaattiioonnss 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 debug- ger. This problem can be avoided by running the program in the separate execution window. Output that confuses DDD includes: +o Primary debugger prompts (e.g. `((ggddbb)) ' or `((ddbbxx)) ') +o Secondary debugger prompts (e.g. `>>') +o Confirmation prompts (e.g. `((yy oorr nn)) ') +o Prompts for more output (e.g. `PPrreessss RREETTUURRNN ttoo ccoonn-- ttiinnuuee') +o Display output (e.g. `$$ppcc == 00xx11223344') DDD 3.1.1 1998-12-06 105 ddd(1) ddd(1) If your program outputs any of these strings, you should run it in the separate execution window. If the inferior debugger changes the default TTY settings, for instance through a `ssttttyy' command in its initializa- tion file, DDD will likely become confused. The same applies to debugged programs which change the default TTY settings. LLiimmiittaattiioonnss uussiinngg GGDDBB Some GDB settings are essential for DDD to work correctly. These settings with their correct values are: sseett hheeiigghhtt 00 sseett wwiiddtthh 00 sseett vveerrbboossee ooffff sseett pprroommpptt ((ggddbb)) DDD sets these values automatically when invoking GDB; if these values are changed, there may be some malfunctions, especially in the data display. When debugging at the machine level with GDB 4.12 and ear- lier as inferior debugger, use a `ddiissppllaayy //xx $$ppcc' command to ensure the program counter value is updated correctly at each stop. You may also enter the command in $$HHOOMMEE//..ggddbbiinniitt or (better yet) upgrade to the most recent GDB version. LLiimmiittaattiioonnss uussiinngg DDBBXX When used for debugging Pascal-like programs, DDD does not infer correct array subscripts and always starts to count with 1. With some DBX versions (notably Solaris DBX), DDD strips C-style and C++-style comments from the DBX output in order to interpret it properly. This also affects the output of the debugged program when sent to the debugger console. Using the separate execution window avoids these problems. In some DBX versions (notably DEC DBX and AIX DBX), there is no automatic data display. As an alternative, DDD uses the DBX `pprriinntt' command to access data values. This means that variable names are interpreted according to the cur- rent frame; variables outside the current frame cannot be displayed. LLiimmiittaattiioonnss uussiinngg XXDDBB There is no automatic data display in XDB. As a workaround, DDD uses the `pp' command to access data val- ues. This means that variable names are interpreted according to the current frame; variables outside the DDD 3.1.1 1998-12-06 106 ddd(1) ddd(1) current frame cannot be displayed. LLiimmiittaattiioonnss uussiinngg JJDDBB There is no automatic data display in JDB. As a workaround, DDD uses the `dduummpp' command to access data values. This means that variable names are interpreted according to the current frame; variables outside the cur- rent frame cannot be displayed. The JDB `dduummpp' and `pprriinntt' commands do not support expres- sion evaluation. Hence, you cannot display arbitrary expressions. Parsing of JDB output is quite CPU-intensive, due to the recognition of asynchronous prompts (any thread may output anything at any time, including prompts). Hence, a pro- gram producing much console output is likely to slow down DDD considerably. In such a case, have the program run with --ddeebbuugg in a separate window and attach JDB to it using the --ppaasssswwdd option. LLiimmiittaattiioonnss uussiinngg PPeerrll There is no automatic data display in Perl. As a workaround, DDD uses the `xx' command to access data val- ues. This means that variable names are interpreted according to the current frame; variables outside the cur- rent frame cannot be displayed. RREEPPOORRTTIINNGG BBUUGGSS 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 `BBUUGGSS' 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 :-) WWhheerree ttoo SSeenndd BBuugg RReeppoorrttss We recommend that you send bug reports for DDD via elec- tronic mail to dddddd--bbuuggss@@iippss..ccss..ttuu--bbss..ddee As a last resort, send bug reports on paper to: Technische UniversitΣt Braunschweig Abteilung Softwaretechnologie DDD-Bugs Bⁿltenweg 88 D-38092 Braunschweig GERMANY IIss iitt aa DDDDDD BBuugg?? Before sending in a bug report, try to find out whether the problem cause really lies within DDD. A common cause DDD 3.1.1 1998-12-06 107 ddd(1) ddd(1) 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 dddddd ----cchheecckk--ccoonnffiigguurraattiioonn checks for common problems and gives hints on how to repair them. Another potential cause of problems is the inferior debug- ger; occasionally, they show bugs, too. To find out whether a bug was caused by the inferior debugger, run DDD as dddddd ----ttrraaccee This shows the interaction between DDD and the inferior debugger on standard error while DDD is running. (If `----ttrraaccee' is not given, this interaction is logged in the file `$$HHOOMMEE//..dddddd//lloogg'.) Compare the debugger output to the output of DDD and determine which one is wrong. HHooww ttoo RReeppoorrtt BBuuggss 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. WWhhaatt ttoo IInncclluuddee iinn aa BBuugg RReeppoorrtt To enable us to fix a DDD bug, you _m_u_s_t include the fol- lowing information: DDD 3.1.1 1998-12-06 108 ddd(1) ddd(1) +o Your DDD configuration. Invoke DDD as dddddd ----ccoonnffiigguurraattiioonn 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., `ggddbb--44..1177' or `ddbbxx aass sshhiippppeedd wwiitthh SSoollaarriiss 22..66'). +o The compiler you used to compile DDD and its version (e.g., `ggcccc--22..88..11'). +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 A _l_o_g _f_i_l_e showing the interaction between DDD and the inferior debugger. By default, this interaction is logged in the file `$$HHOOMMEE//..dddddd//lloogg'. Include all trace output from the DDD invocation up to the first bug occurrence; insert own comments where necessary. +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. HHIISSTTOORRYY 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__ⁿ_t_k_e_h_a_u_s (now _D_o_r_o_t_h_e_a _K_r_a_b_i_e_l_l) realized DDD as her Diploma Thesis, 1994. The original DDD had no source window; this was added by Dorothea during the winter of 1994-1995. In the first quarter of 1995, finally, Andreas completed DDD by adding DDD 3.1.1 1998-12-06 109 ddd(1) ddd(1) command and execution windows, extensions for DBX and remote debugging as well as configuration support for sev- eral architectures. Since then, Andreas has further main- tained and extended DDD, based on the comments and sugges- tions of several DDD users around the world. See the com- ments in the DDD source for details. Major DDD events: April, 1995 DDD 0.9: First DDD beta release. May, 1995 DDD 1.0: First public DDD release. December, 1995 DDD 1.4: Machine-level debugging, glyphs, EMACS integration. October, 1996 DDD 2.0: Color displays, XDB support, generic DBX support, command tool. May, 1997 DDD 2.1: Alias detection, button tips, status displays. November, 1997 DDD 2.2: Persistent sessions, display shortcuts. June, 1998 DDD 3.0: Icon tool bar, Java support, JDB support. December, 1998 DDD 3.1: Data plotting, Perl support, Python support, Undo/Redo. EEXXTTEENNDDIINNGG DDDDDD If you have any contributions to be incorporated into DDD, please send them to `dddddd@@iippss..ccss..ttuu--bbss..ddee'. For sugges- tions on what might be done, see the file `TTOODDOO' in the DDD distribution. DDDDDD NNEEEEDDSS YYOOUURR SSUUPPPPOORRTT!! DDD needs your support! If you have any success stories related to DDD, please write them down on a picture post- card and send them to us: Technische UniversitΣt Braunschweig Abteilung Softwaretechnologie Bⁿltenweg 88 D-38092 Braunschweig GERMANY You may also leave a message in the _D_D_D _G_u_e_s_t_b_o_o_k. It is accessible via the DDD WWW page, hhttttpp::////wwwwww..ccss..ttuu--bbss..ddee//ssoofftteecchh//dddddd// . PPRRIINNTTIINNGG TTHHIISS MMAANNUUAALL Invoke DDD with the `----mmaannuuaall' option to show this manual page on standard output. This text output is suitable for installation as formatted manual page (as `//uussrr//llooccaall//mmaann//ccaatt11//dddddd..11' or similar) on UNIX systems. A PostScript copy of this manual page, including several DDD 3.1.1 1998-12-06 110 ddd(1) ddd(1) DDD screen shots and diagrams, is included in the DDD source distribution and available separately as `dddddd..mmaann..ppss..ggzz' in ffttpp::////ffttpp..iippss..ccss..ttuu--bbss..ddee//ppuubb//llooccaall//ssoofftteecchh//dddddd//ddoocc// 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 `//uussrr//llooccaall//mmaann//mmaann11//dddddd..11' or similar), is included in the DDD source distribution. CCOOPPYYRRIIGGHHTT DDDDDD DDD is Copyright (C) 1995, 1996, 1997, 1998 Technische UniversitΣt Braunschweig, Germany. DDD is free software; you can redistribute it and/or mod- ify it under the terms of the GNU General Public License as published by the Free Software Foundation; either ver- sion 2 of the License, or (at your option) any later ver- sion. DDD is distributed in the hope that it will be useful, but _w_i_t_h_o_u_t _a_n_y _w_a_r_r_a_n_t_y; without even the implied warranty of _m_e_r_c_h_a_n_t_a_b_i_l_i_t_y or _f_i_t_n_e_s_s _f_o_r _a _p_a_r_t_i_c_u_l_a_r _p_u_r_p_o_s_e. See the License for more details. You should have received a copy of the License along with DDD. If not, invoke DDD with the `----lliicceennssee' option; this will print a copy on standard output. To read the License from within DDD, use `HHeellpp-->>DDDDDD LLiicceennssee'. DDDDDD MMaannuuaall This DDD manual is Copyright (C) 1995, 1996, 1997, 1998 Technische UniversitΣt Braunschweig, Germany. Permission is granted to make and distribute verbatim copies of this manual 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 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 into another language, under the above con- ditions for modified versions, except that this permission DDD 3.1.1 1998-12-06 111 ddd(1) ddd(1) notice may be included in translations approved by the Free Software Foundation instead of in the original English. DDD 3.1.1 1998-12-06 112