XDB(1X10) COMMAND REFERENCE XDB(1X10) NAME xdb - experimental X windows interface to dbx(1) SYNOPSIS {x|X}db [ -t { xterm | tterm }] [ <other dbx options> ] dbx -{x|X} [ -t { xterm | tterm }] [ <other dbx options> ] DESCRIPTION This manual page describes an experimental X windows interface to dbx(1). For information about the basic functionality and command set, see dbx(1). The command Xdb is the same as the command dbx -X and the command xdb is the same as the command dbx -x. All four of these commands are invocations of dbx(1) specifying that the X windows interface is to be used. Commands: The following dbx commands, in addition to the standard set, are available when using the X windows interface: button n button-label Adds a new command button to the Button-Box pane (described later). The new button will be added after the nth existing button. When the button is pressed, a dbx alias corresponding to it is invoked. The alias invoked is the button label string with "_button_pressed" appended. unbutton { n | button-label } Deletes a button from the Button-Box pane. If a number is given as an argument, then the nth button is deleted. Otherwise the button with the matching label is deleted. Only the button is deleted, any associated dbx alias is left untouched. xdb Window: In this experimental version of xdb only limited use is made of multiple windows. Besides the main window described here, there is a rudimentary help window; terminal emulation windows are spawned for the gripe, edit, and sh commands and optionally for the process being debugged (see the -t option in this document). The main xdb window is comprised of a title bar and 6 or 7 panes. Each pane extends the full width of the window containing it. Each type of pane visualizes or interfaces to some specific debugging capability or feature. Because of this specificity, not all types of panes are valid at a given time. Printed 4/6/89 1
XDB(1X10) COMMAND REFERENCE XDB(1X10) Most types of panes have a tag-area. Usually the tag-area contains a text label (like "Stack Trace)" and sits at the top of the pane. In one case, the tag-area covers the entire pane, but has holes in it (see Button-Box Pane in this document). When the mouse is in the tag-area, the pop-up menu is always the same: it is titled "pane menu" and is used for managing panes; it contains the following commands: new-pane, cut- pane, paste before, paste-after, and new-type. In this experimental version, however, these commands are not implemented. When the mouse is not in the tag-area, then the pop-up menu depends on the type of pane. The particular menus with the panes are discussed here. Menus: The xdb interface uses pop-up menus: the middle mouse button is pressed and a menu pops up on the screen where the cursor was. A selection is made by sliding the cursor up or down the menu until the desired selection is highlighted and then releasing the button. The menu disappears and the requested command is executed. All menu commands can be reversed, (except an undo function) when they are executed. If such a function exists when any menu is popped up, then that menu will contain an undo command that, if picked, will execute the saved undo function. In the description of menus, it should be taken as a given that any menu could have an undo command. In this experimental version, however, no commands can be undone. Title Bar: The title bar is really a specialized pane. It has no tag-area but it does have a pop-up menu. The title consists of the id of the process being debugged, the name of the debugger (xdb), and the window number. A mouse-click on the title text iconifies the window. The pop-up menu for the title bar is used to control the window and is titled "title menu". It contains the following commands: close-window, new-window, new-pane, and change-process. In this experimental version, however, these commands are not implemented. Status Pane: This pane shows the id and status of the process being debugged - if it's running or if it's halted. If the process is halted, then the number of the line about to be executed is displayed; if no debug information is available for the current module, then the hex address of the instruction about to be executed is displayed. This pane has no tag-area. Printed 4/6/89 2
XDB(1X10) COMMAND REFERENCE XDB(1X10) The pop-up menu for the process status pane is used to control the process; it contains the following commands: run, step, next, cont, and halt. All of these, except halt, invoke the dbx command of the same name. Selecting the halt menu item is equivalent to keying <ctrl C> in dbx. Stack Pane: This scrollable pane displays the stack of the process much as the dbx(1) where command does. The tag-area simply contains the legend "Stack Trace" and displays the number of active subroutine levels. The pop-up menu for a stack trace pane contains commands that operate on the line that has been selected; it contains the commands edit and peruse. In this experimental version, however, these commands are not implemented. Source Panes: The main xdb window contains two source panes. The bottom source pane shows the source for the most deeply nested subroutine for which the source is available. The top source pane shows the source for the next most deeply nested subroutine for which the source is available. In addition to a scroll bar, each source pane is divided into a line number region and a text region. The line number region displays the number of the line being displayed in the text region and contains an area used to mark lines that have been break-pointed or traced. Mouse usage inside the text region is that of a standard text widget. In the line number region, the left mouse button can be used to set or delete break points on a line and the right mouse button can be used to trace or untrace a line. A source pane keeps track of two special source lines: the active line and the current line. The active line is the one about to be executed and is surrounded by a box. The current line has its number highlighted in the line numbers region and is set when text is selected or the insert point is moved. The line number region has a pop-up menu titled "lines menu"; it contains the following commands: set-brkpnt, delete-brkpnt, trace-line, and untrace-line. If the current line is break-pointed, then the menu will contain the delete-brkpnt command, otherwise it will contain the set- brkpnt command. If the current line is traced, the menu will contain the untrace-line command, otherwise it will contain the trace-line command. The functionality of this menu can be accessed directly by the mouse. The text region has a pop-up menu titled "source menu"; it contains the following commands: print, up-level, down- level, edit, search, center-active, and center-current. The print command simply takes the selected text, prepends a Printed 4/6/89 3
XDB(1X10) COMMAND REFERENCE XDB(1X10) "print " to it and passes everything to the dbx parser. If the selected text is a variable, this has the effect of printing its value. The up-level and down-level menu commands cause the execution of the dbx(1) commands up and down, respectively. The edit menu command invokes an editor, in its own window, on the source file being displayed. The search menu command gives a prompt; the prompt requests a search pattern and contains buttons to search forward, search reverse, or cancel the search. The center-active menu command updates the source display so that the active line is centered. The center-current menu command updates the source display so that the current line is centered. The tag-area for a source pane displays the stack level associated with the pane, the name of the source file, and the subroutine call active at this level. Clicking the left mouse button in the tag-area executes the center-active menu command. Clicking the right mouse button in the tag-area executes the center-current menu command (see above). Button-Box Pane: This scrollable pane contains buttons that are defined by the user. The user can manage this pane using the dbx(1) commands button and unbutton, or by using the non-tag-area pop-up menu available in this pane. When the mouse curser is within a button in this pane, the pop-up menu is titled "button menu"; it contains the following commands: delete, add-before, and add-after. The delete menu command invokes an unbutton dbx(1) command, deleting the button that the mouse cursor was within. The add-before and add-after menu commands invoke dbx(1) button commands to add the new button before or after the button that the mouse cursor was within. The label of the new button is prompted for. The tag-area for this pane consists of the area in the pane that is not taken by some button. dbx I/O Pane: This scrollable pane is a place where the user can interact directly with dbx and it can serve as a log. The pane operates in one of three modes: verbose, terse, and silent. In verbose mode, the strings sent to the dbx(1) parser as a result of a button on menu command are first displayed in this pane. In terse mode, only the output from dbx(1) is displayed in the pane. In silent mode, only keystrokes made in the pane are displayed. When a carriage return is typed in this pane, the line containing the insert cursor is stripped of any dbx(1) prompts and sent to the dbx parser; this allows the full power of the text widget editing commands to be used. The Printed 4/6/89 4
XDB(1X10) COMMAND REFERENCE XDB(1X10) stty special characters are also meaningful. The pop-up menu is titled "dbx I/O menu"; it contains the following commands: verbose, terse, silent, word break, and search. The first three menu commands are mutually exclusive and are used to select the mode of the pane. The word break menu command is used to set and reset the word break option of the text widget. If word break is set, long lines are wrapped at a word boundary. If word break is reset, long lines are truncated. The search menu command allows fast positioning within the pane and works like the search menu command in a source pane. The tag-area for this pane simply contains the string "dbx I/O" and shows what mode the pane is in. Process I/O Pane: The process being debugged is connected through a pseudo-tty to this pane. Characters written by the user process to its standard out, or standard error is displayed in this pane. Characters typed when the mouse is in this pane are available to be read by the process from its standard input. If the -t option is used, then this pane is not used. Instead, the process being debugged is connected through a pseudo-tty to its own terminal emulator window. The pop-up menu for this pane is titled "proc I/O menu"; it contains the following commands: raw, cooked, cbreak, nl, echo, tabs, crt, crtbs, crterase, and stty. In this experimental version, however, these commands are not implemented. The tag-area simply contains the legend "Process nnnn I/O", where nnnn is the id of the process being debugged. OPTIONS -X Use the experimental X windows interface. -x Same as -X option, except that the xdb window is detached from the original. -t [xterm|tterm] Used with the X windows interface to attach the process being debugged to its own xterm(1x10) or tterm(1x10) window. FILES dbxIOdump When dbx terminates and the X windows interface is being used, the final content of the dbx I/O pane, including any text scrolled off screen, is appended to this file. Printed 4/6/89 5
XDB(1X10) COMMAND REFERENCE XDB(1X10) .Xresources This file contains user-specified resources as per the X10 toolkit (see CAVEATS). DIAGNOSTICS Fatal error messages are displayed in their own window. All other diagnostic messages are displayed in the dbx I/O pane. VARIABLES XDBSTATVSIZE Height of status pane in pixels. Default is 20. XDBSTACKVSIZE Height of stack pane in pixels. Default is 150. XDBSOURCE1VSIZE Height of source pane 1 in pixels. Default is 150. XDBSOURCE2VSIZE Height of source pane 2 in pixels. Default is 150. XDBBUTTONVSIZE Height of button box pane in pixels. Default is 25. XDBDBXIOVSIZE Height of dbx I/O pane in pixels. Default is 150. XDBPROCIOVSIZE Height of process I/O pane in pixels. Default is 150. XDBVSIZE Minimum height of entire xdb window. Default is the sum of other "VSIZE" variables. If the specified height is greater than the default would be, the extra is given to the dbx I/O pane; if the specified height is less than the default, then the default is used. XDBHSIZE Width of the entire xdb window in pixels. Default is 300. XDBSTACKSTR Number of bytes allocated for stack pane string. Default is 102400. XDBDBXIOSTR Number of bytes allocated for dbx I/O pane string. Default is 102400. XDBPROCIOSTR Number of bytes allocated for process I/O pane string. Default is 102400. Printed 4/6/89 6
XDB(1X10) COMMAND REFERENCE XDB(1X10) XDBDBXBIGBUF Number of bytes allocated for dbx I/O pane output buffer. Default is 10240. XDBPROCBIGBUF Number of bytes allocated for process I/O pane output buffer. Default is 10240. CAVEATS There are many parameters that can be set by the user using the .Xresources file. However, there are problems with the resource manager part of the X10 toolkit. SEE ALSO dbx(1), dbx(5) Printed 4/6/89 7
%%index%% na:288,100; sy:388,615; de:1003,2951;4314,3548;8222,3565;12147,3483;15990,2243; op:18233,625; fi:18858,334;19552,213; di:19765,261; va:20026,3504;23890,595; ca:24485,276; se:24761,152; %%index%%000000000218