NAME

dbxtool − window- and mouse-based debugging tool

SYNOPSIS

dbxtool [ −i ] [ −I dir ] [ objfile [ corefile ] ]

DESCRIPTION

Dbxtool is a source-level debugger with a window and mouse-based user interface.  It accepts the same commands as dbx (1), but provides a more convenient user interface.  Using the mouse, one can set breakpoints, examine the values of variables, control execution, peruse source files and so on.  Dbxtool has separate subwindows for viewing source code, entering commands and several other uses. It functions in the suntools(1) environment, so that the standard tool manager actions, such as moving, stretching, exposing etc. can be applied to it.

Objfile is an object file produced by cc (1), f77 (1) or pc (1) (or a combination of them) with the appropriate flag (−g) specified to produce symbol information in the object file.  IMPORTANT: every stage of the compilation process, including the loading phase, must include the −g option.  If no objfile is specified, one uses the debug command to specify the program to be debugged.  The object file contains a symbol table which includes the names of all the source files translated by the compiler to create it.  These files are available for perusal while using the debugger. 

If a file named core exists in the current directory or a corefile is specified, dbxtool can be used to examine the state of the program when it faulted. 

Debugger commands in the file .dbxinit are executed immediately after the symbolic information is read, if that file exists in the current directory, or in the user’s home directory if .dbxinit doesn’t exist in the current directory. 

OPTIONS

−iForce dbxtool to act as though standard input were a terminal. 

−I dirAdd dir to the list of directories that are searched when looking for a source file.  Normally dbxtool looks for source files in the current directory and then in the directory where objfile is located.  The directory search path can also be set with the use command.  Multiple −I options may be given. 

SUBWINDOWS

Dbxtool consists of five subwindows.  From top to bottom they are:

statusthe location of the point at which execution is currently stopped and a description of the lines displayed in the source subwindow are displayed in the status subwindow.

sourcedisplays source text of the program being debugged. 

buttonssoftware buttons corresponding to the most frequently used commands are provided in the buttons subwindow. Picking a button with the mouse invokes the command associated with that button.

commandprovides a typing interface to dbxtool to supplement the buttons subwindow and mouse. Also, most of the output generated by commands appears in this subwindow.

displayprovides a way of tracking the values of selected variables by updating a display of their values each time execution stops. 

SCROLLING

The source, command, and display windows have scroll bars to facilitate browsing their contents. The scroll bar is at the left edge of each window. The bar is a medium gray background with a darker gray area superimposed over it indicating the portion of the source file, command transcript or display currently visible in the window.  Note that the size of the darker gray area corresponds to the number of characters visible in the source window, not the number of lines. 

Within the scroll bar, the mouse buttons have the following functions:

leftscroll forward, move towards the end of the file

middlescroll to absolute position in the text

rightscroll backwards, move towards the beginning of the file

Positioning the cursor within the scroll bar next to a given line and clicking the left button causes the line to move to the top of the window.  Clicking the right button causes the top line in the window to move to the position of the cursor. 

The middle button treats the scroll bar as a thumb bar.  The top of the thumb bar represents the beginning of the text and the bottom represents the end of the text.  Clicking the middle button in the scroll bar picks a point within the text relative to its entire size.  This point is displayed at the top of the window. 

THE SOURCE WINDOW

The source window displays the text of the program being debugged. Initially, it displays text from either the main routine, if there is no core file, or the point at which execution stopped, if there is a core file. Whenever execution stops during a debugging session, it displays the point at which it stopped. The file command can be used to switch the source window to another file; the focus of attention moves to the beginning of the new file. Similarly, the func command can be used to switch the source window to another function; the new focus of attention is the first executable line in the function.

Breakpoints are indicated in the source window by a solid stop sign at the beginning of the line. The point at which execution is currently stopped is marked by a rightward pointing outlined arrow.

COMMAND CONSTRUCTION

One can either type commands to dbxtool or construct them with the selection and button mechanism (if a button is provided for the command), but typing and buttons cannot be combined.

A selection is made by pointing the mouse at one end of the desired text and clicking the left button and then pointing the mouse at the other end of the text and clicking the middle button.  The selected text is hilighted in reverse-video.  In the command window, pressing the right button brings up a “stuff” menu, which, when chosen, causes the selected text to be stuffed into the command window’s input stream as if it had been typed from the keyboard.  Holding down the SHIFT key and clicking the right button is an accelerator that automatically stuffs the selection without bringing up a menu. 

The software buttons operate in a postfix manner.  That is, one first selects the arguments and then clicks the software button with the left mouse button.  Each command interprets the selection as appropriate for that command. 

There are five ways in which dbxtool may interpret a selection:

literalA selection may be interpreted as representing exactly the selected material. 

expandA selection may be interpreted as representing exactly the selected material, with the exception that it will be expanded if either the first or last character of the selection is an alphanumeric character or underscore.  It will be expanded to the longest enclosing sequence of alphanumeric characters or underscores.  Selections made outside of dbxtool cannot be expanded and are interpreted as exactly the selected text. 

linenoA selection in the source window may be interpreted as representing the (line number of the) first source line containing all or some of the selection.

commandA selection in the command window may be interpreted as representing the command containing the selection.
 

ignoreButtons may ignore a selection. 

COMMAND BUTTONS

The standard set of command buttons in the buttons window is as follows.

printPrints the value of a variable or expression.  It uses the whole selection, except that if the selection string begins or ends with an alphanumeric character or underscore, the string is first expanded from both ends to the longest enclosing string containing only alphanumerics and underscores.  Thus, an identifier can be printed by selecting as little as one character within it. 

nextExecutes one source line and then stops execution, except that if the current source line is a procedure or function call it executes through the called routine before stopping.  The next button ignores the selection. 

stepExecutes one source line and then stops execution again.  If the current source line is a procedure or function call it stops at the first executable line within the procedure or function.  The step button ignores the selection. 

stop atSets a breakpoint at a given source line.  It interprets a selection in the source window as representing the line number associated with the first line of the selection.

contResumes execution from the point at which it is currently stopped.  The cont button ignores the selection. 

stop inSets a breakpoint at the first line of a given function or procedure.  It interprets the selection in the same manner as the print button, i.e. selecting an occurrence of a procedure or function name causes a breakpoint to be set in the corresponding routine. 

redoCauses a selected command to be repeated.  It interprets a selection in the command window as representing the command containing the selection.

CHOOSING YOUR OWN BUTTONS

The button command may be used to define command buttons in the buttons window. It may be used in .dbxinit to define buttons in addition to the default set of buttons, or during a debugging session to add new buttons. The first argument to button is the selection interpretation to be used for the button and the remainder is the command to be associated with it.  The default set of buttons can be replicated by the sequence

button expand print
button ignore next
button ignore step
button lineno stop at
button ignore cont
button expand stop in
button command redo

The unbutton command my be used in .dbxinit to remove a default button from the buttons window, or during a debugging session to remove any existing buttons. The arguments to the unbutton command are the same as for the button command — a selection interpretation followed by a command. 

THE DISPLAY WINDOW

The display window is used to provide continual feedback of the values of a selected set of variables. The display command specifies variables to appear in the display window and undisplay removes them.  Each time execution of the program being debugged stops, the values of the displayed variables are updated. 

CONTROLLING THE DBXTOOL ENVIRONMENT

The toolenv command provides control over several facets of the dbxtool window environment, including the font, the vertical size of the source, command and display windows, the horizontal size of the tool, and the minimum number of lines between the top or bottom of the source window and the arrow. These are chiefly useful in the .dbxinit file to control initialization of the tool, but may be issued at any time.

OTHER ASPECTS OF DBXTOOL

The commands, expression syntax, scope rules, etc. of dbxtool are identical to those for dbx (1).  Three of the commands, toolenv, button, and unbutton  affect only dbxtool, and so they are described below.  See the dbx (1) manual entry for a description of the others. 

toolenv attribute value
Set attributes of the dbxtool window.  This command has no effect in dbx.  The toolenv command with no arguments prints the current values of the attributes.  The possible attribute-value pairs and their interpretations are as follows:

font fontfile
change the font to that found in fontfile; default is taken from the DEFAULT_FONT shell variable

width nchars
change the width of the tool window to nchars characters; default is 80 characters

srclines nlines
make the source subwindow nlines high; default is 20 lines

cmdlines nlines
make the command subwindow nlines high; default is 12 lines

displines nlines
make the display subwindow nlines high; default is 3 lines

topmargin nlines
keep the line with the arrow at least nlines from the top of the source subwindow; default is  3 lines

botmargin nlines
keep the line with the arrow on it at least nlines from the bottom of the source subwindow; default is 3 lines

button selection command-name
Associate a button with a command in dbxtool.  This command has no effect on dbx.  Selection is described in the Command Construction section above. 

unbutton selection command-name
Remove a button from the buttons window.  The button with a matching selection and command-name is removed. 

FILES

a.outdefault object file
coredefault core file
~/.dbxinitinitial commands

SEE ALSO

cc(1)C compiler
f77(1)FORTRAN compiler
pc(1)Pascal compiler

COMMENTS

The comments listed for dbx (1) apply to dbxtool as well. 

BUGS

The bugs listed for dbx (1) apply to dbxtool as well. 

The selection mechanism of ttytool and dbxtool should be the same.  Dbxtool does not have multi-clicking selections. 

The interaction between scrolling in the source subwindow and dbx’s regular expression search commands is wrong. Scrolling should affect where the next search begins, but it does not.

Sun Release 2.0  —  Last change: 26 March 1985