Controlling the Target
While you are debugging a target application in user mode or a target computer in kernel mode, the target can be running or stopped.
When the debugger connects to a kernel-mode target, the debugger leaves the target running, unless you use the -b command-line option, the target system has stopped responding (that is, crashed), or the target system is still stopped because of an earlier kernel debugging action.
When the debugger starts or connects to a user-mode target, the debugger immediately stops the target, unless you use the -g command-line option. For more information, see Initial Breakpoint.
When the Target is Running
When the target is running, most debugger actions are unavailable.
If you want to stop a running target, you can issue a Break command. This command causes the debugger to break into the target. That is, the debugger stops the target and all control is given to the debugger. The application might not break immediately. For example, if all threads are currently executing system code, or are in a wait operation, the application breaks only after control has returned to the application's code.
If a running target encounters an exception, if certain events occur, if a breakpoint is hit, or if the application closes normally, the target breaks into the debugger. This action stops the target and gives all control to the debugger. A message appears in the Debugger Command window and describes the error, event, or breakpoint.
When the Target is Stopped
To start or control the target's execution, you can do the following:
To cause the application to begin running, issue the Go command.
To step through the application one instruction at a time, use the Step Into or Step Over commands. If a function call occurs, Step Into enters the function and continues stepping through each instruction. Step Over treats the function call as a single step. When the debugger is in Assembly Mode, stepping occurs one machine instruction at a time. When the debugger is in Source Mode, stepping occurs one source line at a time.
To finish the current function and stop when the return occurs, use the Step Out or Trace and Watch commands. The Step Out command continues until the current function ends. Trace and Watch continues until the current function ends and also displays a summary of the function's calls. However, you must issue the Trace and Watch command on the first instruction of the function in question.
If an exception occurs, you can use the Go with Exception Handled and Go with Exception Not Handled commands to resume execution and control the status of the exception. (For more information about exceptions, see Controlling Exceptions and Events.)
(WinDbg only) If you select a line in the Disassembly window or a Source window and then use the Run to Cursor command, the program runs until it encounters the selected line.
(User Mode only) To close the target application and restart it from the beginning, use the Restart command. You can use this command only with a process that the debugger created. After the process is restarted, it immediately breaks into the debugger.
(WinDbg only) To close the target application and clear the debugger, use the Stop Debugging command. This command enables you to start debugging a different target.
Command Forms
Most commands for starting or controlling the target's execution exist as text commands, menu commands, toolbar buttons, and shortcut keys. As basic text commands, you can use these commands in CDB, KD, or WinDbg. (The text form of the commands frequently supports additional options, such as changing the location of the program counter or executing a fixed number of instructions.) You can use the menu commands, toolbar buttons, and shortcut keys in WinDbg.
You can use the commands in the following forms.
| Command | WinDbg command | WinDbg shortcut keys | Effect |
|---|---|---|---|
Debug | Run to Cursor |
F7 CTRL + F10 |
(WinDbg only) Executes until it reaches the line that the cursor marks. |
|
Debug | Stop Debugging |
SHIFT + F5 |
Stops all debugging and closes the target. |
|
(CDB/KD only) CTRL+C |
Debug | Break |
CTRL + BREAK |
Execution stops, and the debugger breaks into the target. |
Debug | Restart |
CTRL + SHIFT + F5 |
(User mode only) Restarts the target application. |
|
Debug | Go |
F5 |
Target executes freely. |
|
Resumes execution after a conditional breakpoint. |
|||
Debug | Go Handled Exception |
Same as g (Go), except that the current exception is treated as handled. |
||
Debug | Go Unhandled Exception |
Same as g (Go), except that the current exception is treated as unhandled. |
||
Debug | Step Out |
SHIFT + F11 |
Target executes until the current function is complete. |
|
Debug | Step Over |
F10 |
Target executes one instruction. If this instruction is a function call, that function is executed as a single step. |
|
Target executes until it reaches the specified address. All steps in this function are displayed (but steps in called functions are not). |
|||
Target executes until the next call instruction. If the current instruction is a call instruction, this call is executed completely and execution continues until the next call. |
|||
Target executes until it reaches a call instruction or a return instruction. |
|||
Target executes until it reaches any kind of branching instruction, including conditional or unconditional branches, calls, returns, and system calls. |
|||
Target executes until it reaches a return instruction. |
|||
Debug | Step Into |
F11 F8 |
Target executes one instruction. If this instruction is a function call, debugger traces into that call. |
|
Target executes until it reaches the specified address. All steps in this function and called functions are displayed. |
|||
(All modes, except kernel mode, only on x86-based systems) Target executes until it reaches the next branch instruction. |
|||
Target executes until the next call instruction. If the current instruction is a call instruction, the instruction is traced into until a new call is reached. |
|||
Target executes until it reaches a call instruction or return instruction. If the current instruction is a call instruction or return instruction, the instruction is traced into until a new call or return is reached. |
|||
Target executes until it reaches any kind of branching instruction, including conditional or unconditional branches, calls, returns, and system calls. If the current instruction is a branching instruction, the instruction is traced into until a new branching instruction is reached. |
|||
Target executes until it reaches a return instruction. If the current instruction is a return instruction, the instruction is traced into until a new return is reached. |
|||
Target executes until the completion of the whole specified function. Statistics are then displayed. |
For more information about how to restart the target computer, see Crashing and Rebooting the Target Computer.
Command-Line Options
If you do not want the application to stop immediately when it starts or loads, use CDB or WinDbg together with the -g command-line option. For more information about this situation, see Initial Breakpoint.
CDB and WinDbg also support the -G command-line option. This option causes the debugging session to end if the application completes properly.
The following command tries to run the application from start to finish, and the debugger prompt appears only if an error occurs.
cdb -g -G ApplicationName
You can use the -pt command-line option to set the break time-out. There are certain problems that can make the target unable to communicate with the debugger. If a break command is issued and the debugger cannot break into the target after this time, the debugger displays a "Break-in timed out" message.
At this point, the debugger stops trying to break into the target. Instead, the debugger pauses the target and enables you to examine (but not control) the target application.
The default time-out is 30 seconds.