IDebugClient::AttachProcess method

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

Syntax

HRESULT AttachProcess(
  ULONG64 Server,
  ULONG   ProcessId,
  ULONG   AttachFlags
);

Parameters

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.

ProcessId

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

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

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

See Also

.attach (Attach to Process)

AbandonCurrentProcess

AttachKernel

ConnectProcessServer

CreateProcess2

CreateProcessAndAttach2

DetachCurrentProcess

GetRunningProcessDescription

GetRunningProcessSystemIds

IDebugClient

IDebugClient2

IDebugClient3

IDebugClient4

IDebugClient5

TerminateCurrentProcess

debugger engine