Événements de débogage

Un événement de débogage est un incident dans le processus en cours de débogage qui amène le système à notifier le débogueur. Les événements de débogage incluent la création d’un processus, la création d’un thread, le chargement d’une bibliothèque de liens dynamiques (DLL), le déchargement d’une DLL, l’envoi d’une chaîne de sortie et la génération d’une exception.

Si un événement de débogage se produit alors qu’un débogueur en attend un, le système remplit la structure DEBUG_EVENT spécifiée par WaitForDebugEvent avec des informations décrivant l’événement.

Lorsque le système avertit le débogueur d’un événement de débogage, il suspend également tous les threads du processus affecté. Les threads ne reprennent pas l’exécution tant que le débogueur ne poursuit pas l’événement de débogage à l’aide de ContinueDebugEvent. Les événements de débogage suivants peuvent se produire pendant le débogage d’un processus.

Événement de débogage	Description
CREATE_PROCESS_DEBUG_EVENT	Généré chaque fois qu’un nouveau processus est créé dans un processus en cours de débogage ou chaque fois que le débogueur commence à déboguer un processus déjà actif. Le système génère cet événement de débogage avant que le processus ne commence à s’exécuter en mode utilisateur et avant que le système ne génère d’autres événements de débogage pour le nouveau processus. La structure DEBUG_EVENT contient une structure CREATE_PROCESS_DEBUG_INFO . Cette structure inclut un handle pour le nouveau processus, un handle pour le fichier image du processus, un handle pour le thread initial du processus et d’autres informations qui décrivent le nouveau processus. Le handle du processus a un accès PROCESS_VM_READ et PROCESS_VM_WRITE. Si un débogueur a ces types d’accès à un thread, il peut lire et écrire dans la mémoire du processus à l’aide des fonctions ReadProcessMemory et WriteProcessMemory . Si le système a précédemment signalé un événement EXIT_PROCESS_DEBUG_EVENT, le système ferme ce handle lorsque le débogueur appelle la fonction ContinueDebugEvent . Le handle du fichier image du processus a GENERIC_READ accès et est ouvert pour le partage en lecture. Le débogueur doit fermer ce handle lors du traitement de CREATE_PROCESS_DEBUG_EVENT. Le handle du thread initial du processus a THREAD_GET_CONTEXT, THREAD_SET_CONTEXT et THREAD_SUSPEND_RESUME accès au thread. Si un débogueur a ces types d’accès à un thread, il peut lire et écrire dans les registres du thread à l’aide des fonctions GetThreadContext et SetThreadContext , et peut suspendre et reprendre le thread à l’aide des fonctions SuspendThread et ResumeThread . Si le système a précédemment signalé un événement EXIT_PROCESS_DEBUG_EVENT, le système ferme ce handle lorsque le débogueur appelle la fonction ContinueDebugEvent .
CREATE_THREAD_DEBUG_EVENT	Généré chaque fois qu’un nouveau thread est créé dans un processus en cours de débogage ou chaque fois que le débogueur commence à déboguer un processus déjà actif. Cet événement de débogage est généré avant que le nouveau thread ne commence à s’exécuter en mode utilisateur. La structure DEBUG_EVENT contient une structure CREATE_THREAD_DEBUG_INFO . Cette structure inclut un handle pour le nouveau thread et l’adresse de départ du thread. Le handle a un accès THREAD_GET_CONTEXT, THREAD_SET_CONTEXT et THREAD_SUSPEND_RESUME au thread. Si un débogueur a ces types d’accès à un thread, il peut lire et écrire dans les registres du thread à l’aide des fonctions GetThreadContext et SetThreadContext , et peut suspendre et reprendre le thread à l’aide des fonctions SuspendThread et ResumeThread . Si le système a précédemment signalé un événement EXIT_THREAD_DEBUG_EVENT, le système ferme le handle au nouveau thread lorsque le débogueur appelle la fonction ContinueDebugEvent .
EXCEPTION_DEBUG_EVENT	Généré chaque fois qu’une exception se produit dans le processus en cours de débogage. Les exceptions possibles incluent la tentative d’accès à la mémoire inaccessible, l’exécution d’instructions de point d’arrêt, la tentative de division par zéro ou toute autre exception notée dans Gestion structurée des exceptions. La structure DEBUG_EVENT contient une structure EXCEPTION_DEBUG_INFO . Cette structure décrit l’exception qui a provoqué l’événement de débogage. Outre les conditions d’exception standard, un code d’exception supplémentaire peut se produire pendant le débogage du processus de console. Le système génère un code d’exception DBG_CONTROL_C lorsque CTRL+C est entré dans un processus console qui gère les signaux CTRL+C et est en cours de débogage. Ce code d’exception n’est pas destiné à être géré par les applications. Une application ne doit jamais utiliser un gestionnaire d’exceptions pour y faire face. Il est déclenché uniquement pour le bénéfice du débogueur et n’est utilisé que lorsqu’un débogueur est attaché au processus de console. Si un processus n’est pas débogué ou si le débogueur transmet l’exception DBG_CONTROL_C non gérée (via la commande gn), la liste des fonctions de gestionnaire de l’application est recherchée, comme documenté pour la fonction SetConsoleCtrlHandler . Si le débogueur gère l’exception DBG_CONTROL_C (via la commande gh), une application ne remarquera pas la touche CTRL+C, sauf dans le code suivant. while ((inputChar = getchar()) != EOF) ... Par conséquent, le débogueur ne peut pas être utilisé pour empêcher la fin de l’attente de lecture dans ce code.
EXIT_PROCESS_DEBUG_EVENT	Généré chaque fois que le dernier thread d’un processus débogué se termine. Cet événement de débogage se produit immédiatement après que le système a déchargé les DLL du processus et mis à jour le code de sortie du processus. La structure DEBUG_EVENT contient une structure EXIT_PROCESS_DEBUG_INFO qui spécifie le code de sortie. Le débogueur libère toutes les structures internes associées au processus à la réception de cet événement de débogage. Le système ferme le handle du débogueur au processus de sortie et à tous les threads du processus. Le débogueur ne doit pas fermer ces handles. La partie en mode noyau de l’arrêt du processus ne peut pas être terminée tant que le débogueur qui reçoit cet événement appelle ContinueDebugEvent. En attendant, les handles de processus sont ouverts et l’espace d’adressage virtuel n’est pas libéré, de sorte que le débogueur peut examiner le processus enfant. Pour recevoir une notification lorsque la partie en mode noyau de l’arrêt du processus est terminée, dupliquez le handle retourné avec CREATE_PROCESS_DEBUG_EVENT, appelez ContinueDebugEvent, puis attendez que le handle de processus en double soit signalé.
EXIT_THREAD_DEBUG_EVENT	Généré chaque fois qu’un thread faisant partie d’un processus débogué se ferme. Le système génère cet événement de débogage immédiatement après avoir mis à jour le code de sortie du thread. La structure DEBUG_EVENT contient une structure EXIT_THREAD_DEBUG_INFO qui spécifie le code de sortie. Cet événement de débogage ne se produit pas si le thread sortant est le dernier thread d’un processus. Dans ce cas, l’événement de débogage EXIT_PROCESS_DEBUG_EVENT se produit à la place. Le débogueur libère toutes les structures internes associées au thread à la réception de cet événement de débogage. Le système ferme le handle du débogueur au thread sortant. Le débogueur ne doit pas fermer ce handle.
LOAD_DLL_DEBUG_EVENT	Généré chaque fois qu’un processus débogué charge une DLL. Cet événement de débogage se produit lorsque le chargeur système résout les liens vers une DLL ou lorsque le processus débogué utilise la fonction LoadLibrary . Cet événement de débogage se produit uniquement la première fois que le système attache une DLL à l’espace d’adressage virtuel d’un processus. La structure DEBUG_EVENT contient une structure LOAD_DLL_DEBUG_INFO . Cette structure inclut un handle pour la DLL nouvellement chargée, l’adresse de base de la DLL et d’autres informations qui décrivent la DLL. Le débogueur doit fermer le handle au handle DLL lors du traitement LOAD_DLL_DEBUG_EVENT. En règle générale, un débogueur charge une table de symboles associée à la DLL à la réception de cet événement de débogage.
OUTPUT_DEBUG_STRING_EVENT	Généré lorsqu’un processus en cours de débogage utilise le Fonction OutputDebugString . La structure DEBUG_EVENT contient une structure OUTPUT_DEBUG_STRING_INFO . Cette structure spécifie l’adresse, la longueur et le format de la chaîne de débogage.
UNLOAD_DLL_DEBUG_EVENT	Généré chaque fois qu’un processus débogué décharge une DLL à l’aide de la fonction FreeLibrary . Cet événement de débogage se produit uniquement la dernière fois qu’une DLL est déchargée de l’espace d’adressage d’un processus (autrement dit, lorsque le nombre d’utilisation de la DLL est égal à zéro). La structure DEBUG_EVENT contient une structure UNLOAD_DLL_DEBUG_INFO . Cette structure spécifie l’adresse de base de la DLL dans l’espace d’adressage du processus qui décharge la DLL. En règle générale, un débogueur décharge une table de symboles associée à la DLL lors de la réception de cet événement de débogage. Lorsqu’un processus se termine, le système décharge automatiquement les DLL du processus, mais ne génère pas d’événement de débogage UNLOAD_DLL_DEBUG_EVENT.
RIP_EVENT	Généré chaque fois qu’un processus en cours de débogage meurt en dehors du contrôle du débogueur système. La structure DEBUG_EVENT contient une structure RIP_INFO . Cette structure spécifie l’erreur et le type d’erreur.