CreateProcess Function

The CreateProcess function creates a new process and its primary thread. The new process is launched with the specified executable file.

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. This string must include the full path to the executable file.
lpCommandLine The command line string for the new process.
lpProcessAttributes A pointer to a SECURITY_ATTRIBUTES structure that determines whether the returned handle can be inherited by child processes of the process being created.
lpThreadAttributes A pointer to a SECURITY_ATTRIBUTES structure that determines whether the returned handle can be inherited by child processes of the process being created.
bInheritHandles If this parameter is TRUE, the child process inherits the handles of the calling process. Otherwise, the child process does not inherit the handles.
dwCreationFlags Flags that control the priority class and behavior of the new process.
lpEnvironment A pointer to a null-terminated string list that specifies the environment variables for the new process.
lpCurrentDirectory A pointer to a null-terminated string that specifies the full path of the current directory for the process.
lpStartupInfo A pointer to a STARTUPINFO structure that specifies the window station, family of handles, and 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.

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 is the primary mechanism for launching new applications in Windows. It provides extensive control over how the new process is created, including its environment, working directory, and security attributes.

Note

When specifying the executable name, it is recommended to use the full path to avoid ambiguity and potential security risks.

Important

Properly handling the handles returned in the PROCESS_INFORMATION structure is crucial for resource management. Ensure that handles are closed when they are no longer needed using CloseHandle.

Example

The following example demonstrates how to create a new process that runs 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
    const char* commandLine = "notepad.exe";

    // Start the child process.
    if( !CreateProcess( NULL,       // No module name (use command line)
        (LPSTR)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
    ) {
        printf( "CreateProcess failed (%d).\n", GetLastError() );
        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." << std::endl;

    return 0;
}