DebugActiveProcess, fonction (debugapi.h)

Article
02/28/2024

Permet à un débogueur de s’associer à un processus actif et de le déboguer.

Syntaxe

BOOL DebugActiveProcess(
  [in] DWORD dwProcessId
);

Paramètres

[in] dwProcessId

Identificateur du processus à déboguer. Le débogueur se voit accorder l’accès débogage au processus comme s’il avait créé le processus avec l’indicateur DEBUG_ONLY_THIS_PROCESS . Pour plus d’informations, consultez la section Remarques de cette rubrique.

Valeur retournée

Si la fonction réussit, la valeur de retour est différente de zéro.

Si la fonction échoue, la valeur de retour est zéro (0). Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Remarques

Pour arrêter le débogage du processus, vous devez quitter le processus ou appeler la fonction DebugActiveProcessStop . Quitter le débogueur quitte également le processus, sauf si vous utilisez la fonction DebugSetProcessKillOnExit .

Le débogueur doit avoir un accès approprié au processus cible, et il doit être en mesure d’ouvrir le processus pour PROCESS_ALL_ACCESS. DebugActiveProcess peut échouer si le processus cible est créé avec un descripteur de sécurité qui accorde au débogueur un accès inférieur à un accès total. Si le processus de débogage a le privilège SE_DEBUG_NAME accordé et activé, il peut déboguer n’importe quel processus.

Une fois que le système a vérifié l’identificateur du processus et déterminé qu’une pièce jointe de débogage valide est effectuée, la fonction retourne TRUE. Ensuite, le débogueur doit attendre les événements de débogage à l’aide de la fonction WaitForDebugEvent . Le système suspend tous les threads du processus et envoie les événements de débogueur qui représentent l’état actuel du processus.

Le système envoie au débogueur un seul événement de débogage CREATE_PROCESS_DEBUG_EVENT qui représente le processus spécifié par le paramètre dwProcessId . Le membre lpStartAddress de la structure CREATE_PROCESS_DEBUG_INFO est NULL.

Pour chaque thread qui fait actuellement partie du processus, le système envoie un événement de débogage CREATE_THREAD_DEBUG_EVENT . Le membre lpStartAddress de la structure CREATE_THREAD_DEBUG_INFO est NULL.

Pour chaque bibliothèque de liens dynamiques (DLL) actuellement chargée dans l’espace d’adressage du processus cible, le système envoie un événement de débogage LOAD_DLL_DEBUG_EVENT . Le système s’organise pour que le premier thread du processus exécute une instruction de point d’arrêt après sa reprise. La poursuite de ce thread l’amène à revenir à la même chose qu’avant l’attachement du débogueur.

Une fois cette opération terminée, le système reprend tous les threads du processus. Lorsque le premier thread du processus reprend, il exécute une instruction de point d’arrêt qui provoque l’envoi d’un événement de débogage EXCEPTION_DEBUG_EVENT au débogueur. Tous les événements de débogage futurs sont envoyés au débogueur à l’aide du mécanisme et des règles normaux.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows XP [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	debugapi.h (inclure Windows.h)
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll