CreateProcess Function

The CreateProcess function creates a new process and its primary thread. The new process runs in the address space of the calling process.

BOOL CreateProcess( _In_opt_ LPCTSTR lpApplicationName, _Inout_opt_ LPTSTR lpCommandLine, _In_opt_ LPSECURITY_ATTRIBUTES lpProcessAttributes, _In_opt_ LPSECURITY_ATTRIBUTES lpThreadAttributes, _In_ BOOL bInheritHandles, _In_ DWORD dwCreationFlags, _In_opt_ LPVOID lpEnvironment, _In_opt_ LPCTSTR lpCurrentDirectory, _In_ LPSTARTUPINFO lpStartupInfo, _Out_ 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 white space–delimited token in the `lpCommandLine` string. This token is determined by the tokens that are used by the `strtok` function. If the module is a COM server, use the `ProgID` instead of a path. If this parameter is NULL, the first token in `lpCommandLine` is used as the executable name. This parameter can be NULL. If it is NULL, the first token in `lpCommandLine` is used as the executable name.
`lpCommandLine`	The command line string for the new process. This string is Unicode or ANSI, depending on whether you are using the wide-character or multibyte-character version of the function. The first white space–delimited token in this string is the name of the module and its parameters. This name must be a file name that is accessible to the new process. If `lpApplicationName` is not NULL, the `lpApplicationName` parameter specifies the module to be executed. If `lpApplicationName` is NULL, the first token in `lpCommandLine` specifies the module to be executed. If the executable module is on the path, you do not need to specify a full path. If the executable module is not on the path, you should specify a full path. This parameter can be NULL.
`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 calling process inherits handles. Otherwise, the handles are not inherited.
`dwCreationFlags`	A flag that controls the execution priority class and the creation of the process. For a list of possible values, see Creation Flags.
`lpEnvironment`	A pointer to a block of memory containing a null-terminated Unicode or ANSI string table, terminated by two null characters. If this parameter is NULL, the new process inherits the environment of the calling process.
`lpCurrentDirectory`	A pointer to a null-terminated 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 STARTUPINFO structure that specifies the window station, standard handles, and appearance of the main window for the new process.
`lpProcessInformation`	A pointer to a PROCESS_INFORMATION structure that receives identification information, such as a handle and identifier, for 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.

Remarks

The CreateProcess function creates a new process to execute the specified application. The new process is created with a new set of executable threads that inherit certain attributes of the calling process and have unique attributes.

Note

If the executable file is a 16-bit application on a 32-bit system, CreateProcess returns an error.

Creation Flags

The dwCreationFlags parameter can be a combination of the following flags:

Flag	Description
`DEBUG_PROCESS`	The calling process is being debugged. It will receive debug events when the new process is created or terminates.
`DEBUG_ONLY_THIS_PROCESS`	The calling process is a debugger. It will receive notification when the new process is created or terminates. This flag is not supported for 32-bit processes debugging 64-bit processes or for 64-bit processes debugging 32-bit processes.
`CREATE_SUSPENDED`	The primary thread of the new process is created suspended. It does not run until the ResumeThread function is called.
`DETACHED_PROCESS`	The new process is a terminal process. It does not have a console associated with it unless it explicitly creates one.
`CREATE_NEW_CONSOLE`	The new process has a new console allocated, instead of inheriting the parent's console.
`CREATE_NEW_PROCESS_GROUP`	The new process is the root of a new process group. The SetConsoleCtrlHandler function can be used to handle CTRL+C and CTRL_CLOSE_EVENT signals.
`CREATE_UNICODE_ENVIRONMENT`	The new process uses the Unicode version of the CreateProcess function.

Tip

For security, always use the full path for the executable when possible, and validate user input carefully before passing it to CreateProcess.

Important

The lpCommandLine parameter is modified by the system and therefore must be mutable. Do not pass a string literal to this parameter.

Example


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

int main() {
    STARTUPINFO si;
    PROCESS_INFORMATION pi;

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

    // Command line for the new process
    TCHAR commandLine[] = TEXT("notepad.exe"); 

    // Create the child process. 
    if (CreateProcess(NULL,          // No module name (use command line)
                      commandLine,   // Command line
                      NULL,          // Process handle not inheritable
                      NULL,          // Thread handle not inheritable
                      FALSE,         // Set handle inheritance to FALSE
                      0,             // No creation flags
                      NULL,          // Use parent's environment block
                      NULL,          // Use parent's starting directory 
                      &si,           // Pointer to STARTUPINFO structure
                      &pi)           // Pointer to PROCESS_INFORMATION structure
    ) {
        std::wcout << L"Process created successfully." << 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"CreateProcess failed. Error: " << GetLastError() << std::endl;
        return 1; 
    }

    return 0;
}