[Previous] [Contents] [Index] [Next]

Caution: This version of this document is no longer maintained. For the latest documentation, see http://www.qnx.com/developers/docs.

Debugging Programs

You can select a topic from this diagram:

Utilities Used by the IDE Getting System Information Using Code Coverage Common Wizards Reference Preparing Your Target Developing Photon Applications Developing C/C++ Programs Where Files Are Stored Building OS and Flash Images Migrating to the 6.3 Release Tutorials IDE Concepts About This Guide Analyzing Your System With Kernel Tracing Profiling an Application Finding Memory Errors Debugging Programs Managing Source Code Launch Configurations Reference

Workflow diagram with debug chapter highlighted


This chapter shows you how to work with the debugger.


In this chapter...

Introduction

One of the most frequently used tools in the traditional design-develop-debug cycle is the source-level debugger. In the IDE, this powerful tool provides an intuitive debugging environment that's completely integrated with the other workbench tools, giving you the flexibility you need to best address the problems at hand.

Have you ever had to debug several programs simultaneously? Did you have to use separate tools when the programs were written in different languages or for different processors? The IDE's source debugger provides a unified environment for multiprocess and multithreaded debugging of programs written in C, C++, Embedded C++, or Java. You can debug such programs concurrently on one or multiple remote target systems, or locally if you're doing Neutrino self-hosted development.

In order to use the full power of the Debug perspective, you must use executables compiled for debugging. These executables contain additional debug information that lets the debugger make direct associations between the source code and the binaries generated from that original source. With QNX Make projects, an executable compiled for debugging has "_g" appended to its filename.

The IDE debugger uses GDB as the underlying debug engine. It translates each GUI action into a sequence of GDB commands, then processes the output from GDB to display the current state of the program being debugged.

The IDE updates the views in the Debug perspective only when the program is suspended.


Note: Editing your source after compiling causes the line numbering to be out of step because the debug information is tied directly to the source. Similarly, debugging an optimized binary can also cause unexpected jumps in the execution trace.

Debugging your program

Building an executable for debugging

Although you can debug a regular executable, you'll get far more control by building debug variants of the executables. When you created your project, you may have already set the option to cause the IDE to build an executable that's ready for debugging. If so, you should have executables with _g appended to the filename. If not, you must tell the IDE to build debug variants:

  1. In the C/C++ Projects view (or the Navigator view), right-click the project and select Properties.
  2. In the left pane, select QNX C/C++ Project.
  3. In the right pane, select the Build Variants tab.
  4. Under your selected build variants, make sure Debug is enabled:

    Properties dialog; Build Variants tab

  5. Click Apply.
  6. Click OK.
  7. Rebuild your project (unless you're using the IDE's autobuild feature).

For more information about setting project options, see the Common Wizards Reference chapter.

Starting your debugging session


Note: For a full description of starting your programs and the launch configuration options, see the Launch Configurations Reference chapter.

After building a debug-enabled executable, your next step is to create a launch configuration for that executable so you can run and debug it:

  1. From the main menu, select Run-->Debug.... The launch configurations dialog appears.

    Debug launch configurations

  2. Create a launch configuration as you normally would, but don't click OK.
  3. Select the Debugger tab.

    Debugger tab

  4. Make sure Stop at main() on startup is set.
  5. Click Apply.
  6. Click Debug.

Note: By default, the IDE automatically changes to the Debug perspective when you debug a program. If the default is no longer set, or if you wish to change to a different perspective when you debug, see the "Setting execution options" section in the Launch Configurations Reference chapter.

If launching a debugging session doesn't work when connected to the target with qconn, make sure pdebug is on the target in /usr/bin.


Note: Debugging sessions stay in the Debug perspective until you remove them. These consume resources on your development host and your debugging target. You can automatically delete the completed debug session by checking the Remove terminated launches when a new launch is created box on the Run/Debug-->Launching pane of the Preferences dialog.

Controlling your debug session


Note: The contents of all views in the Debug perspective are driven by the selections you make in the Debug view.

The Debug view lets you manage the debugging or running of a program in the workbench. This view displays the stack frame for the suspended threads for each target you're debugging. Each thread in your program appears as a node in the tree. The view displays the process for each program you're running.

Debug view

The Debug view shows the target information in a tree hierarchy as follows (shown here with a sample of the possible icons):

Session item Description Possible icons
Launch instance Launch configuration name and type (e.g. Stack Builder [C/C++ QNX QConn (IP)]) Icon: Debug  launch instance
Debugger instance Debugger name and state (e.g. QNX GDB Debugger (Breakpoint hit)) Icon: Debugger
Thread instance Thread number and state (e.g. Thread[1] (Suspended)) Icon: Thread; suspended Icon: Thread; running Icon: Thread; stopped
Stack frame instance Stack frame number, function, filename, and line number Icon: Stackframe Icon: Stack frame; running

Note: The number beside the thread label is a reference counter for the IDE, not a thread ID (TID) number.

The IDE displays stack frames as child elements, and gives the reason for the suspension (e.g. end of stepping range, breakpoint hit, signal received, and so on). When a program exits, the IDE displays the exit code.

The label includes the thread's state. In the example above, the thread was suspended because the program hit a breakpoint. You can't suspend only one thread in a process; suspension affects all threads.

The Debug view also drives the C/C++ editor; as you step through your program, the C/C++ editor highlights the location of the execution pointer.

Using the controls

After you start the debugger, it stops (by default) in main() and waits for your input. (For information about changing this setting, see the "Debugger tab" section in the Launch Configurations Reference chapter.)

The debugging controls appear in the following places (but not all together in any one place):

The controls are superseded by breakpoints. For example, if you ask the program to step over a function (i.e. run until it finishes that function) and the program hits a breakpoint, the program pauses on that breakpoint, even though it hasn't finished the function.

The icons and menu items are context-sensitive. For example, you can use the Terminate action to kill a process, but not a stack frame.

Action Icon Hotkey Description
Resume Icon: Resume F8 Run the process freely from current point.
Suspend Icon: Suspend   Regain control of the running process.
Terminate Icon: Terminate   Kill the process.
Restart Icon: Restart   Rerun the process from the beginning.
Resume without signal Icon: Resume without signal   Resume the execution of a process without delivering pending signals.
Step Into Icon: Step Into F5 Step forward one line, going into function calls.
Step Over Icon: Step Over F6 Step forward one line without going into function calls.
Run to return Icon: Step Return F7 Finish this function.
Resume at line Icon: Resume at line   Resume the execution of the process at the specified line. Using this action to change into a different function may cause unpredictable results.

You can control your debug session in various ways:

From the Debug view

You'll probably use the Debug view primarily to control your program flow.

To control your debug execution:

  1. In the Debug view, select the thread you wish to control.
  2. Click one of the stepping icons (e.g. Step Into) in the Debug view's toolbar. Repeat as desired.
  3. Finish the debug session by choosing one of the debug launch controls (e.g. Disconnect). For details, see the section "Debug launch controls" in this chapter.

Using hotkeys

Even if you're running your debug session without the Debug view showing, you can use the hotkeys or (the Run menu) to step through your program. You can enable the debug hotkeys in any perspective.


Note: You can easily customize these keys through the Preferences dialog:

Key preferences


To customize the debug hotkeys:

  1. Choose Window-->Preferences from the menu. The Preferences dialog is displayed.
  2. Choose Workbench-->Keys in the list on the left.
  3. Choose Run/Debug in the Category drop-down. The commands for running and stepping through a program are displayed.
  4. Select a command in the Name drop-down. Its scope, configuration, and current key sequence (if any) are listed in the Assignments box.
  5. To assign this command to a new hot key, click in the Key sequence box, then press the key(s) for your new hot key.
  6. Click the Add button to assign the newly created hot key to the selected command.
  7. Click OK to activate your new hot keys.

From the C/C++ editor

You can control your debug session using the C/C++ editor by having the program run until it hits the line your cursor is sitting on (i.e. the gdb until command). If the program never hits that line, the program runs until it finishes.

You can also use the C/C++ editor's context menu to resume execution at a specific line, or to add a watch expression.

To use the C/C++ editor to debug a program:

  1. In the editor, select a file associated with the process being debugged.
  2. Left-click to insert the cursor where you want to interrupt the execution.
  3. Right-click near the cursor and select Run To Line, Resume at line or Add watch expression.

Note: Note that Run To Line only works in the current stack frame. That is, you can use Run to Line within the currently executing function.

Debug launch controls

In addition to controlling the individual stepping of your programs, you can also control the debug session itself (e.g. terminate the session, stop the program, and so on) using the debug launch controls available in the Debug view (or in the view's right-click menu).

As with the other debug controls, these are context-sensitive; some are disabled depending on whether you've selected a thread, a process, and so on, in the Debug view.

Action Icon Description
Terminate Icon: Terminate Kill the selected process.
Terminate & Remove Icon: Terminate and Remove Kill the selected process and remove it from the Debug view.
Terminate All Icon: Terminate All Kill all active processes in the Debug view.
Disconnect Icon: Disconnect Detach the debugger (i.e. gdb) from the selected process (useful for debugging attached processes).
Remove All Terminated Launches Icon: Remove All Terminated Clear all the killed processes from the Debug view.
Relaunch Icon: Relaunch Restart the process.

Disassembly mode

You can also examine your program as it steps into functions that you don't have source code for, such as printf(). Normally, the debugger steps over these functions, even when you click Step Into. When the instruction pointer enters functions for which it doesn't have the source, the IDE shows the function in the Disassembly view.

To show the Disassembly view:

=>> From the menu, choose Window-->Show View-->Disassembly.

The workbench adds the Disassembly view to the Debug perspective.

More debugging features

Besides the Debug view, you'll find several other useful views in the Debug perspective:

To: Use this view:
Inspect variables Variables
Using breakpoints and watchpoints Breakpoints
Evaluate expressions Expressions
Inspect registers Registers
Inspect a process's memory Memory
Inspect shared library usage Shared Libraries
Monitor signal handling Signals
View your output Console
Debug with GDB Console

Inspecting variables

The Variables view displays information about the variables in the currently selected stack frame:

Variables view

At the bottom of the view, the Detail pane displays the value of the selected variable (as evaluated by gdb).


Note: If you happen to have multiple variables of the same name, the one most in scope is evaluated.

When the execution stops, the changed values are highlighted in red (by default). Like the other debug-related views, the Variables view doesn't try to keep up with the execution of a running program; it updates the display only when execution stops.

You can decide whether or not to display the variable type (e.g. int) by clicking the Show Type Names toggle button (Icon: Show Type Names).

Variables view

You can also control whether or not the IDE tracks your program's variables. See the "Debugger tab" section in the Launch Configurations Reference chapter.

Inspecting global variables

By default, global variables aren't displayed in the Variables view. To add global variables to the view:

  1. In the Variables view, click the Add Global Variables button (Add Global  Variables).
  2. Select one or more symbols in the Selection Needed dialog.

    Selection Needed

  3. Click OK to add the selected globals to the Variables view.

Changing variable values

While debugging a program, you may wish to manually change the value of a variable to test how your program handles the setting or to speed through a loop.

To change a variable value while debugging:

  1. In the Variables view, right-click the variable and select the Change Value... item.

    Changing a variable's value

  2. Enter the new value in the field.

Note: You can also change a variable's value in the detail pane at the bottom of the Variables view. Click the value, change it, then press Ctrl-S to save the new value.

Controlling the display of variables

You can prevent the debugger from reading the value of variables from the target. You might use this feature for variables that are either very sensitive or specified as volatile.

To enable or disable a variable:

=>> In the Variables view, right-click the variable and select either Enable or Disable. (You can disable all the variables in your launch configuration. See the "Debugger tab" section in the Launch Configurations Reference chapter.)

To change a variable to a different type:

  1. In the Variables view, right-click the variable.
  2. Select one of the following:
    Cast To Type...
    Casts the variable to the type you specify in the field (e.g. int).

    Casting to another type

    Restore Original Type
    Cancels your Cast To Type command.
    Format, followed by a type
    Displays the variable in a different format (e.g. hexadecimal).
    Display As Array
    Displays the variable as an array with a length and start index that you specify. This option is available only for pointers.

Using breakpoints and watchpoints

The Breakpoints view lists all the breakpoints and watchpoints you've set in your open projects:

Breakpoints view

A breakpoint makes your program stop whenever a certain point in the program is reached. For each breakpoint, you can add conditions to better control whether or not your program stops.

A watchpoint is a special breakpoint that stops the program's execution whenever the value of an expression changes, without specifying where this may happen. Unlike breakpoints, which are line-specific, watchpoints are event-specific and take effect whenever a specified condition is true, regardless of when or where it occurred.

Object Icon
Breakpoint Icon: Breakpoint
Watchpoint (read) Icon: Watchpoint; read
Watchpoint (write) Icon: Watchpoint; write
Watchpoint (read and write) Icon: Watchpoint; read and write

If the breakpoint or watchpoint is for a connected target, the IDE places a check mark (Icon: Check mark; overlay) on the icon.

The rest of this section describes how to:

Adding breakpoints

You set breakpoints on an executable line of a program. When you debug the program, the execution suspends before that line of code executes.

To add a breakpoint:

  1. In the editor area, open the file that you want to add the breakpoint to.
  2. Notice that the left edge of the C/C++ editor has a blank space called a marker bar.
  3. Hover your pointer over the marker bar beside the exact line of code where you want to add a breakpoint. Right-click the marker bar and select Toggle Breakpoint.

    A dot appears, indicating the breakpoint:

    Breakpoints view; breakpoint added

    A corresponding dot also appears in the Breakpoints view, along with the name of the file in which you set the breakpoint:.

To add a breakpoint at the entry of a function:

=>> In either the Outline or C/C++ Projects view, right-click a function and select Toggle Breakpoint.

Adding watchpoints

To add a watchpoint:

  1. Right-click in the Breakpoints view and choose the Add Watchpoint (C/C++)... item.

    Breakpoints view; adding watchpoints

  2. Enter an expression in the field. The expression may be anything that can be evaluated inside an if statement. (e.g. y==1)
  3. If you want the program to stop when it reads the watch expression, check Read; to have the program stop when it writes the expression, check Write.
  4. Click OK. The watchpoint appears in the Breakpoints view list.

Setting properties of breakpoints and watchpoints

After you've set your breakpoint or watchpoint, the IDE unconditionally halts the program when:

To set the properties for a breakpoint or watchpoint:

  1. In the Breakpoints view, right-click the breakpoint or watchpoint and select the Breakpoint Properties... item. (For breakpoints only, in the C/C++ editor, right-click the breakpoint and select Breakpoint Properties.)

    Breakpoints view; setting breakpoint properties

  2. To restrict the breakpoint to a specific treads, make sure they are selected in the Filtering panel.
  3. Use the Common panel to modify the watchpoint's behavior.

    Common Breakpoint properties

    In the Condition field, enter the Boolean expression to evaluate. The expression may be anything that can be evaluated inside an if statement (e.g. x > y ). The default is TRUE.

    In the Ignore Count field, enter the number of times the breakpoint or watchpoint may be hit before it begins to take effect (not the number of times the condition is true). The default is 0.

  4. Click OK. When in debug mode, your program stops when it meets the conditions you've set for the breakpoint or watchpoint.

Disabling/enabling breakpoints and watchpoints

You may wish to temporarily deactivate a breakpoint or watchpoint without losing the information it contains.

To disable or enable a breakpoint or watchpoint:

=>> In the Breakpoints view, right-click the breakpoint or watchpoint and select Disable or Enable. Clicking the check box in the Breakpoints view (so the breakpoint is no longer selected) also disables the breakpoint.

For breakpoints only, right-click the breakpoint in the editor area and select Disable Breakpoint or Enable Breakpoint.

To disable or enable multiple breakpoints or watchpoints:

  1. In the Breakpoints view, use any of the following methods to select the breakpoints:
  2. Right-click the highlighted breakpoints/watchpoints and select Disable or Enable.

Removing breakpoints and watchpoints

To remove one or more breakpoints/watchpoints:

=>> Select the breakpoint or watchpoint, right-click, then select Remove or Remove All.

Evaluating your expressions

The Expressions view lets you evaluate and examine the value of expressions:

Expressions view


Note: The Expressions view is similar to the Variables view; for more information, see the "Inspecting variables" section in this chapter.

To evaluate an expression:

  1. Right-click the Expressions view, then choose Add Watch Expression.

    Expressions view; add expressions

  2. Enter the expression you want to evaluate (e.g. (x-5)*3 ).
  3. Click OK. The expression and its value appear in the Expressions view. When the debugger suspends the program's execution, it reevaluates all expressions and highlights the changed values.

Inspecting your registers

The Registers view displays information about the registers in the currently selected stack frame. When the execution stops, the changed values are highlighted.


Note: The Registers view is similar to the Variables view; for more information, see the "Inspecting variables" section in this chapter.

Registers view

You can also customize the colors in the Registers view and change the default value of the Show Type Names option.

Inspecting a process's memory

The Memory view lets you inspect and change your process's memory. The view consists of four tabs that let you inspect multiple sections of memory:

Memory view


Note: QNX Neutrino uses a virtual-addressing model wherein each process has its own range of valid virtual addresses. This means that the address you enter into the Memory view must be a virtual address that's valid for the process you're debugging (e.g. the address of any variable). For more on QNX Neutrino's memory management, see the Process Manager chapter in the System Architecture guide.

Inspecting memory

The Memory view supports the same addressing as the C language. You can address memory using expressions such as 0x0847d3c, (&y)+1024, and *ptr.

To inspect the memory of a process:

  1. In the Debug view, select a process. Selecting a thread automatically selects its associated process.
  2. In the Memory view, select one of the four tabs (labeled Memory 1, Memory 2, etc.).
  3. In the Address field, type the address, then press Enter.

Changing memory


Caution: Changing a process's memory can make your program crash.

To change the memory of a process:

  1. Follow the procedure for inspecting a process's memory.
  2. In the memory pane, type the new value for the memory. The Memory view works in "type-over" mode; use the Tab and arrow keys to jump from byte to byte.

    The changed memory appears in red.

Configuring output format

You can configure your output to display hexadecimal or decimal. You can also set the number of display columns and the memory unit size. You can configure each memory tab independently.

To configure the output format:

  1. In the Memory view, select one of the four tabs labeled Memory 1, Memory 2, and so on.
  2. Right-click the pane and select the item you want to configure (Format, Memory Unit Size, or Number of Columns).
  3. Choose your desired format; the output reflects your selection.

    Note that some output formats look best in a monospaced font such as Courier.

Customizing the Memory view

You can customize the Memory view's colors and fonts. You can also customize some of its behavior.

To access the view's customization dialog:

  1. From the menu, select Window-->Preferences.
  2. In the left pane, select Run/Debug-->Memory View.
  3. You can now change the colors, font, and behavior of the Memory view. When you're done, click Apply, then OK.

Inspecting shared-library usage

The Shared Libraries view shows you information about the shared libraries for the session you select in the Debug view. The view shows the name, start address, and end address of each library. Shared Libraries view

To load a library's symbols:

=>> Right-click a library and select Load Symbols (or Load Symbols for All for all your libraries).

Monitoring signal handling

The Signals view provides a summary of how your debugger handles signals that are intercepted before they're received by your program.

Signals view

The view contains the following fields:

Name
The name of the signal
Pass
The debugger can filter out signals. If the signal is set to "no", the debugger prevents it from reaching your program.
Suspend
Upon receipt of a signal, the debugger can suspend your program as if it reached a breakpoint. Thus, you can step through your code and watch how your program handles the signal.

To change how the debugger handles a signal:

  1. In the Signals view, select a signal (e.g. SIGINT) in the Name column.
  2. Right-click the signal's name, then choose Signal Properties... from the menu.

    Signal properties

  3. In the signal's Properties dialog, check Pass this signal to the program. to pass the selected signal to the program. Uncheck it to block this signal.

    Check Suspect the program when this signal happens. to suspend the program when it receives this signal. Uncheck it to let the program handle the signal as it normally would.

To send a signal to a suspended program:

  1. In the Signals view, select a signal.
  2. If the program isn't suspended, click the Suspend button (Icon: Suspend) in the View.
  3. In the Signals view, right-click your desired signal and select Resume With Signal. Your program resumes and the debugger immediately sends the signal.

Note: You can see a thread-by-thread summary of how your program handles signals using the Signal Information view. To learn more, see the "Mapping process signals" section in the Getting System Information chapter.

Viewing your output

The Console view shows you the output of the execution of your program and lets you supply input to your program:

Console view

The console shows three different kinds of text, each in a different default color:

You can choose different colors for these kinds of text on the preferences pages.

To access the Console view customization dialog:

  1. From the menu, select Window-->Preferences.
  2. In the left pane, select Run/Debug-->Console.

Debugging with GDB

The IDE lets you use a subset of the commands that the gdb utility offers:

Console view; GDB

To learn more about the gdb utility, see its entry in the Utilities Reference

Enabling the QNX GDB Console view

The QNX GDB Console view is part of the regular Console view but isn't accessible until you toggle to it. Once you do, GDB output appears in place of the regular Console view output.

To enable the QNX GDB Console view:

  1. In the Debug view, select a debug session.
  2. Click the Display selected console button (Icon: Display selected console). The Console view changes to the QNX GDB Console view.

Using the QNX GDB Console view

The QNX GDB Console view lets you bypass the IDE and talk directly to GDB; the IDE is unaware of anything done in the QNX GDB Console view. Items such as breakpoints that you set from the QNX GDB Console view don't appear in the C/C++ editor.


Note: You can't use the Tab key for line completion because the commands are sent to GDB only when you press Enter.

To use the QNX GDB Console view:

=>> In the QNX GDB Console view, enter a command (e.g. nexti to step one instruction):

Console view; GDB; using


[Previous] [Contents] [Index] [Next]