CreateProcessAndAttach

The CreateProcessAndAttach and CreateProcessAndAttachWide methods create a process from a specified command line, then attach to another user-mode process. The created process is suspended and only allowed to execute when the attach has completed. This allows rough synchronization when debugging both, client and server processes.

HRESULT
  IDebugClient::CreateProcessAndAttach(
    IN ULONG64  Server,
    IN OPTIONAL PSTR  CommandLine,
    IN ULONG  CreateFlags,
    IN ULONG  ProcessId,
    IN ULONG  AttachFlags
    );

HRESULT
  IDebugClient3::CreateProcessAndAttachWide(
    IN ULONG64  Server,
    IN OPTIONAL PWSTR  CommandLine,
    IN ULONG  CreateFlags,
    IN ULONG  ProcessId,
    IN ULONG  AttachFlags
    );

#ifdef UNICODE
#define CreateProcessAndAttachT CreateProcessAndAttachWide
#else
#define CreateProcessAndAttachT CreateProcessAndAttach
#endif

Parameters

Server

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

CommandLine

Specifies the command line to execute to create the new process. If CommandLine is NULL, then no process is created and these methods attach to an existing process, as AttachProcess does.

CreateFlags

Specifies the flags to use when creating the process. For details on these flags, see DEBUG_CREATE_PROCESS_OPTIONS.CreateFlags.

ProcessId

Specifies the process ID of the target process the debugger will attach to. If ProcessId is zero, the debugger will attach to the process it created from CommandLine.

AttachFlags

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

Return Value

S_OK

The method was successful.

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

Interface Version

CreateProcessAndAttach is available in all versions of IDebugClient. CreateProcessAndAttachWide is available in IDebugClient3 and later versions.

Comments

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

If CommandLine is not NULL and ProcessId is not zero, then the engine will create the process in a suspended state. The engine will resume this newly created process after it successfully connects to the process specified in ProcessId.

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.

Requirements

Headers: Defined in dbgeng.h. Include dbgeng.h.

See Also

CreateProcessAndAttach2, AttachProcess, .attach (Attach to Process), .create (Create Process), ConnectProcessServer, CreateProcess2, GetRunningProcessSystemIds, GetRunningProcessDescription , DetachCurrentProcess, TerminateCurrentProcess, AbandonCurrentProcess