test

Using Sun WorkShop

Basic Debugging Steps

The following sections describe the basic steps to perform after you start debugging a program. For more detailed information on any of the steps, see Debugging a Program With dbx.

Changing Run Parameters

You can change run parameters such as arguments, the run directory, and environment variables during a debugging session.

Specifying Program Arguments

You can specify program arguments when you load your program for debugging, and edit them at any time once your program is loaded.

When you enter arguments in the text box that contain characters that have special meaning to the shell, make sure you set them off with either a backslash (\) or quotes (" "). The special characters are | & ; < > ( ) $ ` \ " ' * ? [ ] Space Tab Newline.

To specify program arguments when loading a program, type the arguments in the Arguments text box of the Debug New Program dialog box as if you were typing them on the command line. Do not include the program name.

To edit program arguments once a program is loaded:

  1. Choose Debug > Edit Run Parameters to open the Edit Run Parameters dialog box.

  2. Add or change arguments in the Arguments text box.

  3. Click OK.

Specifying a Run Directory

You can specify a run directory when loading your program for debugging and change the run directory at any time once a program is loaded. When your program is loaded, the directory you selected as the run directory is made the current working directory of the debugger.

To specify a run directory when loading a program:

  1. Type the directory name in the Run Directory text box or click the browse button to display the Run Directory dialog box, in which you can select the directory name.

  2. Click OK.

To change the run directory once a program is loaded:

  1. Choose Debug > Edit Run Parameters to open the Edit Run Parameters dialog box.

  2. Type the directory name in the Run Directory text box or click the browse button to display the Run Directory dialog box, in which you can select the directory name.

  3. Click OK.

Setting Environment Variables

You can specify the environment variables that are in effect when the program runs. When you run the program, setenv commands for these environment variables are prepended to the run command.

Using the Environment Variables dialog box, you can add or delete environment variables to the Persistent Environment Variables list. All environment variables in the Persistent Environment Variables list are saved with your WorkSet.

Note -

The Persistent Environment Variables list for running your program is not the same as the Persistent Environment Variables list for building your program described in "Using Environment Variables".

To open the Environment Variables dialog box:

Adding An Environment Variable

To add an environment variable to the Persistent Environment Variables list:

  1. Type the name of an environment variable in the Name text box.

  2. Type a value for the variable in the Value text box.

    If you make a mistake, click Clear to remove entries in the Name and Value text boxes.

  3. Click Add to add the environment variable to the Persistent Environment Variables list.

  4. Repeat the previous three steps to add other environment variables.

  5. Click OK to close the dialog box.

    Note -

    Pressing the Return key after each step move the input focus to the next step.

Deleting an Environment Variable

To delete a variable from the Persistent Environment Variables list:

  1. Select a variable from the list.

  2. Click Delete (Delete All removes all environment variables in the list).

  3. Click OK to establish the change and close the dialog box.

Changing the Value of an Environment Variable

To change the value of an environment variable in the Persistent Environment Variables list:

  1. Select an environment variable in the list.

  2. Type a new value in the Value text box and click Change.

  3. Click OK to establish the change and close the dialog box.

Reviewing and Overriding Environment Variables

An environment variable definition that appears in the Persistent Environment Variables list overrides any environment variable with the same name that appears in the current debugging environment.

To review the current debugging environment variable definitions, click More to open the Current Environment list, which includes all the environment variables in the debugging environment for your program. You can filter the list using the Filter text box.

To override the value of an environment variable:

  1. Select an environment variable in the Current Environment list.

  2. Click <<Add to add the environment variable to the Persistent Environment Variables list.

  3. Type a new value in the Value text box and click Change.

  4. Click OK to establish the change and close the dialog box.

    The environment variable definition in the Persistent Environment Variables list overrides the environment variable definition in the current debugging environment, and is saved with your WorkSet.

Note -

To delete a variable and unset its value, you can use the dbx command unset variable.

Stepping Through Your Code

You can view your code by stepping--that is, moving through your code one line at a time. As you step, a green highlighted line known as the program counter marks your place in the program. With each step, the program counter moves to the source line which is next to be executed, always showing you the next line to be executed.

There are three ways to step:

Step Into 

Proceed forward one source line; if the source line is a function call, the debugger stops before the first statement of the function. 

Step Over 

Proceed forward one source line; if the source line is a function call, the debugger executes the entire function without stepping through the individual function instructions. 

Step Out 

Finish execution of the present function and stop on the source line immediately following the call to that function. 

Note -

Sometimes after the current function finishes executing, the highlight returns to the line of the call. In such cases, some extra post-call instructions remain to be executed. Stepping into or over again does not call the function again.

To view your code by stepping:

  1. Wait until your program stops, or interrupt execution by choosing Execute > Interrupt, clicking the Interrupt button, or pressing Ctrl+Break.

  2. In the editor window, step through your code one line at a time, moving through functions, around functions, or out of functions:

    • To step forward in your program one source line, choose Execute > Step Into or click the Step Into button (see Figure 5-1 or Figure 5-2) or press F8.

    • To step forward one source line in the current function, choose Execute > Step Over or click the Step Over button or press F7.

    • To finish executing the current function and stop execution on the source line immediately following the call to the function, choose Execute > Step Out or click the Step Out button.

  3. Continue executing your program by clicking on Go or choosing Execute > Go.

Setting Breakpoints

Set breakpoints to force the debugger to stop execution. You can set simple breakpoints to stop at a line of code, or in a procedure or function.

Set advanced breakpoints to break in C++ classes, track changes in data, break on a condition, break on special events, or create your own custom breakpoints.

You can set and clear breakpoints in the editor window (see Figure 5-2) or the Breakpoints window (see Figure 5-4). In the editor window, you can set or clear a breakpoint at a line of code or in a function. In the Breakpoints window, you can set more complex breakpoints, such as a breakpoint when a signal occurs.

Setting Breakpoints in the Editor Window

To set a location breakpoint:

  1. Click the line where you want the breakpoint.

  2. Click the Stop At button.

    The line is highlighted in red to indicate the breakpoint is set. If the line selected is not an executable line of source code, the debugger sets the breakpoint at the next line after the specified line that is executable.

To set a function breakpoint:

  1. Select the name of the function where you want the breakpoint.

  2. Click the Stop In button.

    A message in the message area tells you that the breakpoint is set.

To remove a breakpoint, do the following:

  1. Move the pointer to the line containing the breakpoint you want to remove.

  2. Click the Clear At button to remove all breakpoints on the line.

Setting Breakpoints in the Breakpoints Window

To open the Breakpoints window, shown in Figure 5-4, choose Windows > Breakpoints or Execute > Set Breakpoints in the Debugging window.

To set a location breakpoint:

  1. If the Details pane is not in view, click the Add/Change Breakpoint button.

  2. Choose At Location from the Event list and type the file name and the line number in the text box, such as Foo.cc:21.

  3. If it is not already set, choose Stop from the Action list.

  4. Click Add.

    The line is highlighted in red to indicate the breakpoint is set. If the line selected is not an executable line of source code, the debugger sets the breakpoint at the next line after the specified line that is executable.

To set a function breakpoint:

  1. If the Details pane is not in view, click the Add/Change Breakpoint button.

  2. Choose In Function from the Event list and type the function or procedure name in the text box.

  3. If it is not already set, choose Stop from the Action list.

  4. Click Add.

    The breakpoint is added to the list of currently active breakpoints.

To remove a breakpoint, do one of the following:

Disable and re-enable breakpoints as you move through your program.

Figure 5-4 Breakpoints Window

Graphic

Scrolling list 

Shows the breakpoints and tracepoints assigned in your program. A breakpoint or tracepoint can be in one of three states: -- Enabled, indicated by a red stop sign -- Disabled, indicated by a gray, crossed-out stop sign 

-- Executed, indicated by an arrow 

Delete button 

Deletes the breakpoint or tracepoint from the source code and removes it from the scrolling list. 

Delete All button 

Deletes all breakpoints and tracepoints from the source code and removes them from the scrolling list. 

Enable button 

Enables the selected breakpoint or tracepoint and changes its glyph to a red stop sign. 

Disable button 

Disables the selected breakpoint or tracepoint and changes its glyph to a gray, crossed-out stop sign. 

Disable All button 

Disables all breakpoints or tracepoints listed and changes their glyphs to gray, crossed-out stop signs. 

Enable All button 

Enables all disabled breakpoints or tracepoints listed and changes their glyphs to red stop signs. 

Show Source button 

Shows the source line of the selected breakpoint or tracepoint in the editor window. 

Add/Change Breakpoints button 

Expands the Breakpoints window. Click to display options for adding or changing a breakpoint in your program. This button toggles to Hide Details. 

Details pane 

Lets you specify the details of a breakpoint.  

Event list 

Allows you to set where and when you want to pause program execution. 

Event text box 

Lets you specify the file name, line number, function name, class name, and so forth, of an event. 

Action list 

Lets you set breakpoint actions such as stopping and 

tracing. 

Option list 

Lets you place additional restrictions on a breakpoint or tracepoint. 

Add button 

Adds a breakpoint or tracepoint with the specified action, event, and option to the source code. In the editor window, a stop sign glyph appears to the left of the source line where the breakpoint or tracepoint appears, and the line is highlighted in red. The breakpoint or tracepoint also appears in the Breakpoints scrolling list. 

Change button 

Updates the event, action, and option of the selected breakpoint or tracepoint. 

Clear button 

Removes all entries from the Event, Action, and Option text boxes. 

Close button 

Closes the Breakpoints window. 

Help button 

Displays online help for the Breakpoints window. 

Collecting Performance Data

While running your program in the debugger, you can use the Sampling Collector to collect performance data and write it to experiment files to be used by the Sampling Analyzer. The Sampling Collector can gather program memory-usage data, execution profile data excluding called function times, and execution profile data including called function times. For more information on collecting and analyzing performance data, see Chapter 6, Analyzing Program Performance,"the Analyzing Program Performance With Sun WorkShop manual, and the Sun WorkShop online help.

You can collect performance data only when you are running in the Sun WorkShop Debugging window and runtime checking is turned off.

To collect performance data:

  1. Choose Windows > Sampling Collector.

  2. Type the complete path name for your experiment file in the Experiment File text box.

  3. Select whether you want to collect data for one run only or for all runs.

    If you run the Sampling Collector for one run only, the Collector shuts off after the experiment is created. If you leave the Collector on for all runs, the Collector remains on even after the experiment is created.

  4. Select the type(s) of data you want to collect.

    If you have chosen to collect Execution Profile data, use the Collect Profile data slider to specify an interval at which the Collector gathers samples.

  5. Select either the Manually, on "New Sample" command radio button or the Periodically radio button to determine when the Collector interrupts data gathering to stop and summarize.

    If you have selected the Periodically button, use the Period slider to define the interval at which the Collector summarizes samples.

  6. Start your program running in the debugger by clicking either Start or Go.

Runtime Checking

Runtime checking, or RTC, allows you to automatically detect runtime errors in an application during the development phase. Using RTC, you can:

To use runtime checking, you must turn on the type of checking you want to use before you execute the program,. Then, when you run the program, runtime checking compiles reports on your memory usage.

Setting Runtime Checking Options

You can customize runtime checking to set defaults for reporting options, error reporting, and stack depth for reports.

To set Runtime Checking options:

  1. Choose Debug > Debugging Options.

    The Debugging Options dialog box is displayed.

  2. Click the Category button and select Runtime Checking.

  3. Click the desired settings in the Runtime Checking category. (For descriptions of the Runtime Checking Options, see "Setting Runtime Checking Options" in the online help.)

Starting Runtime Checking

To turn on memory use checking:

  1. In the Debugging window, choose Windows > Runtime Checking.

    The Runtime Checking window is displayed (see Figure 5-5).

  2. In the Debugging window or the Runtime Checking window, choose Checks > Enable Memuse Checking.

A blue recycling symbol with three arrows pointing in a circle appears in the Debugging window status area and in the Runtime Checking window to remind you that memory use checking is enabled

To turn on memory access checking:

  1. In the Debugging window, choose Windows > Runtime Checking.

    The Runtime Checking window is displayed (see Figure 5-5).

  2. In the Debugging window or the Runtime Checking window, choose Checks > Enable Access Checking.

    A red circle with a white minus sign in the middle (the international Do Not Enter sign) appears in the Debugging window and in the Runtime Checking window to remind you that memory access checking is enabled.

Figure 5-5 Runtime Checking Window

Graphic

File menu 

Provides commands for opening and saving error logs, clearing information from the Runtime Checking window, and closing the window. 

Leaks menu 

Provides commands for controlling the detail level and content of the memory leaks report. 

Blocks menu 

Provides commands for controlling the detail level and content of the memory blocks report. 

Options menu 

Provides a command to display the Runtime Checking category of the Debugging Options dialog box. 

Checks menu 

Provides commands for turning on memory use checking and memory access checking. 

Suppress Last Reported Error button 

Suppresses reporting of the last reported error when you continue running your program. You can use this button after an error is reported and when the program is stopped or interrrupted. 

View Report radio buttons 

Control which runtime checking report is displayed in the output display pane (Access, Memory Leaks, or Memory Blocks) 

Output Display Pane 

Lists the access, memory leak, or memory use report, with a separator line indicating each run of the program or new report requested. 

Tracing Code

Tracing collects information about what is happening in your program and displays it in the Dbx Commands window. Program execution does not stop.

An unfiltered trace displays each line of source code as it is about to be executed, which in all but the simplest programs produces volumes of output.

It is more useful to filter a trace to display information about events in your program. For example, you can trace each call to a function, every member function of a given name, every function in a class, or each exit from a function. You can also trace changes to a variable.

An event is the association of a program event with a debugging action. A typical event is a change in the value of a specified variable. A handler manages debugging events. The trace listing in the Breakpoints window is called a trace handler because it manages the trace, a type of event.

To set up a trace:

  1. In the Breakpoints window, if the Details pane is not displayed, click the Add/Change Breakpoint button.

  2. From the Event list box, choose the type of event you want to trace.

  3. Type any event information, such as the name of a function, or the file name and line number of a location, in the text box.

  4. Choose Action > Trace.

  5. Click Add.

    Note -

    You can control the speed of the trace using the Debugging Behavior category in the Debugging Options dialog box (See the Debugging online help for information on setting debugging options.)

Examining Values and Data

An evaluation is a one-time spot-check of the value of an expression. You can evaluate expressions at any time from the editor window or the Debugging window. You can track the changes in a value each time the program stops using the Data Display window.

The results of an evaluation are listed in the Data History pane of the Debugging window. A dashed line indicates that the evaluation context has changed since the last evaluation. The Data History pane maintains a list of expressions you previously evaluated in a history list. You can clear the Data History pane at any time by choosing Data > Clear History.

To evaluate an expression using the editor window, select the target variable or expression in the source display. Then do one of the following:

The value is shown in the Data History pane. A separator line is inserted into the Data History pane list whenever the evaluation context changes.

To evaluate an expression using the Debugging window:

  1. In the Expression text box, type or paste the variable or expression.

    If the expression you want to examine is visible in the Debugging or editor window, you can select the expression, then choose Data > Evaluate Selected.

  2. Click the Evaluate radio button.

  3. Click the Evaluate button or choose Data > Evaluate Selected.

    Note -

    While the program is stopped, you can change the value of a variable or expression using the Assign button.

Monitoring Data Values

The Data Display window allows you to watch the changes in the value of an expression during program execution. A set of expressions you choose is automatically evaluated every time a program stops executing--at a breakpoint, at a step, and when the program is interrupted. When the value of an expression changes, the value is highlighted in boldface.

From the Data Display window, you can display pop-up windows to view additional information about an expression, giving you control over the information you are viewing.

To monitor the value of an expression:

  1. Open the Data Display window by choosing Windows > Data Display or clicking Display in the Debugging window.

  2. Type an expression in the window by doing one of the following:

    • Type the expression in the Expression text box and click the Display button.

    • Choose Display > New Expression in the Data Display window and type the expression in the text box in the New Expression panel that is displayed.

  3. Place the pointer anywhere in the Data Display window and press the right mouse button to display the Selected Display Item pop-up menu.

    Choose commands from the menu to view context and type information, compare current and previous values, show pointer aliases, and graph arrays.

Examining the Call Stack

The call stack represents all currently active routines--those that have been called but have not yet returned to their respective caller. In the stack, the functions and their arguments are listed in the order that they were called. The initial function (main() for C and C++ programs) is at the top of the Stack pane; the function executing when the program stopped is at the bottom of the Stack pane. This function is known as the stopped in function.

The stopped in function is listed in the Stopped In status line in the Debug Status area of the Debugging window (see Figure 5-1). The source code of the stopped in function is displayed in the editor window with the next line to be executed highlighted in green.

The Evaluation Context line in the status area provides the name of the context function, which determines the scope resolution search order that applies when you provide a symbol name in various debugging operations.

You can examine the call stack by doing any of the following:

Debugging Multithreaded Programs

When a multithreaded program is detected, the Sessions/Threads pane on the Debugging window opens. This pane can be toggled between displaying sessions and displaying threads. For a multithreaded program, the pane lists information about the threads in the currently selected process. The current thread is marked with a green arrow.

To view the context of another thread:

  1. Click the thread in the Threads pane.

    The call stack dynamically updates to reflect the context of the selected thread. The source display also updates. The context function and stopped in function are changed to their respective values for the new thread.

  2. To resume program execution, click Go.

To hide a thread:

  1. Click the thread in the Threads pane.

  2. Choose Threads > Hide Selected.

You can expose threads to help in managing them. To show all hidden threads, choose Threads > Expose Hidden.

Customizing Debugging Sessions

You can set new defaults for debugging performance, output, language, and so on by choosing Debug > Debugging Options. The Debugging Options dialog box is displayed. Using this window, you can customize a debugging session or change defaults for the entire debugger. You can also set many of the defaults by setting environment variables with the dbxenv command.

For detailed information on customizing your debugging session, see Debugging a Program With dbx.