CreateProcessW Function

Creates a new process and its primary thread. The new process is run under the security context specified in the saProcess and saThread parameters.

Syntax

BOOL CreateProcessW(
  LPCWSTR               lpApplicationName,
  LPWSTR                lpCommandLine,
  LPSECURITY_ATTRIBUTES lpProcessAttributes,
  LPSECURITY_ATTRIBUTES lpThreadAttributes,
  BOOL                  bInheritHandles,
  DWORD                 dwCreationFlags,
  LPVOID                lpEnvironment,
  LPCWSTR               lpCurrentDirectory,
  LPSTARTUPINFOW        lpStartupInfo,
  LPPROCESS_INFORMATION lpProcessInformation
);

Parameters

Parameter	Description
`lpApplicationName`	The name of the module to be executed. The string must be a full path or a relative path. If this parameter is NULL, the module name is taken from the first token in the `lpCommandLine` string.
`lpCommandLine`	The command line string for the process to be executed. This string is Unicode. The first token of this string is the module name and the rest are parameters. The module name is not necessarily the same as the module being executed. It is the module that the new process is to use to get its starting point.
`lpProcessAttributes`	A pointer to a `SECURITY_ATTRIBUTES` structure that determines whether the returned handle can be inherited by the child processes. If NULL, the handle cannot be inherited.
`lpThreadAttributes`	A pointer to a `SECURITY_ATTRIBUTES` structure that determines whether the returned handle can be inherited by the child processes. If NULL, the handle cannot be inherited.
`bInheritHandles`	If this parameter is TRUE, the child process inherits the handles of the calling process. Otherwise, the handles are not inherited.
`dwCreationFlags`	Flags that control the priority class and behavior of the new process. For a list of possible values, see Process Creation Flags.
`lpEnvironment`	A pointer to a null-terminated Unicode string specifying the environment variable block for the new process. If NULL, the new process inherits the environment of the calling process.
`lpCurrentDirectory`	A pointer to a null-terminated Unicode string that specifies the full path for the current directory for the process. If NULL, the new process inherits the current directory of the calling process.
`lpStartupInfo`	A pointer to a `STARTUPINFOW` structure that specifies the window station, the standard handles, and the appearance of the main window for the new process.
`lpProcessInformation`	A pointer to a `PROCESS_INFORMATION` structure that receives identification information about the new process and its primary thread.

Return Value

If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call GetLastError.

Note

For a complete list of error codes, refer to the Windows Error Codes documentation.

Remarks

To create a console process, you must specify either the CREATE_NEW_CONSOLE flag or the DETACHED_PROCESS flag in the dwCreationFlags parameter. If neither flag is specified, the new process inherits the console of the parent process.

Important

If lpApplicationName is NULL, the first token in lpCommandLine is taken as the application name. The tokenization mechanism is the same one that the shell uses. This means that if the application name is omitted, the first "word" of the command line is treated as the application name.

You can use the STARTUPINFOW structure to specify how the new process's window should appear. This includes the window title, position, and size, as well as whether the window should be shown or minimized.

Example

The following example demonstrates how to use CreateProcessW to start a new Notepad process:


#include <windows.h>
#include <iostream>

int main() {
    STARTUPINFOW si;
    PROCESS_INFORMATION pi;

    ZeroMemory(&si, sizeof(si));
    si.cb = sizeof(si);
    si.dwFlags |= STARTF_USESHOWWINDOW;
    si.wShowWindow = SW_SHOWDEFAULT; // Show window in its default state

    ZeroMemory(&pi, sizeof(pi));

    // Application name and command line for Notepad
    LPCWSTR appName = L"notepad.exe";
    LPWSTR cmdLine = NULL; // Use NULL to have the application name as the command line

    // Create the child process.
    if (CreateProcessW(
        appName,       // lpApplicationName
        cmdLine,       // lpCommandLine
        NULL,          // lpProcessAttributes
        NULL,          // lpThreadAttributes
        FALSE,         // bInheritHandles
        0,             // dwCreationFlags
        NULL,          // lpEnvironment
        NULL,          // lpCurrentDirectory
        &si,           // lpStartupInfo
        &pi)           // lpProcessInformation
    ) {
        std::wcout << L"Successfully created process." << std::endl;
        std::wcout << L"Process ID: " << pi.dwProcessId << std::endl;
        std::wcout << L"Thread ID: " << pi.dwThreadId << std::endl;

        // Wait until child process exits.
        WaitForSingleObject(pi.hProcess, INFINITE);

        // Close process and thread handles.
        CloseHandle(pi.hProcess);
        CloseHandle(pi.hThread);
    } else {
        std::wcerr << L"CreateProcessW failed (" << GetLastError() << L")." << std::endl;
    }

    return 0;
}

View More Examples

← Previous Section Next Section →

Documentation