Live User-Mode Targets

The methods for creating and attaching to processes that are listed in this topic can be used for the local computer and for a remote computer running a process server.

A user-mode process can be created using Create Process or CreateProcess2, which execute a given command to create a process. The method AttachProcess can be used to attach the debugger engine to an existing user-mode process. CreateProcessAndAttach and CreateProcessAndAttach2 create a new user-mode process and attach to it or another user-mode process on the same computer. The Request operations DEBUG_REQUEST_GET_ADDITIONAL_CREATE_OPTIONS, DEBUG_REQUEST_SET_ADDITIONAL_CREATE_OPTIONS, and DEBUG_REQUEST_SET_LOCAL_IMPLICIT_COMMAND_LINE can be used to set some of the default options for creating processes.

Note  The engine doesn't completely attach to the process until the WaitForEvent method has been called. Only after the process has generated an event — for example, the process creation event — does it become available in the debugger session. See Debugging Session and Execution Model for more details.

The method GetRunningProcessSystemIds will return the process IDs of all the running processes on the computer. The process ID of a particular program can be found using GetRunningProcessSystemIdByExecutableName. Given a process ID, a description of the process is returned by GetRunningProcessDescription.

Process Options

The process options determine part of the engine's behavior when attached to a user-mode process, including whether or not the debugger engine will automatically attach to child processes created by the target process and what the engine does with the target processes when it exits. See DEBUG_PROCESS_XXX for a description of the process options.

The process options can be queried using GetProcessOptions. They can be changed using AddProcessOptions, RemoveProcessOptions, and SetProcessOptions.

Disconnecting from Processes

There are three different ways for the engine to disconnect from a process.

1. Detach. Resume all the threads in the process so that it will continue running, no longer being debugged. DetachCurrentProcess will detach the engine from the current process and DetachProcesses will detach the engine from all processes. Not all targets support detaching. The Request operation DEBUG_REQUEST_TARGET_CAN_DETACH can be used to check if the target supports detaching.
2. Terminate. Attempt to kill the process. TerminateCurrentProcess will terminate the current process and TerminateProcesses will terminate all processes in the debugger session.
3. Abandon. Remove the process from the list of processes being debugged. The operating system will still consider the process as being debugged and it will remain suspended until another debugger attaches to it or it is killed. AbandonCurrentProcess will abandon the current process.