Função DebugActiveProcess (debugapi.h)

Artigo
08/23/2023

Permite que um depurador se anexe a um processo ativo e depure-o.

Sintaxe

BOOL DebugActiveProcess(
  [in] DWORD dwProcessId
);

Parâmetros

[in] dwProcessId

O identificador do processo a ser depurado. O depurador recebe acesso de depuração ao processo como se tivesse criado o processo com o sinalizador DEBUG_ONLY_THIS_PROCESS . Para obter mais informações, confira a seção Comentários deste tópico.

Valor retornado

Se a função for bem-sucedida, o valor retornado será diferente de zero.

Se a função falhar, o valor retornado será zero (0). Para obter informações de erro estendidas, chame GetLastError.

Comentários

Para interromper a depuração do processo, você deve sair do processo ou chamar a função DebugActiveProcessStop . Sair do depurador também sai do processo, a menos que você use a função DebugSetProcessKillOnExit .

O depurador deve ter acesso apropriado ao processo de destino e deve ser capaz de abrir o processo para PROCESS_ALL_ACCESS. DebugActiveProcess poderá falhar se o processo de destino for criado com um descritor de segurança que concede ao depurador nada menos que o acesso completo. Se o processo de depuração tiver o privilégio SE_DEBUG_NAME concedido e habilitado, ele poderá depurar qualquer processo.

Depois que o sistema verifica o identificador do processo e determina que um anexo de depuração válido está sendo feito, a função retorna TRUE. Em seguida, espera-se que o depurador aguarde eventos de depuração usando a função WaitForDebugEvent . O sistema suspende todos os threads no processo e envia os eventos do depurador que representam o estado atual do processo.

O sistema envia ao depurador um único evento de depuração CREATE_PROCESS_DEBUG_EVENT que representa o processo especificado pelo parâmetro dwProcessId . O membro lpStartAddress da estrutura CREATE_PROCESS_DEBUG_INFO é NULL.

Para cada thread que atualmente faz parte do processo, o sistema envia um evento de depuração CREATE_THREAD_DEBUG_EVENT. O membro lpStartAddress da estrutura CREATE_THREAD_DEBUG_INFO é NULL.

Para cada DLL (biblioteca de vínculo dinâmico) que está atualmente carregada no espaço de endereço do processo de destino, o sistema envia um evento de depuração LOAD_DLL_DEBUG_EVENT. O sistema organiza o primeiro thread no processo para executar uma instrução de ponto de interrupção depois que ele é retomado. Continuar esse thread faz com que ele volte a fazer a mesma coisa que antes de o depurador ser anexado.

Depois que tudo isso for feito, o sistema retomará todos os threads no processo. Quando o primeiro thread no processo é retomado, ele executa uma instrução de ponto de interrupção que faz com que um evento de depuração EXCEPTION_DEBUG_EVENT seja enviado ao depurador. Todos os eventos de depuração futuros são enviados ao depurador usando o mecanismo e as regras normais.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows XP [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	debugapi.h (inclua Windows.h)
Biblioteca	Kernel32.lib
DLL	Kernel32.dll