DebugActiveProcess-Funktion (debugapi.h)

Artikel
08/23/2023

Ermöglicht einem Debugger, einen aktiven Prozess anzufügen und ihn zu debuggen.

Syntax

BOOL DebugActiveProcess(
  [in] DWORD dwProcessId
);

Parameter

[in] dwProcessId

Der Bezeichner für den zu debuggenden Prozess. Dem Debugger wird Debugzugriff auf den Prozess gewährt, als ob er den Prozess mit dem DEBUG_ONLY_THIS_PROCESS-Flag erstellt hätte. Weitere Informationen finden Sie in diesem Thema im Abschnitt „Hinweise“.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null.

Wenn die Funktion fehlerhaft ist, ist der Rückgabewert 0 (null). Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Um das Debuggen des Prozesses zu beenden, müssen Sie den Prozess beenden oder die DebugActiveProcessStop-Funktion aufrufen. Wenn Sie den Debugger beenden, wird auch der Prozess beendet, es sei denn, Sie verwenden die DebugSetProcessKillOnExit-Funktion .

Der Debugger muss über entsprechenden Zugriff auf den Zielprozess verfügen und in der Lage sein, den Prozess für PROCESS_ALL_ACCESS zu öffnen. DebugActiveProcess kann fehlschlagen, wenn der Zielprozess mit einem Sicherheitsdeskriptor erstellt wird, der dem Debugger nur Vollzugriff gewährt. Wenn dem Debugprozess die SE_DEBUG_NAME Berechtigung gewährt und aktiviert ist, kann er jeden Prozess debuggen.

Nachdem das System den Prozessbezeichner überprüft und festgestellt hat, dass eine gültige Debuganlage erstellt wird, gibt die Funktion TRUE zurück. Anschließend wird erwartet, dass der Debugger mithilfe der WaitForDebugEvent-Funktion auf Debugereignisse wartet. Das System hält alle Threads im Prozess an und sendet die Debuggerereignisse, die den aktuellen Status des Prozesses darstellen.

Das System sendet dem Debugger ein einzelnes CREATE_PROCESS_DEBUG_EVENT Debugereignis, das den durch den dwProcessId-Parameter angegebenen Prozess darstellt. Das lpStartAddress-Element der CREATE_PROCESS_DEBUG_INFO-Struktur ist NULL.

Für jeden Thread, der derzeit Teil des Prozesses ist, sendet das System ein CREATE_THREAD_DEBUG_EVENT Debugereignis. Das lpStartAddress-Element der CREATE_THREAD_DEBUG_INFO-Struktur ist NULL.

Für jede DLL (Dynamic Link Library), die derzeit in den Adressraum des Zielprozesses geladen wird, sendet das System ein LOAD_DLL_DEBUG_EVENT Debugereignis. Das System sorgt dafür, dass der erste Thread im Prozess eine Haltepunktanweisung ausführt, nachdem er fortgesetzt wurde. Wenn Dieser Thread fortgesetzt wird, wird er wieder zum gleichen Vorgang wie vor dem Anfügen des Debuggers zurückkehren.

Nachdem all dies erledigt ist, setzt das System alle Threads im Prozess fort. Wenn der erste Thread im Prozess fortgesetzt wird, wird eine Haltepunktanweisung ausgeführt, die dazu führt, dass ein EXCEPTION_DEBUG_EVENT Debugereignis an den Debugger gesendet wird. Alle zukünftigen Debugereignisse werden mithilfe des normalen Mechanismus und der normalen Regeln an den Debugger gesendet.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	debugapi.h (einschließen von Windows.h)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll