CreateProcess Function

Namespace: Win32 API Module: Kernel32.dll

The CreateProcess function creates a new process and its primary thread. The new process is represented by a handle to the process and a handle to the primary thread of the process. The function can also return information about the new process, such as handles and identifiers. This function is the most powerful and flexible way to create processes.

Syntax


BOOL CreateProcess(
  LPCTSTR               lpApplicationName,
  LPTSTR                lpCommandLine,
  LPSECURITY_ATTRIBUTES lpProcessAttributes,
  LPSECURITY_ATTRIBUTES lpThreadAttributes,
  BOOL                  bInheritHandles,
  DWORD                 dwCreationFlags,
  LPVOID                lpEnvironment,
  LPCTSTR               lpCurrentDirectory,
  LPSTARTUPINFO         lpStartupInfo,
  LPPROCESS_INFORMATION lpProcessInformation
);

Parameters

Parameter	Description
`lpApplicationName`	The name of the module to be executed. The string must be a null-terminated string. This parameter can be NULL. If it is NULL, the module name must be the first token in the string pointed to by `lpCommandLine`.
`lpCommandLine`	The command line string for the process to be executed. This string is always processed by the C run-time library (C runtime) startup code. The C runtime startup code uses the string pointed to by `lpCommandLine` to determine the arguments to pass to the `main()` function.
`lpProcessAttributes`	A pointer to a `SECURITY_ATTRIBUTES` structure that determines whether the returned handle can be inherited by child processes. If `lpProcessAttributes` is NULL, the handle cannot be inherited.
`lpThreadAttributes`	A pointer to a `SECURITY_ATTRIBUTES` structure that determines whether the handle returned in `lpProcessInformation` can be inherited by child processes. If `lpThreadAttributes` is NULL, the handle cannot be inherited.
`bInheritHandles`	A boolean value that specifies whether the new process inherits the calling process's environment, including its handles. If this parameter is TRUE, the calling process's handles are inherited by the new process.
`dwCreationFlags`	Flags that control the priority class and behavior of the new process. See `dwCreationFlags` for a list of possible values.
`lpEnvironment`	A pointer to a null-terminated list of environment strings for the new process. If NULL, the new process inherits the environment of the calling process.
`lpCurrentDirectory`	A pointer to a null-terminated string that specifies the fully qualified path of the current directory for the new 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, desktop, standard handles, and the appearance of the main window for the new process.
`lpProcessInformation`	A pointer to a `PROCESS_INFORMATION` structure that receives information about the new process, such as handles and identifiers.

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

When you specify the command line, it's important to understand how it's parsed. The first token is treated as the executable name. If the executable name has a file extension, it's used directly. Otherwise, the system searches for the executable with common extensions (like .COM, .EXE, .BAT, .CMD).

The dwCreationFlags parameter allows fine-grained control over process creation. Common flags include:

CREATE_NEW_CONSOLE: Creates a new console window for the process.
CREATE_NO_WINDOW: Creates the process without a console window.
DETACHED_PROCESS: Creates the process detached from the console.
CREATE_SUSPENDED: Creates the process in a suspended state, allowing modification before it begins execution.

Handles are inherited by the child process if bInheritHandles is TRUE. This can be useful for redirecting standard input, output, or error streams. You can manage this by creating new pipes and passing their handles via the STARTUPINFO structure.

Example

The following example demonstrates how to create a new process to run Notepad:


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

int main() {
    STARTUPINFO si;
    PROCESS_INFORMATION pi;

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

    // The command line to execute
    LPTSTR commandLine = TEXT("notepad.exe");

    // Start 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
                       CREATE_NEW_CONSOLE, // Use new console
                       NULL,               // Use parent's environment block
                       NULL,               // Use parent's starting directory
                       &si,                // Pointer to STARTUPINFO structure
                       &pi)                // Pointer to PROCESS_INFORMATION structure
    ) {
        std::cerr << "CreateProcess failed (" << GetLastError() << ").\n";
        return 1;
    }

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

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

    std::cout << "Notepad process has finished.\n";

    return 0;
}