dbXtra(CP) 6 January 1993 dbXtra(CP) Name dbXtra - dbx-based Motif/X11 interface-oriented debugger Syntax dbXtra [ X11 flag | dbXtra flag ] ... [objfile [ coredump | processid ] ] Description dbXtra is a debugger based on dbx, employing a Motif user interface. It is used for source-level debugging and program execution under SCO UNIX System V/386. objfile is an object file produced by cc(CP), using the -g flag to include symbol information. An object file created in this way contains a symbol table that includes information about the source code used to create the program. Only COFF files may be debugged using dbXtra. If the file .dbXtrarc exists in the current directory or your home direc- tory then the dbXtra commands in it are executed on start-up. If a file called core exists in the current directory or a coredump file is specified on the command line, dbXtra can examine the state the pro- gram was in when it faulted. If a processid is specified, dbXtra attempts to attach to the given pro- cess. This succeeds only if you are running on a version of SCO UNIX that supports the ptrace(S) attach request. If this is supported, pro- cesses can be attached to or detached from within dbXtra. You may need to set the environment variable DISPLAY in order to run dbXtra. This variable informs your system of the address of the X display you are using. Command line options Any X11 command line option specified will be passed on to X11. The dbXtra command line options are: -r Execute objfile immediately. If it terminates successfully, dbXtra exits. Otherwise the reason for termination is reported and you can either enter the debugger or let the program fault. dbXtra reads from /dev/tty when -r is specified and standard input is not a terminal. -x Ignore cross-reference file when initializing dbXtra. -F dbXtra assumes that file-scoped structure/union/enum definitions with the same name are identical. Specifying -F may significantly decrease dbXtra's memory usage (and startup time) for large pro- grams. This happens because most structure definitions are in #include files included in several source files; this causes many copies of the symbol table information to reside in the various corresponding .o files. Using this option means that the symbol table in the debugger may not match your program in some cases. The default is to assume that structure/union/enum definitions with the same name may have different definitions. -I dir Add dir to the list of directories that are searched when looking for a source file. Normally dbXtra looks for source files in the current directory and in the directory where objfile is located. The directory search path can also be set with the use command. -c file Execute the dbXtra commands in file before reading from standard input. -C++ Assume C++ mode. dbXtra works in C++ mode if C++ information is present in objfile, and attempts to find extended debugging infor- mation files. -C Specifically request C debugging only. C++ information is not used and toggling to C++ debugging mode is not allowed. If neither -C++ nor -C is specified, dbXtra looks for the function main() in the file being debugged; if this function is found, dbXtra assumes C++ mode. The Motif interface The Motif interface to the dbXtra debugger conforms with the Motif style guide and has the ``look and feel'' of Motif applications. Refer to the OSF/Motif Style Guide for information on using the various graphical ele- ments. When dbXtra is invoked it creates one window, called the main window, with two panes within it. The pane at the top will be referred to as the source window, and the pane at the bottom will be referred to as the com- mand window. The main window The main window is the principal window for user interaction during a debugging session. dbXtra's main window is composed of a title bar, a menu bar on the top, command buttons on the left hand side, and the source window pane as well as the command window pane. The title bar The title bar displays the current debugging mode. This is [C++] for the C++ mode and [C] for the C mode. It also displays the current file and function names. The source window pane The source window shows the current position in the current file. This is a read-only view of the file--the program cannot be modified. The line numbers and breakpoint status are displayed to the left of the source window. The current execution point is indicated by an arrow [- >]. Breakpoints are indicated by an [S] at the appropriate lines; trace events are indicated by a [T]. The command window pane The command window provides direct access to the underlying dbx debugger. Output from most debugger commands will appear in this window and any dbx command can be entered using the keyboard from within this window. Other windows Other windows may appear on the screen from time to time as needed. Program output window The program output window appears when you are executing a program from dbXtra and displays the program's output. This is an xterm window and behaves like a terminal. Information window This kind of window displays the output of dbXtra commands that provide information to the user. These windows remain on the screen until dismissed by the user. Display window This window displays the values of selected symbols during program execu- tion. Pull-down menus The menu bar is located across the top edge of the source window. The menus along the bar can be accessed by selecting the name of the menu using the mouse, or by using the keyboard accelerator sequence for the menu (simultaneously pressing the <Alt> key and the underlined, uppercase letter in the menu name). Each menu contains a group of buttons perform- ing related operations. The file menu This menu has commands to save configuration information and exit dbXtra. Write Configuration File This command prompts for a filename, then creates a file containing dbXtra window geometry commands as X configuration commands suit- able for inserting in a .Xdefaults or .Xresources file. See X(X) for more information. Exit dbXtra This command prompts to ensure the user really wants to quit, then exits dbXtra if so indicated. The events menu This menu contains a group of buttons which can be used to generate the various commands associated with breakpoint and trace events. The follow- ing is a brief description of the action performed by each button in the menu. The text between the "[" and the "]" characters following the name of each button is the dbx command constructed when the button is selected. For detailed information about the various dbx commands, see dbxtra(CP). _________________________________________________________________________ NOTE Commands in this menu which cause some action when a variable or address is accessed will have no effect when that access is per- formed by the kernel itself, for example, by a read statement. _________________________________________________________________________ Events [status] This command displays the currently active events (breakpoints, trace expressions, etc.). Call... [call <function-call>] A dialog box appears, prompting the user for a function call. The function will then be invoked with the arguments specified. If the $unsafecall variable is not set, the parameters supplied for the call must match in number and type to the function. When $unsafe- call is set the parameters do not have to match in number or type. If C syntax is used to call C++ member functions, all hidden param- eters must be explicitly specified. When... [when <rest-of-command>] A dialog box appears, prompting the user for text which will be used in place of the <rest-of-command> field. The when command allows the user to execute one or more dbx commands whenever a spe- cific event occurs during the execution of the user's program. For a complete explanation of the when command, see dbxtra(CP). Stop -> This button generates a submenu which provides access to the vari- ous modes of the stop command. if [stop if <conditional-expression>] A dialog box appears, prompting the user for a conditional expres- sion to further qualify the event. Execution of the debugged pro- gram will halt only if the conditional expression evaluates to ``true''. function [stop in <function-name>] A dialog box appears, prompting the user for a function name. The program will halt when the function is invoked. address [stop inst at <address>] A dialog box appears, prompting the user for an absolute memory address in the program space. The program will halt if this address is encountered in the execution stream. line [stop at <line-number>] A dialog box appears, prompting the user for a line number. The program will halt at the line specified. access [stop access <variable>|<address>] A dialog box appears, prompting the user for a variable or absolute memory address. The program will halt if the variable or address has been read from or written to. _________________________________________________________________________ NOTE Using this option requires the use of the debug regis- ters. _________________________________________________________________________ change [stop change <variable>|<address>] A dialog box appears, prompting the user for a variable or memory address name. The program will halt when that variable or address has been written to. _________________________________________________________________________ NOTE This option requires the use of the debug registers. _________________________________________________________________________ stop in main [stop in main] This causes the program to halt before the first line in the func- tion main() is executed. In C++ mode, all static initializers and constructors are executed before main() is called; use stop in main to regain control before static constructors are called. stop [stop <rest-of-command>] A dialog box appears, prompting the user for text which will be used in place of the <rest-of-command> field. This command allows specification of any variations of the stop command. Trace -> This menu generates a submenu which provides access to the various modes of the trace commands. function [trace <function-name>] A dialog box appears, prompting the user for a function name. A message to be displayed when the function is invoked. address [trace inst <address>] A dialog box appears, prompting the user for an absolute address in the program space. A message will be displayed if that address is encountered in the execution stream line [trace <line-number>] A dialog box appears, prompting the user for a line number. A mes- sage will be displayed when that line is executed. access [trace access <variable>|<address>] A dialog box appears, prompting the user for a variable or absolute memory address. A message will be displayed. if the value at that address is read from or written to, _________________________________________________________________________ NOTE This command requires the use of the debug registers. _________________________________________________________________________ change [trace <variable>] A dialog box appears, prompting the user for a variable name. A message is displayed when the variable has been written to. Writes of the same value will not halt the program. _________________________________________________________________________ NOTE This command requires the use of the debug registers. _________________________________________________________________________ trace [trace <rest-of-command>] A dialog box appears, prompting the user for text which will be used in place of the <rest-of-command> field. This command allows specification of any variations of the trace command. Interrupt Sends SIGINT to the program. By default, the executing program is stopped and the source window is updated to display the current execution point. Catch... [catch <signal-name>] A dialog box appears, prompting the user to specify a signal. The signal may be specified by number or name (for example, SIGINT). The catch command adds the signal to the list of signals inter- cepted by the debugger. Upon receipt of the signal, the program is stopped. The user may then elect to send the signal to the program with the continue command. See the description of the continue com- mand in dbxtra(CP). Ignore... [ignore <signal-name>] A dialog box appears, prompting the user to specify a signal. The signal may be specified by number or name (for example, SIGINT). The ignore command deletes this signal from the list of signals intercepted by the debugger. The signal will be processed by the program only. Dbxtra This command allows the user to enter complex commands for direct execution by dbXtra. The output from the debugger will be dis- played in an information window, which can be removed when no longer required. The execute menu This menu is used to control the execution of the user's program. Run... [run <command-line-parameters>] A dialog box appears, prompting the user for the program command line parameters. The program is then run. Program execution will continue to completion unless a breakpoint or other event is encountered. A program output window is created allowing the user to interact with the program. Rerun [rerun] The rerun command restarts the program from its beginning. The previous command line parameters are used. Program execution will continue to completion unless a breakpoint or other event is encountered. Since Rerun does not prompt for parameters, the fastest way to run a program without parameters is to select this command. A program output window is created allowing the user to interact with the program. Continue [cont] The continue command continues execution from the current break- point or event. Skip... [skip <number-of-events>] A dialog box appears, prompting the user for the number of events to skip. Execution continues from the current location until the specified number of events have occurred. Next [next] The Next command executes one source line and then stops. If Next is used when the next line is a function call, dbXtra will cause the function to be executed but will not stop in the function's code. Use Step to follow execution into called functions. Step [step] The Step command executes one source line and then stops. Step will follow the execution into called functions. Goto [goto <selected-line>] goto inserts a temporary breakpoint at the selected source line, then continues execution of the program until it reaches that line. Jump [jump <selected-line>] Jump resumes execution of the program from the selected line. Return [return] Continue executing the program until it returns from the current function and stop in the calling function. The source window dis- plays the line following the current function call. Instruction -> This submenu provides access to single-stepping by machine instruc- tions. The source menu This menu is used to navigate the user's program source code. Browse file... [file <source-file-name>] A dialog box appears, prompting the user for a file name. The specified file is displayed in the source window. Source Path... [use <directory-list>] A dialog box appears, prompting the user for the list of direc- tories used by dbXtra to find source files. Search... A dialog box appears, prompting the user for a regular expression search string. The pattern thus specified is then searched for within the displayed file. The search string defaults to the selected text in the source window. Function... [func <function-name>] A dialog box appears, prompting the user for a function name. The source text around the first executable statement within that func- tion is then displayed. Dbxref... A dialog box appars, prompting the user for arguments to pass to dbxref. A cross-reference table is generated which is required for use of xref, whatis, and where. See dbxtra(CP) for more informa- tion on these commands. Up [up] The source window is changed to display the function that called the current function. This function now becomes the current func- tion and variable scoping rules will default to this function. Down [down] The source window is changed to display the function that was called by the current function. This function now becomes the current function and variable scoping rules will default to this function. The info menu This menu is used to obtain information about the user's program. Show... [whatis <variable>; print <variable>] This command is used to show the type and value of a program vari- able or expression. If a variable or expression is selected in the source window, information about it is displayed; otherwise, a dia- log box appears prompting the user for a variable or expression. The actual variable shown is determined by the scope rules of dbx. Explicit qualification can be used to avoid the default scoping rules. The optional keywords "enum", "union", or "struct" can be used to obtain information about aggregates. A function can be indicated with the "()" characters appended to its name. Where [where] The where command displays the functions called by the user's pro- gram. The up and down commands can be used to change the current function to another one in the call stack. Display... [display <expr>] The display command is used to add a variable or expression to the display window. If a variable or expression is selected in the source window, it is added to the display window; otherwise, a dia- log box appears prompting the user for a variable or expression. Information is updated and displayed whenever the debugger gains control. The display window is created if it does not exist. Items can be deleted by clicking on the item in the display window. Assign... [assign <stmt>] A dialog box appears, prompting the user for an assignment state- ment, which is then executed. Which... [which <name>] The which command is used to obtain a fully qualified name. The identifier is displayed in a fully qualified form with the names of the outer scopes prepended to the name. If a name is selected in the source window, information for that name is displayed; other- wise, a dialog box appears prompting the user for a name. Print... [print <expr>] The print command is used to display the value of an expression. If an expression is selected, its value is displayed; otherwise, a dialog box appears prompting the user for an expression. Xref... The xref command is used to print cross-reference information for a specified variable, function, or macro. Variables [dump] This command displays the names and values of variables local to the current function. Registers [printregs] This command displays the contents of the general and floating point registers of the processor. Memory [<address>/X] This command displays the contents of program memory. The options menu This menu is used to set dbXtra options and the environment variables of the program being debugged. C/C++ The "C/C++" command allows the user to switch between the C++ source code and the C code that is a result of the compilation pro- cess. This is useful for programmers interested in the C language equivalent of a C++ construct. The C++ program must be compiled with the -dbxC flag. Preferences -> This submenu contains a number of dbx switches which can be toggled to suit user preferences. See the section on the set command in dbxtra(CP) for detailed information about these switches. Environment -> This submenu contains buttons to set and unset environment vari- ables accessible by the program being debugged. The help menu This menu contains various buttons which provide on-line help information about the debugger. The sidebar command buttons Some frequently-used commands can be accessed via the ``sidebar command buttons'' on the left hand side of the main window. All these commands are available in the menus and have been described earlier. The commands are Run..., Rerun, Stop, Continue, Next, Step, Interrupt, Goto, Jump, and Return. The Stop command in this menu is the same as the line command under Stop-> in the events menu. The pop up menu Associated with the source window is a "pop up" menu. This appears when the right mouse button is pushed. A command may be selected with the right mouse button. All commands in the pop up menu appear in another menu, and have been described earlier. Here is the list of commands: Show..., Display..., Assign..., Which, Xref, Up, and Down. The Assign... command in this menu allows a statement to be selected or entered in a dialog box. Configurable resources As with most X applications, you can configure a number of resources to modify the appearance of dbXtra to suit your needs. A number of the resources, for example to modify the font utilized, or the colors used, are described elsewhere. (See OSF/Motif Style Guide and OSF/Motif User's Guide, for example.) The values of the resources may be specified in the .Xdefaults file in your home directory, or in a file called dbXtra in /usr/lib/X11/app-defaults, or in the app-defaults directory in your home directory. The resources that control the appearance of dbXtra have the following format: dbXtra*resource:value The following describes the various dbXtra resources that can be used: configFile The value for this resource is a string denoting the full pathname of the file containing the definitions for the various buttons and menus appearing in the source window. The default value for this is "/usr/lib/dbxtra/dbXtra.config". lineNumberDigits The value for this resource is an integer number which specifies the amount of space (in terms of digits) to be allocated for displaying line numbers in the source window. The default value for this resource is 4. A value of 0 will suppress the appearance of line num- bers. controlButtonWidth The value for this resource is an integer number which specifies the amount of space (in terms of characters) to be used as the size of each button defined in the configuration file. This value also defines the number of characters that appear in the name of the but- ton. If this value is not defined, it will be calculated to be the number of characters in the longest button-name in the configuration file. controlPanel The value for this resource controls the appearance of the control window. A value of "wide" means that the control window appears as a paned window underneath the source window. A value of "narrow" means that the control window appears as a paned window underneath the source window, and that the button column extends to the bottom of the control window. The value of "separate" means that the control window will be completely separate from the source window. The default value for this resource is "wide". font The value of this resource defines the font to be used to display characters. By default, this resource is not defined and therefore the default font used by the X session will be used. control.font The value of this resource defines the font to be used to display characters in the control window only. By default, this resource is not defined and therefore the default font used by the X session will be used. display.font The value of this resource defines the font to be used to display characters in the display window only. By default, this resource is not defined and therefore the default font used by the X session will be used. output.font The value of this resource defines the font to be used to display characters in the output window only. By default, this resource is not defined and therefore the default font used by the X session will be used. control.wrap The value of this resource is used to determine whether or not line wraparound is to be performed in the control window. If the value is "true", line wraparound will be performed. If the value is "false", wraparound will not take place and if any line exceeds the width of the window, a horizontal scroll bar will appear to allow access to the parts of the line which cannot fit within the available space. help.wrap The value of this resource is used to determine whether or not line wraparound is to be performed in the help window. If the value is "true", line wraparound will be performed. If the value is "false", wraparound will not take place and if any line exceeds the width of the window, a horizontal scroll bar will appear to allow access to the parts of the line which cannot fit within the available space. information.wrap The value of this resource is used to determine whether or not line wraparound is to be performed in the information windows. If the value is "true", line wraparound will be performed. If the value is "false", wraparound will not take place and if any line exceeds the width of the window, a horizontal scroll bar will appear to allow access to the parts of the line which cannot fit within the available space. In addition to the above, various resources can be set to manipulate the various Motif widgets utilized. See OSF/Motif User's Guide for more details. C++ debugging features This version of the debugger supports C++ in a straightforward fashion; dbXtra is given knowledge of both C++ and C names and source files. At any time, the user may input either the C or C++ names for a function, structure member or variable; the cc command only affects the output from dbXtra to the user. Classes in C++ become structures in C, reference variables (for example, int&) become pointers, and simple symbolic constants (const) become variables in the proper scope. Overloaded functions are prompted for. Enum types become ints, and enum constants become literal constants with no hint as to where they came from. Overloaded operator function names are of the form operator+ (no blanks), where ``+'' is replaced by the overloaded operator. Overloaded new and delete operators are specified as new and delete, not operatornew and operatordelete. To examine the translated C source along with the original C++ source, the source file must have been compiled with CC -dbxC; compiling with -dbx alone does not provide access to the C source. Files a.out object file tags tags file source files Comments Since symbolic debugging information is replicated (both in the COFF file and in dbXtra) for each instance of a header file, storage is quickly taken up by replicated information when several source files #include the same header. In the case of C++ debugging, judicious use of the -F flag may save significant amounts of memory when starting up dbXtra. Executable code within header files is not properly traced by dbXtra. See also cc(CP), dbxtra(CP), ctags(CP), X(X)