Enables a debugger to attach to an active process and debug it.

Syntax

BOOL DebugActiveProcess(  [in] DWORD dwProcessId);

Parameters

[in] dwProcessId

The identifier for the process to be debugged. The debugger is granted debugging access to the process asif it created the process with theDEBUG_ONLY_THIS_PROCESS flag. For more information,see the Remarks section of this topic.

Return value

If the function succeeds, the return value is nonzero.

If the function fails, the return value is 0 (zero). To get extended error information, callGetLastError.

Remarks

To stop debugging the process, you must exit the process or call theDebugActiveProcessStop function. Exiting thedebugger also exits the process unless you use theDebugSetProcessKillOnExit function.

The debugger must have appropriate access to the target process, and it must be able to open the process forPROCESS_ALL_ACCESS.DebugActiveProcess can fail if the target processis created with a security descriptor that grants the debugger anything less than full access. If the debuggingprocess has theSE_DEBUG_NAME privilege granted and enabled, it can debug anyprocess.

After the system checks the process identifier and determines that a valid debugging attachment is being made,the function returnsTRUE. Then the debugger is expected to wait for debugging events byusing theWaitForDebugEvent function. The systemsuspends all threads in the process, and sends the debugger events that represents the current state of theprocess.

The system sends the debugger a singleCREATE_PROCESS_DEBUG_EVENT debugging eventthat represents the process specified by thedwProcessId parameter. ThelpStartAddress member of theCREATE_PROCESS_DEBUG_INFO structure isNULL.

For each thread that is currently part of the process, the system sends aCREATE_THREAD_DEBUG_EVENT debugging event. ThelpStartAddressmember of theCREATE_THREAD_DEBUG_INFOstructure isNULL.

For each dynamic-link library (DLL) that is currently loaded into the address space of the target process, thesystem sends aLOAD_DLL_DEBUG_EVENT debugging event. The system arranges for the firstthread in the process to execute a breakpoint instruction after it resumes. Continuing this thread causes it toreturn to doing the same thing as before the debugger is attached.

After all of this is done, the system resumes all threads in the process. When the first thread in the processresumes, it executes a breakpoint instruction that causes anEXCEPTION_DEBUG_EVENTdebugging event to be sent to the debugger. All future debugging events are sent to the debugger by using thenormal mechanism and rules.

Requirements

See also

CREATE_PROCESS_DEBUG_INFO

CREATE_THREAD_DEBUG_INFO

CreateProcess

DebugActiveProcessStop

Debugging Functions

Debugging a Running Process

WaitForDebugEvent