IDebugClient4::AttachProcess method (dbgeng.h)

Article
10/21/2021

The AttachProcess method connects the debugger engine to a user-modeprocess.

Syntax

HRESULT AttachProcess(
  [in] ULONG64 Server,
  [in] ULONG   ProcessId,
  [in] ULONG   AttachFlags
);

Parameters

[in] Server

Specifies the process server to use to attach to the process. If Server is zero, the engine will connect to a local process without using a process server.

[in] ProcessId

Specifies the process ID of the target process the debugger will attach to.

[in] AttachFlags

Specifies the flags that control how the debugger attaches to the target process. For details on these flags, see Remarks.

Return value

This method may also return error values. See Return Values for more details.

Return code	Description
S_OK	The method was successful.

Remarks

This method is available only for live user-mode debugging.

Note The engine doesn't completely attach to the process until the WaitForEvent method has been called. Only after the process has generated an event -- for example, the create-process event -- does it become available in the debugger session.

For more information about creating and attaching to live user-mode targets, see Live User-Mode Targets.

The DEBUG_ATTACH_XXX bit-flags control how the debugger engine attaches to a user-mode process. For the DEBUG_ATTACH_XXX options used when attaching to a kernel target, see AttachKernel.

The following table describes the possible flag values.

Constant	Description
DEBUG_ATTACH_NONINVASIVE	Attach to the target noninvasively. For more information about noninvasive debugging, see Noninvasive Debugging (User Mode). If this flag is set, then the flags DEBUG_ATTACH_EXISTING, DEBUG_ATTACH_INVASIVE_NO_INITIAL_BREAK, and DEBUG_ATTACH_INVASIVE_RESUME_PROCESS must not be set.
DEBUG_ATTACH_EXISTING	Re-attach to an application to which a debugger has already attached (and possibly abandoned). For more information about re-attaching to targets, see Re-attaching to the Target Application. If this flag is set, then the other DEBUG_ATTACH_XXX flags must not be set.
DEBUG_ATTACH_NONINVASIVE_NO_SUSPEND	Do not suspend the target's threads when attaching noninvasively. If this flag is set, then the flag DEBUG_ATTACH_NONINVASIVE must also be set.
DEBUG_ATTACH_INVASIVE_NO_INITIAL_BREAK	(Windows XP and later) Do not request an initial break-in when attaching to the target. If this flag is set, then the flags DEBUG_ATTACH_NONINVASIVE and DEBUG_ATTACH_EXISTING must not be set.
DEBUG_ATTACH_INVASIVE_RESUME_PROCESS	If this flag is set, then the flags DEBUG_ATTACH_NONINVASIVE and DEBUG_ATTACH_EXISTING must not be set.

Requirements

Requirement	Value
Target Platform	Desktop
Header	dbgeng.h (include Dbgeng.h)