Using the graphical interface of debug

Properties menu

The Properties menu in the debugger's default configuration lets you change some of the properties associated with the different panes of the debugger. Clicking MENU on the Properties button brings up a menu with different options, depending on which panes are present in the window. The following options appear in the Properties menu of one or more windows in the default configuration (remember that you can configure the Properties menu to have different options, or can move these options to different menus):

Several of the options in the Properties menu may also be set as X window resources either in an X window resource file (such as .Xdefaults) or on the debugger's command line. See ``Resource settings'' under ``Customization'', and ``Invoking the debugger''.


The Animation popup window lets you control the time between steps while the process or thread is animated. A process or thread is animated by selecting the ``Animate Source'' or ``Animate Disassembly'' options. When the process or thread is animated, the debugger continuously steps the process or thread, highlighting each statement as it is executed. If the stepping takes place too fast to be followed easily, you can slow it down by specifying a delay between steps.

The popup window displays a slider with a range from no delay to a delay of one second. Positioning the slider between the two ends will introduce a delay of a fraction of a second. The default delay is half a second.

Note that it takes some time for the debugger to step the process or thread and update the display. Depending on the characteristics of your system, this stepping time may be noticeable even with no delay set. The delay specifies only a minimum time between steps. If the stepping time is greater than specified delay, the debugger does not add on any additional delay time.

In the debugger's default configuration, the Animation option is available in the ``Properties menu'' of the Disassembly and Source windows.

Button Configuration

The Button Configuration option lets you change the appearance of the Button Bars in any window. The changes take effect as soon as you select the OK or Apply button in the window. They affect the same window in every window set (all Source windows, for example).

When the Button Configuration window comes up, it displays a scrolling list with a description of every button that is available for use in the button bar. The list of buttons is searchable. See ``Searching in lists''. Buttons that are already part of the current button bar have a check mark next to their description. The name and, possibly, the mnemonic and command fields for the button will be filled in.

You may choose to display the information for either the top or bottom button bars in any window. If there is more than one panel on the selected button bar, the information for the panel currently displayed will be used. You may also create a new button bar for the top or bottom by selecting the Create new button bar toggle.

To add an item to a button bar, select a button description and select the Add button option. A window will popup allowing you to specify a name and (optional) mnemonic for the button. For the ``Exec command'' and ``Debug command'' buttons, you will also be expected to enter a command string. When you are finished, select OK on the popup window. The button list will be updated with the new information.

To change the name, mnemonic or command fields for an existing button, select the button and select the Change button option. The same popup window will come up, already initialized with the current button values. Edit the values as desired and select OK.

To delete a button from a button bar, select the button and then select the Delete button option. To delete the button bar entirely, select the Delete all option.

To save the changes you have made for future invocations of the debugger, select the Save configuration toggle. Use the ``Configuration directory'' line to enter the pathname of a directory under which debug should save the new configuration. If you have invoked the debugger using your own configuration directory, the ``Configuration directory'' line will be initialized with that pathname.

In the debugger's default configuration, the Button Configuration option is available in the ``Properties menu'' of every window.

Disassembly Mode

The Disassembly Mode popup window lets you choose the mode of display for disassembled machine instructions in the ``Disassembly pane''. The choices are:

Disassembly only is the default, but this may be changed via a command line option or X resource (see ``Customization'' and ``Invoking the debugger'').

In the debugger's default configuration, the Disassembly Mode option is available in the ``Properties menu'' of the Disassembly and Source windows.

Frame Direction

The Frame Direction popup allows you to choose the way the stack pane numbers stack frames. By default, the most recent stack frame is numbered 0 and frames are numbered in increasing order until the initial frame, which has the highest number. Alternatively, you can choose that the most recent frame has the highest number. Subsequent frames will be numbered in decreasing order, down to 0 for the initial frame.

Take note when choosing that the most recent frame has the highest number. In this mode, the debugger must determine the highest numbered frame before displaying any stack frames. This can cause the stack display to fail for lack of memory without producing any output for processes that have huge stacks.

In the debugger's default configuration, the Frame Direction option is available in the ``Properties menu'' of the Source window.


The Granularity popup window lets you specify the debugger's behavior with respect to programs, processes, and threads.

A window set has both a current process or thread and a current program (the current program is always the parent program of the current process or thread). Which you are operating on at any point depends on which option, Thread Only, Parent Process or Parent Program, is selected. By default, most commands ( ``Step'', ``Show Value'', etc.) apply to the thread or to the process if the process does not have any threads, but commands that create events apply to the program. By setting events in the program instead of the process or thread, if you have to recreate the program, or if the process forks, the new process will inherit all the events that were defined in the old process. If you set an event in the process only, then all threads created by that process will inherit the event, but if the process forks, the new process will not inherit the event, and the event will disappear when the process dies. If you set an event in a specific thread, the event will not be set in any other process or thread, and the event will disappear when that thread exits. You may set the granularity of event commands separately from the granularity of the other commands. The granularity setting for non-event commands also applies to selections in the ``Process pane''.

The commands that create events are ``Stop'', ``Stop on Function'', ``Set Watchpoint'', ``Set Breakpoint'', ``Signal'', ``Syscall'', ``Exception'', and ``On Stop''.

The granularity selected affects only the parent window set.

In the debugger's default configuration, the Granularity option is available in the ``Properties menu'' of the Event, Process and Source windows.


The Language popup window lets you override the default language for expression evaluation. The default language is displayed in the line titled ``Current Source Language''. The debugger uses information in the object file being debugged to determine the default language. If the object file does not provide that information, the current source language will default to C.

When you choose None for the overriding language, the current source language is used for expression evaluation. When you choose C or C++ for the overriding language, the language chosen will become the current language.

The current language affects the evaluation of expressions in the ``Set value'', ``Show Value'', ``Show Type'', ``Stop'', and ``Dump'' popup windows, as well as commands entered in the ``Command pane''. For details on how they are affected, see the section on the specific language: ``Support for the C language'' or ``Support for the C++ language''.

The language is a global property, and affects all window sets.

In the debugger's default configuration, the Language option is available in the ``Properties menu'' of the Command, Source and Symbols windows.

Support for the C language

When the current language is C, debug will support evaluation of all legal ANSI C expressions, except those involving macro expansion.

The debugger evaluates C expressions using ANSI C semantics rather than the pre-ANSI C (or transition mode) semantics. The main effect is on type promotions involving unsigned types, where ANSI C semantics are value preserving rather than unsigned preserving. The debugger's behavior may differ from the behavior of programs compiled with cc -Xt (for transition mode).

Support for the C++ language

The debugger will recognize when an object file was compiled with the C++ Compilation System (Release 2.0 or 3.0) or the C++ translator, cfront (Release 2.1 or 3.0), and will set the current language (displayed in the ``Language'' popup window) to C++. Names appear as in the C++ source, not as they appear in the object file.

When the current language is C++, debug accepts a subset of C++ expressions, including:

Expressions may be entered in the ``Set value'', ``Show Value'', ``Show Type'', ``Stop'', and ``Dump'' popup windows, as well as in the ``Command pane''.

If given a pointer to a base class object with virtual functions, and if the debugger can determine that the type of the object pointed to is a class derived from the base class, the ``Show Type'' window will display both the base class and the derived class. The ``Show Value'' window will also display the object in terms of the derived type.

When printing the contents of a structure, ``Show Value'' will display static class members, with the notation that they are static. Note that the ``Symbol pane'' does not display static members.

The ``Show Value'' window also has a verbose option that displays additional information such as the function prototypes of all functions called by the debugger while evaluating an expression. This is useful to see how overloaded functions are resolved. The verbose output also includes compiler-generated structure and class members such as pointers to virtual function tables.

Using the ``Stop'' or ``Stop on Function'' popup windows, breakpoints may be set on:

A stop event may also be created on a specific object and member function combination, using the syntax pointer->function or object.function. The debugger will stop the process or thread upon entering the function only if the "this" pointer matches the specified object. If the function is a virtual function, debug will set the breakpoint on the appropriate overriding function. Examples of expressions that may be entered in the ``Stop'' window include:

   C::operator int()
   ptr->f(char *)
An exception event may also be created to take action when an exception of a specific type is thrown or caught. See the ``Exception'' and ``Ignore Exceptions'' popup windows for details. While an exception is in effect, the debugger variable %eh_object represents the thrown object. ``Show Type'' and ``Show Value'' may be used to examine the type and value of %eh_object.

If an exception is thrown while an expression is being evaluated, the debugger will abort the expression evaluation. Any side effects of the expression, such as objects created on the stack, will be left in an indeterminate state.

Output Action

The Output Action popup window lets you specify the actions the debugger is to take when an event occurs, or when a thread changes state, or when a controlled process or thread generates output. The window contains three sets of buttons, one for process and user events, one for thread state changes, and the other for process I/O.

The choices for events and process I/O are:

By default, the debugger beeps when an event occurs, because the event notification is also displayed at the bottom of the main windows.

When a process whose output is captured (see ``Create'') generates output, the default action is Open and Raise (the debugger raises the ``Command pane'' to show you the output). Note that this does not apply to processes whose output is not captured; the debugger cannot tell when those processes generate output.

A thread can change states during its lifetime. For example, a multiplexed thread can be scheduled off an LWP and can later be picked up by another LWP, or it can be suspended by another thread and later continued by yet another.

The choices for thread state change actions are:

These actions, unlike the ones for events and process I/O, are cumulative. That is, you can select both Beep and Stop. By default, both are selected, and the following actions are taken in the various scenarios:

In the debugger's default configuration, the Output Action option is available in the ``Properties menu'' of the Command, Disassembly and Source windows.

Source Path

The Source Path popup window lets you set the path the debugger uses to find source files.

You may enter multiple directories, one directory per line. You may also edit a previously existing set of directories. The directories will be searched in the order they appear.

If you choose the option Program-specific Path, the path will be used for the selected program only. If you choose the Global Path option, the debugger will search that list of directories for any program if it cannot first find the file in the program-specific path.

If you popped up the Source Path window from a window containing a ``Process pane'', the selected programs (if any) in the Process pane are affected by the Program-specific Path. Otherwise, the current program is affected.

In the debugger's default configuration, the Source Path option is available in the ``Properties menu'' of the Command and Source windows.


The Symbols popup window lets you choose what kinds of symbols are displayed in the ``Symbol pane''. The choices are:

Display the global symbols defined in the current object (executable file or shared library).

Display the file static symbols that are defined in the current file.

Display the local variables defined in the current function.

Display the debugger's built-in variables.

Display the debugger-maintained user variables.

You may choose any combination of these categories. By default, local symbols are displayed.

The selections affect only the parent window set.

The Symbols option may only be configured in windows that contain a ``Symbol pane''. In the debugger's default configuration, the Symbols option is available in the ``Properties menu'' of the Symbols window.

Next topic: Help menu
Previous topic: Syscall

© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 27 April 2004