CreateProcessW function

Win32 apps | Microsoft Learn

Creates a new process and its primary thread. The new process runs in the security context of the calling process.


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
);
  • lpApplicationName [in, optional]
    The name of the module to be executed.
    • If this parameter is NULL, the module name is taken from the lpCommandLine string.
    • If this parameter specifies a full path, it must be a valid executable.
    • If this parameter specifies a relative path, CreateProcessW searches for the executable in the current directory.
  • lpCommandLine [in, out, optional]
    The command line string to be executed.
    • This string is parsed by the system and passed to the new process. The first element of the array pointed to by lpCommandLine is the module name.
    • If lpApplicationName is NULL, the first token of lpCommandLine is used as the module name.
    • If lpApplicationName is not NULL, the string specified by lpApplicationName is used as the module name.
    • The application can modify this string.
  • lpProcessAttributes [in, optional]
    A pointer to a SECURITY_ATTRIBUTES structure that specifies the security attributes for the new process. If NULL, the process gets a default security descriptor.
  • lpThreadAttributes [in, optional]
    A pointer to a SECURITY_ATTRIBUTES structure that specifies the security attributes for the new process's primary thread. If NULL, the thread gets a default security descriptor.
  • bInheritHandles [in]
    If TRUE, the calling process inherits handles. Otherwise, they are not inherited.
  • dwCreationFlags [in]
    Flags that control the priority class and behavior of the new process.
  • lpEnvironment [in, optional]
    A pointer to a null-terminated list of null-terminated strings, terminated by an additional NULL (i.e. "\x00\x00").
  • lpCurrentDirectory [in, optional]
    A pointer to a null-terminated string that specifies the full path for the current directory for the new process.
  • lpStartupInfo [in]
    A pointer to a STARTUPINFOW structure that specifies the window station, stdin, stdout, and stderr handles for the new process.
  • lpProcessInformation [out, optional]
    A pointer to a PROCESS_INFORMATION structure that receives identification information about the new process and its primary thread.

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.

The CreateProcessW function creates a new process and its primary thread. The new process is created with a security context that is identical to that of the parent process.

The command line string is parsed by the system. The first token of the command line string is the name of the module to be executed. If lpApplicationName is NULL, the module name is taken from the lpCommandLine string.

If the executable file is a 16-bit Windows-based application that is not compatible with your current version of Windows, the function fails and returns ERROR_DOS_EXCEPTION.

To create a process that runs in a separate console, specify the CREATE_NEW_CONSOLE flag in the dwCreationFlags parameter.

If you want the new process to inherit the handles of the calling process, set bInheritHandles to TRUE. Otherwise, set it to FALSE.

Creating a new process

The following code example demonstrates how to create a new process using CreateProcessW.


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

int main() {
    STARTUPINFOW si;
    PROCESS_INFORMATION pi;

    ZeroMemory(&si, sizeof(si));
    si.cb = sizeof(si);
    ZeroMemory(&pi, sizeof(pi));

    // Application name is NULL. Command line includes program name and arguments.
    LPCWSTR commandLine = L"notepad.exe C:\\Users\\Public\\Documents\\example.txt";

    // Create the child process.
    if (!CreateProcessW(
        NULL,                // lpApplicationName
        (LPWSTR)commandLine, // lpCommandLine
        NULL,                // lpProcessAttributes
        NULL,                // lpThreadAttributes
        FALSE,               // bInheritHandles
        0,                   // dwCreationFlags
        NULL,                // lpEnvironment
        NULL,                // lpCurrentDirectory
        &si,                 // lpStartupInfo
        &pi                  // lpProcessInformation
    )) {
        std::cerr << "CreateProcess failed (" << GetLastError() << ")." << std::endl;
        return 1;
    }

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

    // Close process and thread handles.
    CloseHandle(pi.hProcess);
    CloseHandle(pi.hThread);

    std::cout << "Child process has exited." << std::endl;

    return 0;
}
Package Minimum supported version
Header winbase.h (include Windows.h)
DLL Kernel32.lib, CoreMessaging.lib (if using Unified Shell Platform)