Debugging a User-Mode Process Using CDB

You can use CDB to attach to a running process or to spawn and attach to new process.

Attaching to a Running Process

Command Prompt

In a Command Prompt window, you can attach to a running process when you launch CDB. Use one of the following commands:

• cdb -p ProcessID
• cdb -pn ProcessName

where ProcessID is the Process ID of a running process or ProcessName is the name of a running process.

For more information about the command-line syntax, see CDB Command-Line Options.

CDB Command Window

If the debugger is already debugging one or more processes, you can attach to a running process by using the .attach (Attach to Process) command.

The debugger always starts multiple target processes simultaneously, unless some of their threads are frozen or suspended.

If the .attach command is successful, the debugger attaches to the specified process the next time that the debugger issues an execution command. If you use this command several times in a row, execution has to be requested by the debugger as many times as you use this command.

Attaching to a Running Process Noninvasively

If you want to debug a running process and interfere only minimally in its execution, you should debug the process noninvasively.

Command Prompt

To noninvasively debug a running process from the CDB command line, specify the -pv option, the -p option, and the process ID, in the following syntax.

cdb -pv -p ProcessID

Or, to noninvasively debug a running process by specifying the process name, use the following syntax instead.

cdb -pv -pn ProcessName

There are several other useful command-line options. For more information about the command-line syntax, see CDB Command-Line Options.

CDB Command Window

If the debugger is already active, you can noninvasively debug a running process by entering the .attach -v (Attach to Process) command.

You can use the .attach command if the debugger is already debugging one or more processes invasively.

If the .attach -v command is successful, the debugger debugs the specified process the next time that the debugger issues an execution command. Because execution is not permitted during noninvasive debugging, the debugger cannot noninvasively debug more than one process at a time. This restriction also means that using the .attach -v command might make an existing invasive debugging session less useful.

Spawning a New Process

CDB can start a user-mode application and then debug the application. The application is specified by name. The debugger can also automatically attach to child processes (additional processes that the original target process started).

Processes that the debugger creates (also known as spawned processes) behave slightly differently than processes that the debugger does not create.

Instead of using the standard heap API, processes that the debugger creates use a special debug heap. You can force a spawned process to use the standard heap instead of the debug heap by using the _NO_DEBUG_HEAP environment variable or the -hd command-line option.

Also, because the target application is a child process of the debugger, it inherits the debugger's permissions. This permission might enable the target application to perform certain actions that it could not perform otherwise. For example, the target application might be able to affect protected processes.

In a Command Prompt window, you can spawn a new process when you launch CDB. Enter the following command.

cdb [-o] ProgramName [Arguments]

The -o option causes the debugger to attach to child processes. There are several other useful command-line options. For more information about the command-line syntax, see CDB Command-Line Options.

If the debugger is already debugging one or more processes, you can create a new process by entering the .create (Create Process) command.

The debugger will always start multiple target processes simultaneously, unless some of their threads are frozen or suspended.

If the .create command is successful, the debugger creates the specified process the next time that the debugger issues an execution command. If you use this command several times in a row, execution has to be requested by the debugger as many times as you use this command.

You can control the application's starting directory by using the .createdir (Set Created Process Directory) command before .create. You can use the .createdir -I command or the -noinh command-line option to control whether the target application inherits the debugger's handles.

You can activate or deactivate the debugging of child processes by using the .childdbg (Debug Child Processes) command.

Reattaching to a Process

If the debugger stops responding or freezes, you can attach a new debugger to the target process. For more information about how to attach a debugger in this situation, see Reattaching to the Target Application.