Debugging Tools for Windows

CreateProcess2

The CreateProcess2 and CreateProcess2Wide methods execute the given command to create a new process.

HRESULT
  IDebugClient5::CreateProcess2(
    IN ULONG64  Server,
    IN PSTR  CommandLine,
    IN PVOID  OptionsBuffer,
    IN ULONG  OptionsBufferSize,
    IN OPTIONAL PCSTR  InitialDirectory,
    IN OPTIONAL PCSTR  Environment
    );

HRESULT
  IDebugClient5::CreateProcess2Wide(
    IN ULONG64  Server,
    IN PWSTR  CommandLine,
    IN PVOID  OptionsBuffer,
    IN ULONG  OptionsBufferSize,
    IN OPTIONAL PCWSTR  InitialDirectory,
    IN OPTIONAL PCWSTR  Environment
    );

#ifdef UNICODE
#define CreateProcess2T CreateProcess2Wide
#else
#define CreateProcess2T CreateProcess2
#endif

Parameters

Server

Specifies the process server that will be attached to the process. If Server is zero, the engine will create the local process without using a process server.

CommandLine

Specifies the command line to execute to create the new process.

OptionsBuffer

Specifies the process creation options. OptionsBuffer is a pointer to a DEBUG_CREATE_PROCESS_OPTIONS structure.

OptionsBufferSize

Specifies the size of the buffer OptionsBuffer. This should be set to sizeof(DEBUG_CREATE_PROCESS_OPTIONS).

InitialDirectory

Specifies the starting directory for the process. If InitialDirectory is NULL, the current directory for the process server is used.

Environment

Specifies an environment block for the new process. An environment block consists of a null-terminated block of null-terminated strings. Each string is of the form:

name=value

Note that the last two characters of the environment block are both NULL: one to terminate the string and one to terminate the block.

If Environment is set to NULL, the new process inherits the environment block of the process server. If the DEBUG_CREATE_PROCESS_THROUGH_RTL flag is set in OptionsBuffer, then Environment must be NULL.

Return Value

S_OK: The method was successful.

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

Interface Version

CreateProcess2 and CreateProcess2Wide are available in IDebugClient5 and later versions.

Comments

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

If CreateFlags contains either of the flags DEBUG_PROCESS or DEBUG_ONLY_THIS_PROCESS, the engine will also attach to the newly created process. This is similar to the behavior of CreateProcessAndAttach2 with its argument ProcessId set to zero.

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

Requirements