Introduction to Sun WorkShop

Chapter 4

Debugging a Program

Sun WorkShop provides an integrated debugging service that can run a program in a controlled fashion and inspect the state of a stopped program. Sun WorkShop gives you complete control of the dynamic execution of a program, including the collection of performance data.

Through the Debugging window (to open, choose Debug Show Debugging Window) and the windows accessed from it, you can:

• Start a debugging session or multiple debugging sessions
• Determine where your program stops executing
• Control program execution
• Use breakpoints
• Attach to processes
• Trace code
• Evaluate expressions and variables
• Use the call stack
• Fix your program
• Debug multithreaded programs
• Collect performance data
• Use runtime checking
• Graph arrays
• Set up your debugging environment
• Create custom buttons

In addition, machine-level and other commands are available to help you debug code. You can use standard dbx commands in the Dbx Commands window.

For information about debugging how-tos, concepts, windows, and dbx commands, see the Using the Debugging Window and Using dbx Commands sections of the online help (you can access the online help through the Help menu in any Sun WorkShop window).

Preparing for Debugging

To prepare for debugging, you must generate debugging information when you compile your source files by doing one of the following:

• Ask Sun WorkShop to generate debugging information when compiling your project's source files: Choose Project Edit Project in the WorkShop main window, and click Select Project Preferences. When you are finished with your selections, click OK, and then build your project. For more information, click Help in the Edit Current Project window or see "Editing a Project" in the Working With Projects section of the online help.
• Compile the application using the -g or -g0 (zero) option, which instructs the compiler to generate debugging information during compilation (for information on how to specify these options in your makefile, see Appendix B). For more detailed information on preparing your program for debugging, see Debugging a Program with dbx.

Starting Debugging

To start debugging a program:

1. Choose a debugging state.

• Choose Debug Quick Mode to run a program normally, but with debugging ready in the background to save the program in case your program terminates abnormally. Use Quick Mode when you think you are finished debugging, want to avoid waiting for symbols to load, and want to test a fix you made.
• Choose Debug Debug Mode or click Debug in the Sun WorkShop main window tool bar to debug the program using the full functionality of the debugging service.

2. Select the program to debug.

To debug the current program, click Debug in the Sun WorkShop main window tool bar. To debug another program, do the following:

• To debug a program previously run or debugged in Sun WorkShop, select the program from the Debug menu picklist.
• To debug a program that is new to Sun WorkShop, load the new program by choosing Debug New Program.
• To attach to another running process, choose Debug Attach Process.
• To debug a core dump file from an unsuccessful program execution, choose Debug Load Core File.

  Your program loads, and the Debugging window (see FIGURE 4-1) and a text editor window open. Sun WorkShop allows you to view and edit a program's source code and perform basic debugging operations from a text editor window. The editor window tool bar provides access to common debugging operations, especially those that use a source component as an argument, plus buttons from other parts of Sun WorkShop.

  To change your default text editor and set text editor options, see Choosing a Text Editor and Text Editor Options.

3. Run your program by doing one of the following:

• Press F6.
• Click Start in the Debugging window tool bar.
• Choose Execute Start in the Debugging window.
• Click Continue in the Debugging window tool bar.
• Choose Execute Continue in the Debugging window.

  For more information about the Debugging window, see "Debugging Window" in the Using the Debugging Window section of the online help.

You can change run parameters, such as program arguments, the run directory, and environment variables, during a debugging session. For more information, see the following topics in the Using the Debugging Window section of the online help:

• "Specifying Program Arguments"
• "Specifying a Run Directory"
• "Setting Environment Variables"

FIGURE 4-1   Debugging Window

Customizing Your Debugging Session

You can customize your debugging session to change the defaults for:

• Debugging output
• Debugging behavior
• Window layout
• Window behavior
• Data Display windows
• Language and scoping
• Runtime checking
• Data grapher
• Debugging performance
• Forks and threads
• Command-line only
• Advanced options

To view the available debugging options, choose Debug Debugging Options in the Debugging window. Using the Debugging Options dialog box, you can customize a debugging session or change defaults for the entire debugger. You can also set many of the defaults by setting dbx environment variables with the dbxenv command (for more information, see "dbxenv Command" in the Using dbx Commands section of the online help).

For detailed information about choosing debugging options, see:

• "Debugging Options Dialog Box" in the Using the Debugging Window section of the online help
• Debugging a Program With dbx

Stepping Through Your Code

You can view your code by stepping, which is moving through your code one line at a time. As you step, a green highlighted line known as the program counter (PC) marks your place in the program. With each step, the PC moves to the next source line to be executed (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. If the PC stops on the same source line as the call, there are a few more machine instructions remaining that are associated with the call. Stepping once more completes the call and you are on the next source line.

For detailed information about stepping through your code, see "Program Stepping" in the Using the Debugging Window section of the online help.

Setting Breakpoints

You can 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 or the Breakpoints window. 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. (The Breakpoints tab in the Debugging window displays breakpoints you have already set.)

For more information on setting and using breakpoints, see "Breakpoints" and the Using Breakpoints How-Tos in the Using the Debugging Window section of the online help.

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 tab in the Debugging window or a separate Data Display window.

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

To evaluate an expression using the editor window, do one of the following:

• Use the balloon expression evaluator, which instantly shows you the current value of the expression at which your cursor is pointing in your editor. For more information, see "Using the Balloon Expression Evaluator" in the Text Editing section of the online help.
• Select the target variable or expression in the source display. Then do one of the following:
  
  
  • Click Evaluate or choose WorkShop Evaluate Selected to find the value of the selected expression.
    
  • Click Evaluate * or choose WorkShop Evaluate As Pointer to evaluate where a pointer-type expression points.

  The value is shown in the Data History tab, or when the result is short, the result is printed in the footer message area of the editor window. A separator line is inserted into the Data History tab list whenever the evaluation context changes. For more information, see "Expression Evaluation" in the Using the Debugging Window section of the online help.

Monitoring Data Values

By default, Data Display is a tab in the Debugging window. You can choose to have it shown as a separate window. For more information, see "Choosing How to Show the Data Display" in the Using the Debugging Window section of the online help.

The Data Display tab in the Debugging 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.

The Data Display tab shows you how a value changes each time you stop execution. If you need to monitor changes in a value as the program is running, use the On Access breakpoint (see "Breaking On Access" in the Using the Debugging Window section of the online help). With this breakpoint, you can ask the program to stop whenever a specific memory location is either read or written.

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

For more information, see "Data Display Window" and "Data Display Tab" in the Using the Debugging Window section of the online help.

Collecting Performance Data

While running your program in the debugging service, 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 clock-based profiling data, thread-synchronization wait tracing data, hardware counter overflow profiling data, and address-space data. The Collector automatically records global execution statistics, including page-fault and I/O data, context switches, and working-set and paging statistics.

For more information on collecting and analyzing performance data, see:

• Chapter 6 in this book
• Analyzing Program Performance With Sun WorkShop 6
• The Collecting Performance Data How-Tos in the Using the Debugging Window section of the online help

Detecting Runtime Errors

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

• Detect memory access errors
• Detect memory leaks
• Collect data on memory use
• Work with all languages
• Work on code for which you do not have the source, such as libraries

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, RTC compiles reports on your memory usage.

For more information, see "Runtime Checking" in the Using the Debugging Window section of the online help.

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, producing volumes of output. Filtering a trace to display information about events in your program creates more selective output. 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.

For more information, see "Code Tracing" in the Using the Debugging Window section of the online help.

Examining the Call Stack

The call stack represents all currently active routines, routines 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 source code of the stopped in function is displayed in the editor window with the next line to be executed highlighted in green.

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

• Move up one level in the stack by clicking Up or choosing Stack Up.
• Move down one level in the stack by clicking Down or choosing Stack Down.
• Remove multiple frames by placing your cursor next to the frame you want to return to and choosing Stack Pop to Current Frame.
• Remove the function you are stopped in from the stack by choosing Stack Pop.
• Remove multiple frames by placing your pointer next to the frame you want to return to and choosing Stack Pop to Current Frame.

Using Pop gives you a limited form of undo. If you want to start executing from the beginning of the current function again, Pop to the parent stack frame and then step into the function. You are now back at the start of the function.

For more information on using the call stack, see "The Call Stack" in the Using the Debugging Window section of the online help.

Debugging Multithreaded Programs

When a multithreaded program is detected, the Threads tab in the Debugging window opens. You can display sessions by clicking the Sessions tab. For a multithreaded program, the tab lists information about the threads in the currently selected process. The current thread is marked with a green arrow.

For more information, see "Multithreaded Program Debugging" in the Using the Debugging Window section of the online help.

Debugging Processes Simultaneously

You can debug more than one program at a time, with each program connected to a separate debugging session. Following are three examples of programs you might want to debug simultaneously:

• A process and the child process it forks
• A client and server program
• Two related programs

If you are debugging a program and you ask to debug another program, a message tells you that you are currently debugging a program. You will be prompted to terminate or detach the current session and load a new debugging session, reuse the current session, or debug both sessions. Choose to debug both only if you want to debug both programs simultaneously.

Managing Sessions

The Sessions tab in the Debugging window and the Active Sessions dialog box maintain a list of all the debugging sessions. To open the Active Sessions dialog box, choose Debug Manage Sessions in the Debugging Window. The current program is marked with an arrow.

Debugging multiple sessions consumes resources and might slow down your system. The Debugging window states how many active sessions you have. To remove sessions you no longer need, click Detach or Quit Session in the Active Sessions dialog box.

Although you are debugging multiple sessions, you can see the context of only one session at a time. When you switch to a different session, the Debugging window, the editor window, the Dbx Commands window, and the other displays change to reflect the context of the new session.

If you want to see the programs side by side (with an editor and a Debugging window for each program), you need to start two WorkShop applications. To prevent the WorkShop applications from sharing the same editor, start both WorkShop applications with the following command:

% workshop -s editsessionname

For example, start your first WorkShop application with workshop -s 1 and start your second WorkShop application with workshop -s 2. See the workshop(1) man page for more information.

For more information on managing sessions, see "Managing Sessions" in the Using the Debugging Window section of the online help.

Debugging a Child Process

When a process forks a child process, you can choose to debug the parent process, the child process, or both. You can also override the normal deletion of all breakpoints from the forked process.

For more information, see "Child Process Debugging" in the Using the Debugging Window section of the online help.

Exiting Debugging

If you want to close the Debugging window without quitting the processes under the control of Sun WorkShop, choose Debug Close. The processes under the control of Sun WorkShop continue running, using memory and CPU time. Sun WorkShop continues to store data on these processes.

To quit all processes currently under the control of Sun WorkShop and close all debugging windows, choose Debug Exit Debugging in the Debugging window.