DebugActiveProcess

	BOOL DebugActiveProcess(idProcess)
	DWORD idProcess;	/* process to be debugged	*/

The DebugActiveProcess function allows a debugger to attach to an active process and debug the process.

Parameters

idProcess

Identifies the process to be debugged. The debugger gets debug access to the process as if it had created the process with the DEBUG_ONLY_THIS_PROCESS creation flag.

Return Value

The return value is TRUE if the function was successful, or FALSE if an error occurred. Use the GetLastError function to obtain extended error information.

Comments

The debugger must have appropriate access to the target process — it must be able to open the process for PROCESS_ALL_ACCESS. For Dos/Win32 this is always true if the process ID is a valid process ID. For NT/Win32 this function can fail if the target process was created with a security descriptor that denies the debugger appropriate access.

Once the system checks the process ID and determines that a valid debug attachment is being made, this function returns TRUE. The debugger is then expected to wait for debug events by using the WaitForDebugEvent function. The system will suspend all threads in the process and send the debugger events representing the current state of the process.

The system will send the debugger a single CREATE_PROCESS_DEBUG_EVENT representing the process specified by idProcess. The lpStartAddress member of the CREATE_PROCESS_DEBUG_INFO structure is NULL.

For each thread currently part of the process, the system will send a CREATE_THREAD_DEBUG_EVENT. The lpStartAddress member of the CREATE_THREAD_DEBUG_INFO structure is NULL.

For each DLL currently loaded into the address space of the target process, the system will send a LOAD_DLL_DEBUG_EVENT. The system will arrange for the first thread in the process to execute a breakpoint instruction after it is resumed. Continuing this thread causes the thread to return to whatever it was doing prior to when the debugger was attached.

After all of this has been done, the system resumes all threads within the process. When the first thread in the process resumes, it will execute a breakpoint instruction causing an EXCEPTION_DEBUG_EVENT to be sent to the debugger. All future debug events are sent to the debugger using the normal mechanism and rules.