XDBX(1)

NAME
xdbx - X window system interface to the dbx debugger.

SYNOPSIS
xdbx [ -toolkitoption ... ] [-xdbxoption ... ] [-dbxoption ... ] [objfile [ corefile ]]

DESCRIPTION
Xdbx is a graphical user interface to the dbx debugger under the X Window System. It provides visual feedback and mouse input for the user to control program execution through breakpoints, to examine and traverse the function call stack, to display values of variables and data structures, and to browse source files and functions.

Xdbx allows initial dbx commands stored in the file .dbxinit to be executed immediately after the symbolic information is read. If .dbxinit does not exist in the current directory, the user's home directory is searched (~/.dbxinit).

Objfile is an object file produced by a compiler with the appropriate option (-g) specified to produce symbol table information for dbx. For Sun dbx, if no objfile is specified, the debug command can be used later to specify the program to be debugged.

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

The name of the debugger invoked by xdbx is, by default, dbx, but it can be overridden with the environment variable DEBUGGER.

OPTIONS
Xdbx accepts all of the standard X Toolkit command line options (see X(1)), and all the dbx options (see dbx(1)), plus the following xdbx specific options:

-bigicon
    Uses a 64x64 icon instead of the default 48x48 icon.

SUBWINDOWS
Xdbx consists of the following subwindows:

File Window
    Display the full pathname of the file displayed in the source window, and the line number of the caret.

Source Window
    Display the contents of a source file.

Message Window
    Display the execution status and error messages of xdbx .

Command Window
    Provide a list of the common dbx commands which are invoked by simply clicking the LEFT mouse button.

Dialogue Window
    Provide a typing interface to dbx.

Display Window
    Provide a window for displaying variables each time execution stops. (Sun dbx only)

The relative sizes of the source window, command window, and the dialogue window can be adjusted by dragging the grip (a small square near the right edge of a horizontal border) with the LEFT mouse button down.

SELECTION
Text selection in the source window is modified to make it easier to select C expressions. LEFT mouse button down selects a C expression by highlighting it in reverse-video. LEFT mouse button down also positions the caret and updates the line label accordingly.

C expression selection is based on the resource delimiters which determines the set of characters that delimits a C expression. (The default word selection behavior in the Athena text widget selects a word delimited by white spaces.) Text selection adjustment is possible by holding the LEFT mouse button down and dragging.

A LEFT mouse button click with the SHIFT button down prints the value of the expression selected.

SCROLLBAR
Pressing the LEFT mouse button scrolls the text forward, whereas pressing the RIGHT mouse button scrolls the text backward. The amount of scrolling depends on the distance of the pointer button away from the top of the scrollbar. If the button is pressed at the top of the scrollbar, only one line of text is scrolled. If the button is pressed at the bottom of the scrollbar, one screenful of text is scrolled.

Pressing the MIDDLE mouse button changes the thumb position of the scrollbar. Dragging the MIDDLE mouse button down moves the thumb along and changes the text displayed.

COMMAND BUTTONS

  Execution Commands

run Begin program execution.

cont
    Continue execution from where it stopped.

step
    Execute one source line, stepping into a function if the source line contains a function call.

next
    Execute one source line, without stepping into any function call.

return
    (Berkeley dbx only) Continue execution until the selected procedure returns; the current procedure is used if none is selected.

  Breakpoint Commands

stop at
    Stop program execution at the line selected. To set a breakpoint in the program, place the caret on the source line and click the stop at button. A stop sign will appear next to the source line.

stop in
    Stop program execution in the function selected. To set a breakpoint in a function, select the function name and click the stop in button. A stop sign will be placed near the first executable line of the function.

delete
    Remove the breakpoint on the source line selected or the breakpoint number selected.

status
    Show the current breakpoints and traces.

  Stack Commands

where
    Show a stack trace of the functions called.

up  Move up one level on the call stack.

down
    Move down one level on the call stack.

  Data Display Commands

print
    Print the value of a selected expression.

print *
    Print the value of the object the selected expression is pointing to.

display
    Display the value of a selected expression in the display window, updating its value every time execution stops. (Sun dbx only)

undisplay
    Stop displaying the value of the selected expression in the display window. If the selected expression is a constant, it refers to the display number associated with an expression in the display window. (Sun dbx only)

dump
    Print the names and values of local variables and parameters in the current or selected function.

  Miscellaneous Commands

func
    Display a selected function on the source window, and change the scope for variable name resolution to the selected function. The file scope is changed to the file containing the function.

file
    Pop up a directory browser that allows the user to move up and down in the directory tree, to select a text file to be displayed, or (in Sun dbx) to select an executable file to debug. Directory entries are marked with a trailing slash (`/') and executables with a trailing asterisk (`*'). Filenames beginning with a dot (`.') or ending with a tilde (`~') are not listed in the menu.

search
    Pop up a search panel which allows both forward (>>) and reverse (<<) search of text strings in the source file. Hitting carriage return after entering the search string will begin a forward search and pop down the search panel.

quit
    Exit xdbx.

  Displaying C Data Structures (Sun dbx only)
Xdbx provides some primitive support for graphically displaying C structures and the ability of following pointers. Pressing the RIGHT mouse button on the print (or print *) command button displays the value of the selected expression (or the value the selected expression is pointing to) in a popup. If the value is a pointer or a structure containing pointers, the user can examine the value of the object that pointer is pointing to by clicking the pointer value. This will create another popup that displays the object the pointer points to. Clicking the label of the popup pops down itself and all of its descendants.

X DEFAULTS
To change the default values of widget resources used in xdbx, you need to reference the widgets by name or by class. The widget hierarchies for the main window, the file menu, the search dialog box, and the popup data display used in xdbx are shown as follows, with the name of the widget followed by the name of its class in parentheses:
Main window:
    toplevel (ToplevelShell)
      vpane (Paned)
	fileWindow (Form)
	  fileLabel (Label)
	  lineLabel (Label)
	sourceForm (Form)
	  sourceWindow (AsciiText)
	messageWindow (Label)
	commandWindow (Box)
	  run (Command)
	  cont (Command)
	  next (Command)
	  return (Command)
	  step (Command)
	  stop at (Command)
	  stop in (Command)
	  delete (Command)
	  where (Command)
	  up (Command)
	  down (Command)
	  print (Command)
	  print * (Command)
	  func (Command)
	  file (Command)
	  status (Command)
	  display (Command)
	  undisplay (Command)
	  dump (Command)
	  search (Command)
	  quit (Command)
	dialogWindow (AsciiText)
	displayWindow (AsciiText)

File menu:
    File Directory (TransientShell)
      popup (Paned)
	fileMenuLabel (Label)
	fileMenu (List)
	cancelButton (Command)
Search dialog box:
    Search (TransientShell)
      searchPopup (Dialog)
	<< (Command)
	>> (Command)
	DONE (Command)
Data display popup:
    Data Popup (TransientShell)
      popup (Form)
	label (Label)
	dataDpyWindow (AsciiText)

In addition to the standard X resources, xdbx uses the following application-specific resources for user customization. The value in parentheses is the default value.

bell
    If True, the bell is on. (True)

displayWindow
    If True, the display window appears on start up. (False)

delimiters
    The set of delimiters for word selection. (" !%^&*()+=~|;:{},/#<?

prompt
    The prompt string used in xdbx. ("(xdbx) ")

stop_color
    Color of the stop sign. (Red)

arrow_color
    Color of the arrow sign. (Blue)

updown_color
    Color of the updown sign. (Blue)

bomb_color
    Color of the bomb sign. (Red)

dataDpyMaxHeight
    Maximum height of the data display window. (300)

dataDpyMaxWidth
    Maximum width of the data display window. (600)

tabstop
    When displaying source code, the width (in spaces) of a tab. (8)

FILES
a.out 		default object file
core 		default core file
.dbxinit 		local initial commands file
~/.dbxinit 	user's initial commands file

SEE ALSO
X(1), dbx(1)

LIMITATIONS
Xdbx does not handle all the dbx commands properly. Only a subset of the commands is supported:
        run     stop at	   where   print   list   display     return
        cont    stop in	   up      dump    /      undisplay
        next    delete     down    func    ?
        step    status     use     file    quit

BUGS
Sparc dbx does not always return correct source line position after an up or down command. Also, the file variable in sparc dbx sometimes has an extra slash, as in /file.c, which could break what normally works. One way of getting around the latter is to specify the current directory before the program name, as in 'xdbx ./a.out' or 'debug ./a.out'.

COPYRIGHT
Copyright 1989 The University of Texas at Austin Copyright 1990 Microelectronics and Computer Technology Corporation

AUTHOR
Po Cheung