NAME

       xxgdb - X window system interface to the gdb debugger.

SYNOPSIS

       xxgdb [ -toolkitoption ... ] [-xxgdboption ... ] [-gdboption ... ] [objfile [ corefile ]]

DESCRIPTION

       Xxgdb  is  a  graphical user interface to the gdb 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.

       Xxgdb allows initial gdb commands stored in the file  .gdbinit  to  be  executed  immediately  after  the
       symbolic  information  is  read.   If  .gdbinit  does not exist in the current directory, the user's home
       directory is searched ( /.gdbinit). Option -nx can be used to prevent xxgdb  from  executing  this  file.
       Option -i can be used to change the file name of command file.

       Objfile  is  an  object file produced by a compiler with the appropriate option (-g) specified to produce
       symbol table information for gdb.

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

       The  name  of  the  debugger  invoked  by  xxgdb  is,  by default, gdb, but it can be overridden with the
       environment variable XXGDB_DEBUGGER or with the db_name option.

OPTIONS

       Xxgdb accepts all of the standard X Toolkit command line options (see X(1)), and all the gdb options (see
       gdb(1)), plus the following xxgdb specific options:

       -db_name debuggername
              Specify  the  name  of the debugger to override the default "gdb".  WARNING : by default prompt is
              the name of the debugger enclosed in parenthesis followed by a space. So if the  prompt  is  still
              "(gdb) ", you HAVE TO use -db_prompt "gdb"

       -db_prompt promptstring
              Specify  to  xxgdb what is the debugger prompt. The default is to expect the prompt to be the name
              of the debugger enclosed in parenthesis followed by a space (eg, "(gdb) ").

       -i filename
              Specify the filename of initial gdb command file. The default is ".gdbinit".

       -nx    Do not execute .gdbinit file (or file specified with -i)

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

SUBWINDOWS

       Xxgdb 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 xxgdb .

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

       Dialogue Window     Provide a typing interface to gdb.

       Display Window      Provide a window for displaying variables each time execution stops.

       Popup Windows       Provide windows for displaying variables (see "Displaying C Data Structures" below).

       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.

IOWIN and NOIOWIN COMMAND

       If  compiled, with the right option, xxgdb can use a separate io window to talk to gdb, so program output
       is not confused with gdb output.  Type command 'iowin' in Dialogue Window to create io window. If you get
       'Undefined  command'  error message, then xxgdb was not compiled for that feature. The program xxgdbiowin
       is used for this io window.

       If xxgdb was compiled with iowin support, typing 'noiowin'  will  close  the  io  window  and  reset  the
       controlling terminal of the debugger.

COMMAND BUTTONS

   Execution Commands
       run         Begin program execution.

       cont        Continue execution from where it stopped.

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

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

       finish      Continue execution until the selected procedure returns; the current  procedure  is  used  if
                   none is selected.

   Breakpoint Commands
       break     Stop  program  execution  at  the line or in the function selected.  To set a breakpoint in the
                 program, place the caret at the start of the source line or on the function name and click  the
                 break button.  A stop sign will appear next to the source line.

       tbreak    Set  a  breakpoint  enabled only for one stop.  This is the same as the break button except the
                 breakpoint is automatically disabled the first time it hit.

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

       show brkpts
                 Show the current breakpoints (both active and inactive).

   Stack Commands
       stack     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. (also see "Displaying C Data Structures" below)

       print *   Print the value of the object the selected expression is pointing to.  (also see "Displaying  C
                 Data Structures" below)

       display   Display the value of a selected expression in the display window, updating its value every time
                 execution stops.

       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.

       args      Print the arguments of the selected frame.

       show display
                 Show the names of currently displayed expressions.

       locals    Print the local variables of the selected frame.

       stack     Print a backtrace of the entire stack.

   Miscellaneous Commands
       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.

       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, to select an executable file to debug, or to select a core
              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.

       yes    Send 'y' (yes) to gdb. To be used when gdb requires a yes/no response.

       no     Send 'n' (no) to gdb. To be used when gdb requires a yes/no response.

       quit   Exit xxgdb.

       I/O Win
              Create io window.

       No I/O Win
              Delete io window.

   Displaying C Data Structures
       Xxgdb 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 xxgdb, 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 xxgdb 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)
              step (Command)
              finish (Command)
              break (Command)
              tbreak (Command)
              delete (Command)
              up (Command)
              down (Command)
              print (Command)
              print * (Command)
              display (Command)
              undisplay (Command)
              args (Command)
              locals (Command)
              stack (Command)
              search (Command)
              file (Command)
              show display (Command)
              show brkpts (Command)
              yes (Command)
              no (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, xxgdb 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. (" !%^&*()+=~|;:{},/#<?\"\n\t")

       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)

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

       db_name
              The name of the debugger program. ("gdb")

       db_prompt
              The prompt string of the debugger program. ("(gdb) ")

       gdbinit
              The filename of initial command file. (".gdbinit")

       nx     If True, xxgdb will not execute .gdbinit at start-up. (False)

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

FILES

       a.out          default object file
       core           default core file
       ~/XDbx         resources file (or /usr/lib/X11/app-defaults/XDbx)
       .gdbinit       local initial commands file
       ~/.gdbinit     user's initial commands file

SEE ALSO

       X(1), gdb(1)

COPYRIGHT

       Copyright 1989 The University of Texas at Austin.
       Copyright 1990 Microelectronics and Computer Technology Corporation.
       Copyright 1990-1994 Thomson Consumer Electronics, Inc.

AUTHOR

       Po Cheung.
       Pierre Willard.