Google Git
Sign in
eclipse / cdt / org.eclipse.cdt / db794992cbbb687ea7c111afb992915d6f431fc1 / . / doc / org.eclipse.cdt.doc.user / raw / hackedguide / dbug.html
blob: 5d3a166c0e9a5b8b7efacdc684de502835b1b2ea [file] [log] [blame]
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.ord/TR/html4/loose.dtd">
<html>
<head>
<title>Debugging Programs</title>
</head>
<body bgcolor="#ffffff" text="#000000">
<hr>
<h1><a name="id1">Debugging Programs</a></h1>
<p>
Once you've written your program, you might need to debug it. The IDE debugger lets you detect and diagnose errors in your programs, whether they're running locally or remotely.</p>
<p>Suggested prior reading: </p>
<ul>
<li>the <a href="cdev.html">Developing C/C++ Programs</a> chapter</li>
</ul>
<p>Related information:</p>
<ul>
<li><tt>gdb</tt></a> utility
</li>
</ul>
<p> </p>
In this chapter:
<ul>
<li><a href="#how">Introduction</a>
</li>
<li><a href="#debug">Debugging your program</a>
</li>
<li><a href="#control">Controlling your debug session (Debug view)</a>
</li>
<li><a href="#more">More debugging features</a></li>
</ul>
<h1><a name="how">Introduction</a></h1>
<p>The debugger lets you see what's going on "inside" a program while it executes, and what it was doing at the moment it crashed or misbehaved.</p>
<p>
In order to use the full power of the <b>Debug</b> 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. The debuggable executables have <tt>_g</tt> appended to their filenames. </p>
<p>
The IDE debugger uses GDB as the underlying debug engine. It translates each GUI action into a sequence of GDB commands and processes the output from GDB to display the current state of the program being debugged. </p>
<p>
The views update only when the program is suspended.</p>
<p></p>
<hr>
<table>
<tr><td valign="top"><img src="image-lib/pointing.gif" alt="Note:"></td>
<td>Editing the source after compiling causes the line numbering to be out of step because the debug information is tied directly to the source.
Similarly, debugging optimized binaries can also cause unexpected jumps in the execution trace.</td></tr>
</table>
<hr>
<h1><a name="debug">Debugging your program</a></h1>
<p>To debug a program, you must build an executable and launch the debugging session. Once you've launched your debugging session, you'll want to control the session.</p>
<h2><a name="id5">Building a debuggable executable</a></h2>
<p>Although you can debug a regular executable, you get far more control by building debug variants of the executables. When you created your project, you may have already set the option to make the IDE build one. If so, you should have debuggable executables with <tt>_g</tt> appended to the filename. If not, you must set the IDE to build debug variants:</p>
<ol>
<li>In the <b>C/C++ Projects</b> view (or the <b>Navigator</b> view), right-click the project and select <b>Properties</b>.
</li>
<li>In the left pane, select <b>QNX C/C++ Project</b>.
</li>
<li>In the right pane, select the <b>Options</b> tab.
</li>
<li>Under <b>Build Type</b>, ensure <b>Build debug version</b> is enabled:<p> <img src="./images/persp_dbug_properties_options.jpg" alt="Properties dialog; options tab">
</p></li>
<li>Click <b>Apply</b>.
</li>
<li>Click <b>OK</b>.
</li>
<li>If it's not done automatically, rebuild the project.</li>
</ol>
<p>For more information about setting project options, see the <a href="cwiz.html">Common Wizards</a> chapter.</p>
<h2><a name="id7">Starting your debugging session</a></h2>
<hr>
<table>
<tr><td valign="top"><img src="image-lib/pointing.gif" alt="Note:"></td>
<td>For a full description of starting your programs and the <b>Launch Configurations</b> options, see the <a href="lnch.html">Starting Your Programs</a> chapter.</td></tr>
</table>
<hr>
<p>
Once you've got a debuggable executable, you must create a launch configuration. </p>
<p>
To launch a debuggable executable:</p>
<ol>
<li>From the main menu, select <b>Run</b>--><b>Debug</b>. (This menu item appears by default in the <b>C/C++ Development</b> perspective. If it doesn't, or you wish to add it to another perspective, select <b>Window</b>--><b>Customize Perspective</b>. In the left pane, select <b>Other</b>--><b>Launch</b>. Enable <b>Launch</b>.)
The <b>Launch Configurations</b> dialog appears.
</li>
<li>Create a launch configuration as you normally would, but don't click <b>OK</b>.
</li>
<li>Select the <b>Debugger</b> tab.
</li>
<li>Ensure <b>Run program in debugger</b> is selected.
</li>
<li>Ensure <b>Stop at main() on startup</b> is enabled.
</li>
<li>Click <b>Apply</b>.
</li>
<li>By default, the IDE automatically changes to the <b>Debug</b> perspective when you debug a program. If the default is no longer set, or you wish to change to a different perspective when you debug, see the <a href="lnch.html#lnch_tabs">"Setting execution options (Launch Configurations tabs)"</a> section in the <a href="lnch.html">Starting Your Programs</a> chapter.
</li>
<li>Click <b>Debug</b>.</li>
</ol>
<h1><a name="control">Controlling your debug session (Debug view)</a></h1>
<p>The <b>Debug</b> view shows a listing of your debug sessions and lets you run your code step-by-step. The IDE is powerful; you can simultaneously debug multiple processes, each with multiple threads.</p>
<h2><a name="id10">Understanding the Debug view</a></h2>
<p>The <b>Debug</b> 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. </p>
<p><img src="./images/view_debug.jpg" alt="Debug view"></p>
<p>The <b>Debug</b> view shows the target information in a tree hierarchy as follows (shown here with a sample of the possible icons):</p>
<table border=1 width="100%">
<tr>
<th>Session item
</th>
<th>Description
</th>
<th>Possible<br>icons</th>
</tr>
<tr>
<td>Launch instance
</td>
<td>Launch configuration name and launch type (e.g. <tt>Stack Builder [C/C++ QNX QConn (IP)]</tt>)
</td>
<td><img src="./images/icon_debug_exc.gif" alt="Icon: Debug executable">
<img src="./images/icon_run_exc.gif" alt="Icon: Run executable">
</td>
</tr>
<tr>
<td>Debugger instance
</td>
<td>Debugger name and state (e.g. <tt>GDB Debugger (Breakpoint hit)</tt>)
</td>
<td><img src="./images/icon_debugt_obj.gif" alt="Icon: Debugger">
</td>
</tr>
<tr>
<td>Thread instance
</td>
<td>Thread number and state (e.g. <tt>Thread[1] (Suspended)</tt>)
</td>
<td><img src="./images/icon_thread1.gif" alt="Icon: Thread; suspended">
<img src="./images/icon_thread2.gif" alt="Icon: Thread; running">
<img src="./images/icon_thread3.gif" alt="Icon: Thread; stopped">
</td>
</tr>
<tr>
<td>Stack frame instance
</td>
<td>Stack frame number, function, filename, and file line number
</td>
<td><img src="./images/icon_stackframe.gif" alt="Icon: Stackframe">
<img src="./images/icon_stackframe_running.gif" alt="Icon: Stack frame; running"></td>
</tr>
</table>
<hr>
<table>
<tr><td valign="top"><img src="image-lib/pointing.gif" alt="Note:"></td>
<td>The number beside the thread label is a reference counter for the IDE, not a thread identification number (TID).</td></tr>
</table>
<hr>
<p>
The IDE displays stack frames as child elements. It displays the reason for the suspension beside the target, such as end of stepping range, breakpoint hit, signal received, and so on. When a program exits, the IDE displays the exit code. </p>
<p>
The label includes the thread's state. In the example above, the label indicates that the thread was suspended because the program hit a breakpoint. You can't suspend only one thread in a process; when one thread is suspended, they all are.</p>
<p>
The <b>Debug</b> view also drives the <b>C/C++ Editor</b>; as you step through your program, the <b>C/C++ Editor</b> highlights the location of the execution pointer.
</p>
<h2><a name="id12">Controlling your debug execution</a></h2>
<p>After you start your debug execution, it stops (by default) in <i>main()</i> and waits for your input. (For information about changing this setting, see the <a href="lnch.html#tab_debugger">"Debugger tab"</a> section in the <a href="lnch.html">Starting Your Programs</a> chapter.) You can control your debug execution in various ways, but they all rely on a core set of debug controls. </p>
<h3><a name="id14">Debug execution controls</a></h3>
<p>The debug execution controls appear in the following places (though they don't all appear in any one place):</p>
<ul>
<li>at the top of the <b>Debug</b> view as buttons
</li>
<li>in the <b>Debug</b> view right-click context menu
</li>
<li>in the main menu under <b>Run</b> (with hotkeys)
</li>
<li>in the <b>C/C++ Editor</b>.</li>
</ul>
<p> The debug execution controls are superceded 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, it pauses, even though it hasn't finished the function.</p>
<p>
The icons and menu items are context-sensitive. For example, you can terminate a process, but you can't terminate a stack frame.</p>
<table border=1 width="100%">
<tr>
<th>Action
</th>
<th>Icon
</th>
<th>Hotkey
</th>
<th>Description
</th>
</tr>
<tr>
<td><b>Resume</b>
</td>
<td><img src="./images/icon_resume.gif" alt="Icon: Resume">
</td>
<td><font face="Helvetica"><b>F8</b></font>
</td>
<td>Run the process freely from current point
</td>
</tr>
<tr>
<td><b>Suspend</b>
</td>
<td><img src="./images/icon_suspend.gif" alt="Icon: Suspend">
</td>
<td>&nbsp;
</td>
<td>Regain control of the running process
</td>
</tr>
<tr>
<td><b>Terminate</b>
</td>
<td><img src="./images/icon_terminate.gif" alt="Icon: Terminate">
</td>
<td>&nbsp;
</td>
<td>Kill the process
</td>
</tr>
<tr>
<td><b>Restart</b>
</td>
<td><img src="./images/icon_restart.gif" alt="Icon: Restart">
</td>
<td>&nbsp;
</td>
<td>Rerun the process from the beginning
</td>
</tr>
<tr>
<td><b>Step into</b>
</td>
<td><img src="./images/icon_stepinto.gif" alt="Icon: Step Into">
</td>
<td><font face="Helvetica"><b>F5</b></font>
</td>
<td>Step forward one line, going into function calls
</td>
</tr>
<tr>
<td><b>Step over</b>
</td>
<td><img src="./images/icon_stepover.gif" alt="Icon: Step Over">
</td>
<td><font face="Helvetica"><b>F6</b></font>
</td>
<td>Step forward one line, not going into function calls
</td>
</tr>
<tr>
<td><b>Run to return</b>
</td>
<td><img src="./images/icon_stepreturn.gif" alt="Icon: Step Return">
</td>
<td><font face="Helvetica"><b>F7</b></font>
</td>
<td>Finish this function </td>
</tr>
</table>
<h3><a name="id16">Controlling your debug execution (Debug view)</a></h3>
<p>You can control how many steps the program runs before it suspends again (if you want it to suspend at all). You'll probably use the <b>Debug</b> view primarily to control your program flow.</p>
<p>
To control your debug execution:</p>
<p></p>
<ol>
<li>In the <b>Debug</b> view, select the thread you wish to control.
</li>
<li>Click one of the debug stepping icons described in the "Debug execution controls" section, above.
</li>
<li>Repeat step 2 as desired.
</li>
<li>Finish the debug session by choosing one of the controls described in the "Debug launch controls" section in this chapter.</li>
</ol>
<h3><a name="id18">Controlling your debug execution (hotkeys)</a></h3>
<p>If you're running your debug session without the <b>Debug</b> view showing, you can use either the hotkeys or the <b>Run</b> menu to step through your program. The customization works on a per-perspective basis; if you want to use the hotkeys in another perspective, you must enable them there, too.</p>
<p>
To enable the debug hotkeys:</p>
<ol>
<li>Open the perspective you want to enable the hotkeys for.
</li>
<li>From the menu, select <b>Window</b>--><b>Customize Perspective</b>.
</li>
<li>In the left pane, select <b>Other</b>--><b>Debug</b>.
</li>
<li>In the left pane, enable <b>Debug</b>.
</li>
<li>Click <b>OK</b>.
The hotkeys are enabled for that particular perspective. You can also access the controls from the <b>Run</b> menu.
</li>
</ol>
<h3><a name="id20">Controlling your debug execution (C/C++ Editor)</a></h3>
<p>You can control your debug session using the <b>C/C++ Editor</b> by having the program run until it hits the line your cursor is sitting on. (This is the same as the <tt>gdb until</tt> command.) If the program never hits that line, the program runs until it finishes. </p>
<p>
You enable this option on a per-perspective basis. The option is enabled by default in the <b>Debug</b> perspective.</p>
<p>
To enable debug execution using the <b>C/C++ Editor</b>:</p>
<p></p>
<ol>
<li>From the menu, select <b>Window</b>--><b>Customize Perspective</b>.
</li>
<li>In the left pane, select <b>Other</b>--><b>C/C++ Debug</b>.
</li>
<li>In the left pane, enable <b>C/C++ Debug</b>.
</li>
<li>Click <b>OK</b>.
The controls for debug execution in the <b>C/C++ Editor</b> are enabled for your active perspective.</li>
</ol>
<p>
To debug using the <b>C/C++ Editor</b>:</p>
<p></p>
<ol>
<li>In the <b>C/C++ Editor</b>, select a file associated with the process being debugged (e.g. <tt>myProgram.c</tt>).
</li>
<li>Left-click to insert the cursor where you want to interrupt the execution.
</li>
<li>Right-click near the cursor and select <b>Run to C/C++ Line</b>:
<p> <img src="./images/view_debug_runtoline.jpg" alt="Debug view; run to line"></p><p> The program continues running until it hits that line.</p></li>
</ol>
<h2><a name="id22">Debug launch controls</a></h2>
<p>In addition to controlling the individual stepping of your programs, you can also control the debug session itself. You can perform actions such as terminating the session, stopping the program, and so on, using the debug launch controls available in the <b>Debug</b> view or in the <b>Debug</b> view's right-click context 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 <b>Debug</b> view.</p>
<p></p>
<table border=1 width="100%">
<tr>
<th>Action
</th>
<th>Icon
</th>
<th>Description</th>
</tr>
<tr>
<td><b>Terminate</b>
</td>
<td><img src="./images/icon_terminate.gif" alt="Icon: Terminate">
</td>
<td>Kill the selected process </td>
</tr>
<tr>
<td><b>Terminate &amp; Remove</b>
</td>
<td><img src="./images/icon_terminate_rem.gif" alt="Icon: Terminate and Remove">
</td>
<td>Kill the selected process and remove it from the <b>Debug</b> view </td>
</tr>
<tr>
<td><b>Terminate All</b>
</td>
<td><img src="./images/icon_terminate_all.gif" alt="Icon: Terminate All">
</td>
<td>Kill all active processes in the Debug view </td>
</tr>
<tr>
<td><b>Disconnect</b>
</td>
<td><img src="./images/icon_disconnect.gif" alt="Icon: Disconnect">
</td>
<td>Detach the debugger (i.e. <tt>gdb</tt>) from the selected process (useful for debugging attached processes) </td>
</tr>
<tr>
<td><b>Remove All Terminated Launches</b>
</td>
<td><img src="./images/icon_remove_all.gif" alt="Icon: Remove All Terminated">
</td>
<td>Clear all the killed processes from the Debug view </td>
</tr>
<tr>
<td><b>Relaunch</b>
</td>
<td><img src="./images/icon_relaunch.gif" alt="Icon: Relaunch">
</td>
<td>Restart the process</td>
</tr>
</table>
<h2><a name="id24">Disassembly mode</a></h2>
<p>When you're debugging, you can also examine your program as it steps into functions that you don't have source code for, such as <i>printf()</i>. Normally, the debugger steps over these functions, even when you click <b>Step Into</b>. When the instruction pointer enters functions for which it doesn't have the source, the IDE shows the function in the <b>Assembly Editor</b>.
</p>
<p>To step into assembler functions during debugging:</p>
<table>
<tr><td valign="top"><img src="image-lib/onestep.gif" alt="=&gt;&gt;"></td>
<td>In the <b>Debug</b> view, click the <b>Disassembly Mode On/Off</b> toggle button <img src="./images/icon_disassembly.gif" alt="Icon: Disassembly Mode On/Off">.
As you <b>Step Into</b> assembler functions, the IDE shows the execution trace in the <b>Assembly Editor</b>.</td></tr>
</table>
<h1><a name="more">More debugging features</a></h1>
<p>This section contains the following subsections:</p>
<ul>
<li><a href="#view_variables">Inspecting your variables (Variables view)</a>
</li>
<li><a href="#view_breakpoints">Using breakpoints and watchpoints (Breakpoints view)</a>
</li>
<li><a href="#view_expressions">Evaluating your expressions (Expressions view)</a>
</li>
<li><a href="#view_registers">Inspecting your registers (Registers view)</a>
</li>
<li><a href="#view_memory">Inspecting your process memory (Memory view)</a>
</li>
<li><a href="#view_console">Viewing your output (Console view)</a>
</li>
<li><a href="#view_console_gdb">Debugging with GDB (Console view)</a></li>
</ul>
<h2><a name="view_variables">Inspecting your variables (Variables view)</a></h2>
<p>
The <b>Variables</b> view displays information about the variables in the currently selected stack frame:</p>
<p><img src="./images/view_variables.jpg" alt="Variables view"></p>
<p> When the execution stops, the changed values are highlighted in red (by default). Like the other debug-related views, the <b>Variables</b> view doesn't try to keep up with the execution of a running program; it updates only when execution stops.
</p>
<p>You can set whether or not the variable type (e.g. <tt>int</tt>) is displayed by clicking the <b>Show Type Names</b> toggle button <img src="./images/icon_tnames.gif" alt="Icon: Show Type Names">.</p>
<h3><a name="id28">Customizing the Variables view</a></h3>
<p>You can customize the look of the <b>Variables</b> view and set the color of changed variables (red by default).
</p>
<p>To access the <b>Variables</b> view preferences:</p>
<ol>
<li>From the main menu, select <b>Window</b>--><b>Preferences</b>.
</li>
<li>In the left pane, select <b>Debug</b>--><b>Variables View</b>:<p> <img src="./images/view_variables_customize.jpg" alt="Variables view; customization"></p></li>
</ol>
<h3><a name="id30">Changing variable values</a></h3>
<p>During the course of debugging, you may wish to artificially change the value of a variable to test how your program handles the setting or to speed through a loop.</p>
<p>
To change a variable value while debugging:</p>
<p></p>
<ol>
<li>In the <b>Variables</b> view, right-click the variable and select <b>Change Variable Value</b>.
</li>
<li>Enter the new value in the available field.</li>
</ol>
<h2><a name="view_breakpoints">Using breakpoints and watchpoints (Breakpoints view)</a></h2>
<p>The <b>Breakpoints</b> view lists all the breakpoints and watchpoints you've set in your open projects:</p>
<p><img src="./images/view_breakpoints.jpg" alt="Breakpoints view">
</p>
<p>A <i>breakpoint</i> 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.</p>
<p>
A <i>watchpoint</i> 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.</p>
<p></p>
<table border=1 width="100%">
<tr>
<th>Object
</th>
<th>Icon</th>
</tr>
<tr>
<td>Breakpoint
</td>
<td><img src="./images/icon_breakpoint_obj.gif" alt="Icon: Breakpoint"></td>
</tr>
<tr>
<td>Watchpoint (read)
</td>
<td><img src="./images/icon_watchpoint_read_obj.gif" alt="Icon: Watchpoint; read"></td>
</tr>
<tr>
<td>Watchpoint (write)
</td>
<td><img src="./images/icon_watchpoint_write_obj.gif" alt="Icon: Watchpoint; write"></td>
</tr>
<tr>
<td>Watchpoint (read and write)
</td>
<td><img src="./images/icon_watchpoint_readwrite_obj.gif" alt="Icon: Watchpoint; read and write"></td>
</tr>
</table>
<p>If the breakpoint or watchpoint is for a connected target, a check mark <img src="./images/icon_installed_ovr.gif" alt="Icon: Checkmark; overlay"> is superimposed on the icon.
</p>
<p>The rest of this section describes how to:
</p>
<ul>
<li><a href="#view_breakpoints_add_break">Add breakpoints</a>
</li>
<li><a href="#view_breakpoints_add_watch">Add watchpoints</a>
</li>
<li><a href="#view_breakpoints_setprop">Set properties of breakpoints and watchpoints</a>
</li>
<li><a href="#view_breakpoints_disable">Disable and enable breakpoints and watchpoints</a>
</li>
<li><a href="#view_breakpoints_remove">Remove breakpoints and watchpoints</a></li>
</ul>
<hr>
<table>
<tr><td valign="top"><img src="image-lib/pointing.gif" alt="Note:"></td>
<td>While the <b>Breakpoints</b> view displays both breakpoints and watchpoints, the procedures for setting them differ somewhat. </td></tr>
</table>
<hr>
<h3><a name="view_breakpoints_add_break">Adding breakpoints</a></h3>
<p>You set breakpoints on an executable line of a program. If the breakpoint is enabled when you debug, the execution suspends <em>before</em> that line of code executes. </p>
<p>
To add a breakpoint:</p>
<ol>
<li>In the editor area, open the file that you want to add the breakpoint to (e.g. <tt>myProgram.c</tt>).
</li>
<li>Notice that the left edge of the <b>C/C++ Editor</b> has a blank space called a <i>marker bar</i>.
</li>
<li>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 <b>Add Breakpoint</b>:<p> <img src="./images/view_breakpoints_adding.jpg" alt="Breakpoints view; adding breakpoints"></p><p> A dot <img src="./images/icon_breakpoint_obj.gif" alt="Icon: Breakpoint object"> appears, indicating a breakpoint. A corresponding dot <img src="./images/icon_breakpoint_obj.gif" alt="Icon: Breakpoint object"> also appears in the <b>Breakpoints</b> view, along with the name of the file in which you set the breakpoint:</p><p> <img src="./images/view_breakpoints_added.jpg" alt="Breakpoints view; breakpoint added">
</p></li>
</ol>
<h3><a name="view_breakpoints_add_watch">Adding watchpoints</a></h3>
<p>To add a watchpoint:</p>
<ol>
<li>From the main menu, select <b>Run</b>--><b>Add C/C++ Watchpoint</b>. (If this option isn't available, select <b>Window</b>--><b>Customize Perspective</b>. In the left pane, select <b>Other</b>. Enable <b>C/C++ Debug</b>. Click <b>OK</b>.)
The <b>Add C/C++ Watchpoint</b> dialog appears:<p> <img src="./images/view_breakpoints_watch_add.jpg" alt="Breakpoints view; adding watchpoints">
</p></li>
<li>Enter an expression in the <b>Expression to watch</b> field. The expression may be anything that can be evaluated inside an <tt>if</tt> statement. (e.g. <tt>y==1</tt>)
</li>
<li>If you want the program to stop when it reads the watch expression, enable <b>Read</b>; to have the program stop when it writes the watch expression, enable <b>Write</b>. You must enable at least one.
</li>
<li>Click <b>OK</b>.
The watchpoint appears in the <b>Breakpoints</b> view list.</li>
</ol>
<h3><a name="view_breakpoints_setprop">Setting properties of breakpoints and watchpoints</a></h3>
<p>After you've set your breakpoint or watchpoint, the IDE unconditionally halts the program when:</p>
<ul>
<li>it reaches a line of code that the breakpoint is set on
<p>Or:
</p></li>
<li>the expression specified by the watchpoint becomes true.</li>
</ul>
<p>
To set the properties for a breakpoint or watchpoint:</p>
<ol>
<li>In the <b>Breakpoints</b> view, right-click the breakpoint or watchpoint and select <b>Properties</b>. (Or for breakpoints only, in the <b>C/C++ Editor</b>, right-click the breakpoint and select <b>Breakpoint Properties</b>.)
The <b>C/C++ Line Breakpoint Properties</b> or <b>C/C++ Watchpoint Properties</b> dialog appears (they're very similar). You need to fill in at least one field:<p> <img src="./images/view_breakpoints_prop.jpg" alt="Breakpoints view; setting breakpoint properties">
</p></li>
<li>In the <b>Condition</b> field, enter the Boolean expression to evaluate. The expression may be anything that can be evaluated inside an <tt>if</tt> statement (e.g. <tt>x &gt; y</tt> ). The default is TRUE.
</li>
<li>In the <b>Ignore Count</b> 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.
</li>
<li>Click <b>OK</b>.
When in debug mode, your program stops when it meets the conditions you've set for the breakpoint or watchpoint.</li>
</ol>
<h3><a name="view_breakpoints_disable">Disabling and enabling breakpoints and watchpoints</a></h3>
<p>You may wish to temporarily deactivate a breakpoint or watchpoint without losing the information it contains.</p>
<p>
To disable or enable a breakpoint or watchpoint:</p>
<table>
<tr><td valign="top"><img src="image-lib/onestep.gif" alt="=&gt;&gt;"></td>
<td>In the <b>Breakpoints</b> view, right-click the breakpoint or watchpoint and select <b>Disable</b> or <b>Enable</b> (Or for breakpoints only, right-click the breakpoint in the editor area and select <b>Disable Breakpoint</b> or <b>Enable Breakpoint</b>):<p><img src="./images/view_breakpoints_disable.jpg" alt="Breakpoints view; disabling breakpoints"></p></td></tr>
</table>
<p>To disable or enable all (or many) breakpoints or watchpoints:
</p>
<ol>
<li>In the <b>Breakpoints</b> view, use any of the following methods:
<ul>
<li>Select breakpoints and watchpoints while holding down the <font face="Helvetica"><b>Ctrl</b></font> key.
</li>
<li>Select a range of breakpoints and watchpoints while holding down the <font face="Helvetica"><b>Shift</b></font> key.
</li>
<li>From the main menu, select <b>Edit</b>--><b>Select All</b>.
</li>
<li>Right-click in the <b>Breakpoints</b> view and select <b>Select All</b>.
</li>
</ul>
</li>
<li>Right-click the highlighted breakpoints and watchpoints and select <b>Disable</b> or <b>Enable</b>.</li>
</ol>
<h3><a name="view_breakpoints_remove">Removing breakpoints and watchpoints</a></h3>
<p>
To remove one or more breakpoints and watchpoints:</p>
<table>
<tr><td valign="top"><img src="image-lib/onestep.gif" alt="=&gt;&gt;"></td>
<td>Follow the procedure described in <a href="#view_breakpoints_disable">"Disabling and enabling breakpoints and watchpoints"</a>, with the following exceptions:
<ul>
<li>Instead of selecting <b>Disable</b> or <b>Enable</b>, select <b>Remove</b>.
</li>
</ul></td></tr>
</table>
<p>
To remove all breakpoints and watchpoints:
</p>
<table>
<tr><td valign="top"><img src="image-lib/onestep.gif" alt="=&gt;&gt;"></td>
<td>In the <b>Breakpoints</b> view, right-click and select <b>Remove All</b>.</td></tr>
</table>
<h2><a name="view_expressions">Evaluating your expressions (Expressions view)</a></h2>
<p>The <b>Expressions</b> view lets you evaluate and examine the value of expressions:</p>
<p><img src="./images/view_expressions.jpg" alt="Expressions view">
</p>
<p>To evaluate an expression:</p>
<ol>
<li>From the menu, select <b>Run</b>--><b>Add C/C++ Expression</b>. (Or, right-click in the <b>C/C++ Editor</b> and select <b>Add C/C++ Expression</b>.)
The <b>Add Expression</b> dialog opens:<p> <img src="./images/view_expressions_add.jpg" alt="Expressions view; add expressions">
</p></li>
<li>Enter the expression you want to evaluate (e.g. <tt>(x-5)*3</tt> ).
</li>
<li>Click <b>OK</b>.
The expression and its value appear in the <b>Expressions</b> view. When the execution of a program is suspended, the IDE reevaluates all expressions and highlights the changed values.</li>
</ol>
<h2><a name="view_registers">Inspecting your registers (Registers view)</a></h2>
<p>The <b>Registers</b> view displays information about the registers in the currently selected stack frame. When the execution stops, the changed values are highlighted. The functionality of the <b>Registers</b> view is very similar to that of the <b>Variables</b> view; for more information, see the <a href="#view_variables">"Inspecting your variables (Variables view)"</a> section in this chapter.</p>
<p><img src="./images/view_registers.jpg" alt="Registers view"></p>
<p>You can also customize the colors in the <b>Registers</b> view and change the default value of the <b>Show Type Names</b> option.
</p>
<p>To access the <b>Registers</b> view customization dialog:</p>
<ol>
<li>From the main menu, select <b>Window</b>--><b>Preferences</b>.
</li>
<li>In the left pane, select <b>Debug</b>--><b>Registers View</b>.</li>
</ol>
<h2><a name="view_memory">Inspecting your process memory (Memory view)</a></h2>
<p>The <b>Memory</b> view lets you inspect and change your process memory. The view consists of four tabs that let you inspect multiple sections of memory:</p>
<p><img src="./images/view_memory.jpg" alt="Memory view">
</p>
<p></p>
<h3><a name="id41">Inspecting memory</a></h3>
<p>The <b>Memory</b> view supports the same addressing as the C language. You can address memory using expressions such as <tt>0x0847d3c</tt>, <tt>(&amp;y)+1024</tt>, and <tt>*ptr</tt>.
</p>
<p>To inspect your process memory:</p>
<ol>
<li>In the <b>Debug</b> view, select a process. Selecting a thread automatically selects the associated process.
</li>
<li>In the <b>Memory</b> view, select one of the four tabs labeled <b>Memory 1</b>, <b>Memory 2</b>, and so on.
</li>
<li>In the <b>Address</b> field, type the address and press <font face="Helvetica"><b>Enter</b></font>.</li>
</ol>
<h3><a name="id43">Changing memory</a></h3>
<p></p>
<hr>
<table>
<tr><td valign="top"><img src="image-lib/caution.gif" alt="Caution:"></td>
<td>Changing your process memory can make your program crash.</td></tr>
</table>
<hr>
<p>To change your process memory:</p>
<ol>
<li>Follow the procedure for inspecting your process memory.
</li>
<li>In the memory pane, type the new value for the memory. The <b>Memory</b> view works in "typeover" mode; use the arrow keys to jump from byte to byte:<p> <img src="./images/view_memory_change.jpg" alt="Memory view; changing">
</p></li>
<li>Click the <b>Save Changes</b> button<img src="./images/icon_memory_update.gif" alt="Icon: Save Changes">.
The changed memory appears in red.</li>
</ol>
<h3><a name="id45">Configuring output format</a></h3>
<p>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.</p>
<p>
To configure the output format:</p>
<ol>
<li>In the <b>Memory</b> view, select one of the four tabs labeled <b>Memory 1</b>, <b>Memory 2</b>, and so on.
</li>
<li>Right-click the pane and select any of <b>Format</b>, <b>Memory Unit Size</b>, or <b>Number of Columns</b>. Choose your desired output format:<p> <img src="./images/view_memory_configure.jpg" alt="Memory view; configure"></p><p> The output reflects your selection. Note that some output formats are best viewed in a nonproportional font such as Courier.
</p></li>
</ol>
<h3><a name="id47">Customizing the Memory view</a></h3>
<p>You can customize the <b>Memory</b> view to display in different colors and fonts. You can also customize some of its behavior. The customizations affect the entire <b>Memory</b> view.</p>
<p>
To access the <b>Memory</b> view customization dialog:</p>
<ol>
<li>From the menu, select <b>Window</b>--><b>Preferences</b>.
</li>
<li>In the left pane, select <b>Debug</b>--><b>Memory View</b>.
</li>
<li>You can now change the colors, font, and behavior of the <b>Memory</b> view. When you're done, click <b>Apply</b>, then <b>OK</b>.
</li>
</ol>
<h2><a name="view_console">Viewing your output (Console view)</a></h2>
<p>The <b>Console</b> view shows you the output of the execution of your program and lets you supply input to your program:</p>
<p><img src="./images/view_console.jpg" alt="Console view"></p>
<p></p>
<hr>
<table>
<tr><td valign="top"><img src="image-lib/pointing.gif" alt="Note:"></td>
<td>See also the <a href="#view_console_gdb">"Debugging with GDB (Console view)"</a> section, below.</td></tr>
</table>
<hr>
<p>
The console shows three different kinds of text, each in a different default color:</p>
<ul>
<li>standard output (blue)
</li>
<li>standard error (red)
</li>
<li>standard input (green)</li>
</ul>
<p>You can choose different colors for these kinds of text on the preferences pages.
</p>
<p>To access the <b>Console</b> view customization dialog:</p>
<ol>
<li>From the menu, select <b>Window</b>--><b>Preferences</b>.
</li>
<li>In the left pane, select <b>Debug</b>--><b>Console</b>.</li>
</ol>
<h2><a name="view_console_gdb">Debugging with GDB (Console view)</a></h2>
<p>The IDE lets you debug using a subset of the commands that the <tt>gdb</tt> utility offers:</p>
<p><img src="./images/view_console_gdb.jpg" alt="Console view; GDB"></p>
<p></p>
<hr>
<table>
<tr><td valign="top"><img src="image-lib/pointing.gif" alt="Note:"></td>
<td>See also the <a href="#view_console">"Viewing your output (Console view)"</a> section, above.</td></tr>
</table>
<hr>
</p>
<h3><a name="id51">Enabling the GDB Console view</a></h3>
<p>The <b>GDB Console</b> view is part of the regular <b>Console</b> view but isn't accessible until you toggle to it. Once you do, GDB output appears in place of the regular <b>Console</b> view output.
</p>
<p>To enable the <b>GDB Console</b> view:</p>
<ol>
<li>In the <b>Debug</b> view, select a debug session.
</li>
<li>In the <b>Debug</b> view, click the <b>Show Debugger Console on Target Selection</b> button <img src="./images/icon_debugger_console.gif" alt="Icon: Show Debugger Console on Target Selection">.
The <b>Console</b> view changes to the <b>GDB Debugger Console</b> view.</li>
</ol>
<h3><a name="id53">Using the GDB Console view</a></h3>
<p>The <b>GDB Console</b> view lets you bypass the IDE and talk directly to GDB; the IDE is unaware of anything done in the <b>GDB Console</b> view. Thus, items such as breakpoints that you set from the <b>GDB Console</b> view don't appear in the <b>C/C++ Editor</b>.</p>
<p></p>
<hr>
<table>
<tr><td valign="top"><img src="image-lib/pointing.gif" alt="Note:"></td>
<td>You can't use the <font face="Helvetica"><b>Tab</b></font> key for line completion because the commands are sent to GDB only when you press <tt>Enter</tt>.</td></tr>
</table>
<hr>
<p>To use the <b>GDB Console</b> view:</p>
<table>
<tr><td valign="top"><img src="image-lib/onestep.gif" alt="=&gt;&gt;"></td>
<td>In the <b>GDB Console</b> view, enter a command. For example, enter <tt>help</tt> to get a list of commands; <tt>nexti</tt> to step one instruction, proceeding through subroutine calls; <tt>nexti 3</tt> to step three:<p><img src="./images/view_console_gdb_using.jpg" alt="Console view; GDB; using"></p></td></tr>
</table>
</body>
</html>
<!--
/**********************************************************************
* Copyright (c) 2002,2003 QNX Software Systems Ltd. and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Common Public License v0.5
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/cpl-v05.html
*
* Contributors:
* QNX Software Systems - Initial API and implementation
***********************************************************************/
-->