Método IDebugClient5::CreateProcessAndAttach2 (dbgeng.h)

Artigo
02/06/2025

O método CreateProcessAndAttach2 cria um processo a partir de uma linha de comando especificada e, em seguida, é anexado a esse processo ou a outro processo de modo de usuário.

Sintaxe

HRESULT CreateProcessAndAttach2(
  [in]           ULONG64 Server,
  [in, optional] PSTR    CommandLine,
  [in]           PVOID   OptionsBuffer,
  [in]           ULONG   OptionsBufferSize,
  [in, optional] PCSTR   InitialDirectory,
  [in, optional] PCSTR   Environment,
  [in]           ULONG   ProcessId,
  [in]           ULONG   AttachFlags
);

Parâmetros

[in] Server

Especifica o servidor de processo a ser usado para anexar ao processo. Se Server for zero, o mecanismo se conectará ao processo local sem usar um servidor de processo.

[in, optional] CommandLine

Especifica a linha de comando a ser executada para criar o novo processo. Se CommandLine for NULL, nenhum processo será criado e esses métodos usarão ProcessId para anexar a um processo existente.

[in] OptionsBuffer

Especifica as opções de criação do processo. OptionsBuffer é um ponteiro para uma estrutura de DEBUG_CREATE_PROCESS_OPTIONS.

[in] OptionsBufferSize

Especifica o tamanho do buffer OptionsBuffer. Isso deve ser definido como sizeof(DEBUG_CREATE_PROCESS_OPTIONS).

[in, optional] InitialDirectory

Especifica o diretório inicial do processo. Esse parâmetro será usado somente se CommandLine não estiver NULL. Se InitialDirectory for NULL, o diretório atual do servidor de processo será usado.

[in, optional] Environment

Especifica um bloco de ambiente para o novo processo. Um bloco de ambiente consiste em um bloco encerrado em nulo de cadeias de caracteres terminadas em nulo. Cada cadeia de caracteres é do formulário:

name=value

Observe que os dois últimos caracteres do bloco de ambiente são NULL: um para encerrar a cadeia de caracteres e outro para encerrar o bloco.

Se Environment estiver definido como NULL, o novo processo herdará o bloco de ambiente do servidor de processo. Se o sinalizador de DEBUG_CREATE_PROCESS_THROUGH_RTL estiver definido em OptionsBuffer, Environment deverá ser NULL.

[in] ProcessId

Especifica a ID do processo de destino ao qual o depurador será anexado. Se ProcessID for zero, o depurador será anexado ao processo criado a partir de commandline.

[in] AttachFlags

Especifica os sinalizadores que controlam como o depurador é anexado ao processo de destino. Para obter detalhes sobre esses sinalizadores, consulte DEBUG_ATTACH_XXX.

Valor de retorno

Esse método também pode retornar valores de erro. Consulte de Valores Retornados para obter mais detalhes.

Código de retorno	Descrição
S_OK	O método foi bem-sucedido.
E_INVALIDARG	Isso será retornado se CommandLine for NULL e ProcessId for zero.

Observações

Esse método está disponível apenas para depuração dinâmica do modo de usuário.

Se CommandLine não estiver NULL e ProcessId não for zero, o mecanismo criará o processo em um estado suspenso. O mecanismo retomará esse processo recém-criado depois de se conectar com êxito ao processo especificado em ProcessId.

Observação O mecanismo não é completamente anexado ao processo até que o método WaitForEvent tenha sido chamado. Somente depois que o processo tiver gerado um evento, por exemplo, o evento create-process, ele ficará disponível na sessão do depurador.

Para obter mais informações sobre como criar e anexar a destinos de modo de usuário dinâmico, consulte de Destinos do Live User-Mode .