Depuração de eventos

Um evento de depuração é um incidente no processo que está sendo depurado que faz com que o sistema notifique o depurador. Os eventos de depuração incluem a criação de um processo, a criação de um thread, o carregamento de uma DLL (biblioteca de vínculo dinâmico), o descarregamento de uma DLL, o envio de uma cadeia de caracteres de saída e a geração de uma exceção.

Se um evento de depuração ocorrer enquanto um depurador estiver aguardando um, o sistema preencherá a estrutura DEBUG_EVENT especificada por WaitForDebugEvent com informações que descrevem o evento.

Quando o sistema notifica o depurador de um evento de depuração, ele também suspende todos os threads no processo afetado. Os threads não retomam a execução até que o depurador continue o evento de depuração usando ContinueDebugEvent. Os seguintes eventos de depuração podem ocorrer enquanto um processo está sendo depurado.

Evento de depuração	Descrição
CREATE_PROCESS_DEBUG_EVENT	Gerado sempre que um novo processo é criado em um processo que está sendo depurado ou sempre que o depurador começa a depurar um processo já ativo. O sistema gera esse evento de depuração antes que o processo comece a ser executado no modo de usuário e antes que o sistema gere quaisquer outros eventos de depuração para o novo processo. A estrutura DEBUG_EVENT contém uma estrutura CREATE_PROCESS_DEBUG_INFO. Essa estrutura inclui um identificador para o novo processo, um identificador para o arquivo de imagem do processo, um identificador para o thread inicial do processo e outras informações que descrevem o novo processo. O identificador do processo tem acesso PROCESS_VM_READ e PROCESS_VM_WRITE. Se um depurador tiver esses tipos de acesso a um thread, ele poderá ler e gravar na memória do processo usando as funções ReadProcessMemory e WriteProcessMemory. Se o sistema relatou anteriormente um evento EXIT_PROCESS_DEBUG_EVENT, o sistema fechará esse identificador quando o depurador chamar a função ContinueDebugEvent. O identificador do arquivo de imagem do processo tem acesso GENERIC_READ e é aberto para compartilhamento de leitura. O depurador deve fechar esse identificador durante o processamento CREATE_PROCESS_DEBUG_EVENT. O identificador para o thread inicial do processo tem acesso THREAD_GET_CONTEXT, THREAD_SET_CONTEXT e THREAD_SUSPEND_RESUME ao thread. Se um depurador tiver esses tipos de acesso a um thread, ele poderá ler e gravar nos registradores do thread usando as funções GetThreadContext e SetThreadContext e poderá suspender e retomar o thread usando as funções SuspendThread e ResumeThread. Se o sistema relatou anteriormente um evento EXIT_PROCESS_DEBUG_EVENT, o sistema fechará esse identificador quando o depurador chamar a função ContinueDebugEvent.
CREATE_THREAD_DEBUG_EVENT	Gerado sempre que um novo thread é criado em um processo que está sendo depurado ou sempre que o depurador começa a depurar um processo já ativo. Esse evento de depuração é gerado antes que o novo thread comece a ser executado no modo de usuário. A estrutura DEBUG_EVENT contém uma estrutura CREATE_THREAD_DEBUG_INFO. Essa estrutura inclui um identificador para o novo thread e o endereço inicial do thread. O identificador tem acesso THREAD_GET_CONTEXT, THREAD_SET_CONTEXT e THREAD_SUSPEND_RESUME ao thread. Se um depurador tiver esses tipos de acesso a um thread, ele poderá ler e gravar nos registradores do thread usando as funções GetThreadContext e SetThreadContext e poderá suspender e retomar o thread usando as funções SuspendThread e ResumeThread. Se o sistema relatou anteriormente um evento EXIT_THREAD_DEBUG_EVENT, o sistema fechará o identificador para o novo thread quando o depurador chamar a função ContinueDebugEvent.
EXCEPTION_DEBUG_EVENT	Gerado sempre que ocorre uma exceção no processo que está sendo depurado. As exceções possíveis incluem a tentativa de acessar memória inacessível, a execução de instruções de ponto de interrupção, a tentativa de dividir por zero ou qualquer outra exceção observada em Tratamento de exceções estruturadas. A estrutura DEBUG_EVENT contém uma estrutura EXCEPTION_DEBUG_INFO. Essa estrutura descreve a exceção que causou o evento de depuração. Além das condições de exceção padrão, um código de exceção adicional pode ocorrer durante a depuração do processo do console. O sistema gera um código de exceção DBG_CONTROL_C quando CTRL+C é inserido em um processo de console que manipula sinais CTRL+C e está sendo depurado. Esse código de exceção não deve ser manipulado por aplicativos. Um aplicativo nunca deve usar um manipulador de exceção para lidar com ele. Ele é gerado apenas para o benefício do depurador e só é usado quando um depurador é anexado ao processo do console. Se um processo não estiver sendo depurado ou se o depurador passar a exceção DBG_CONTROL_C sem tratamento (por meio do comando gn), a lista de funções do manipulador do aplicativo será pesquisada, conforme documentado para a função SetConsoleCtrlHandler. Se o depurador manipular a exceção DBG_CONTROL_C (por meio do comando gh), um aplicativo não notará a CTRL+C, exceto em código como este. while ((inputChar = getchar()) != EOF) ... Assim, o depurador não pode ser usado para impedir que a espera de leitura nesse código seja encerrada.
EXIT_PROCESS_DEBUG_EVENT	Gerado sempre que o último thread de um processo que está sendo depurado é encerrado. Esse evento de depuração ocorre imediatamente após o sistema descarregar as DLLs do processo e atualizar o código de saída do processo. A estrutura DEBUG_EVENT contém uma estrutura EXIT_PROCESS_DEBUG_INFO que especifica o código de saída. O depurador desaloca quaisquer estruturas internas associadas ao processo ao receber esse evento de depuração. O sistema fecha o identificador do depurador para o processo de saída e todos os threads do processo. O depurador não deve fechar essas alças. A parte do modo kernel do desligamento do processo não pode ser concluída até que o depurador que recebe esse evento chame ContinueDebugEvent. Até lá, os identificadores de processo estão abertos e o espaço de endereço virtual não é liberado, para que o depurador possa examinar o processo filho. Para receber notificação quando a parte do modo kernel do desligamento do processo estiver concluída, duplique o identificador retornado com CREATE_PROCESS_DEBUG_EVENT, chame ContinueDebugEvent e aguarde até que o identificador de processo duplicado seja sinalizado.
EXIT_THREAD_DEBUG_EVENT	Gerado sempre que um thread que faz parte de um processo que está sendo depurado é encerrado. O sistema gera esse evento de depuração imediatamente após atualizar o código de saída do thread. A estrutura DEBUG_EVENT contém uma estrutura EXIT_THREAD_DEBUG_INFO que especifica o código de saída. Esse evento de depuração não ocorrerá se o thread de saída for o último thread de um processo. Nesse caso, o evento de depuração EXIT_PROCESS_DEBUG_EVENT ocorre em vez disso. O depurador desaloca quaisquer estruturas internas associadas ao thread ao receber esse evento de depuração. O sistema fecha o identificador do depurador para o thread de saída. O depurador não deve fechar esse identificador.
LOAD_DLL_DEBUG_EVENT	Gerado sempre que um processo que está sendo depurado carrega uma DLL. Esse evento de depuração ocorre quando o carregador do sistema resolve links para uma DLL ou quando o processo depurado usa a função LoadLibrary . Esse evento de depuração ocorre somente na primeira vez que o sistema anexa uma DLL ao espaço de endereço virtual de um processo. A estrutura DEBUG_EVENT contém uma estrutura LOAD_DLL_DEBUG_INFO. Essa estrutura inclui um identificador para a DLL recém-carregada, o endereço base da DLL e outras informações que descrevem a DLL. O depurador deve fechar o identificador para o identificador DLL durante o processamento LOAD_DLL_DEBUG_EVENT. Normalmente, um depurador carrega uma tabela de símbolos associada à DLL ao receber esse evento de depuração.
OUTPUT_DEBUG_STRING_EVENT	Gerado quando um processo que está sendo depurado usa o Função OutputDebugString . A estrutura DEBUG_EVENT contém uma estrutura OUTPUT_DEBUG_STRING_INFO. Essa estrutura especifica o endereço, o comprimento e o formato da cadeia de caracteres de depuração.
UNLOAD_DLL_DEBUG_EVENT	Gerado sempre que um processo que está sendo depurado descarrega uma DLL usando a função FreeLibrary. Esse evento de depuração ocorre somente na última vez que uma DLL é descarregada do espaço de endereço de um processo (ou seja, quando a contagem de uso da DLL é zero). A estrutura DEBUG_EVENT contém uma estrutura UNLOAD_DLL_DEBUG_INFO. Essa estrutura especifica o endereço base da DLL no espaço de endereço do processo que descarrega a DLL. Normalmente, um depurador descarrega uma tabela de símbolos associada à DLL ao receber esse evento de depuração. Quando um processo é encerrado, o sistema descarrega automaticamente as DLLs do processo, mas não gera um evento de depuração UNLOAD_DLL_DEBUG_EVENT.
RIP_EVENT	Gerado sempre que um processo que está sendo depurado morre fora do controle do depurador do sistema. A estrutura DEBUG_EVENT contém uma estrutura RIP_INFO. Essa estrutura especifica o erro e o tipo de erro.