CreateProcessA

BOOL CreateProcessA( LPCSTR lpApplicationName, LPSTR lpCommandLine, LPSECURITY_ATTRIBUTES lpProcessAttributes, LPSECURITY_ATTRIBUTES lpThreadAttributes, BOOL bInheritHandles, DWORD dwCreationFlags, LPVOID lpEnvironment, LPCSTR lpCurrentDirectory, LPSTARTUPINFOA lpStartupInfo, LPPROCESS_INFORMATION lpProcessInformation );

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

Parameters

lpApplicationName: The name of the module that is to be executed. The string must be a null-terminated string. This parameter can be NULL. If it is NULL, the module name is taken from the command line string pointed to by lpCommandLine.
lpCommandLine: The command line string to be executed. This string is always processed by the container. The first wide character in this string is the one that determines the manner in which the command line is parsed.
lpProcessAttributes: A pointer to a SECURITY_ATTRIBUTES structure that specifies the security attributes for the new process. If this parameter is NULL, the process gets a default security descriptor.
lpThreadAttributes: A pointer to a SECURITY_ATTRIBUTES structure that specifies the security attributes for the new thread. If this parameter is NULL, the thread gets a default security descriptor.
bInheritHandles: Specifies whether the new process inherits the handles of the calling process.
dwCreationFlags: Flags that control the priority class and behavior of the new process.
lpEnvironment: A pointer to a null-terminated list of strings, each terminated by a null character, that specifies the environment for the new process.
lpCurrentDirectory: A pointer to a null-terminated string that specifies the full path of the current directory for the child 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 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 CreateProcessA function provides access to the full functionality of the process creation mechanism. It allows you to control everything from process and thread security attributes to environment variables and working directories.

When you call CreateProcessA, you can specify the executable to run either by setting lpApplicationName or by providing a full command line in lpCommandLine. If lpApplicationName is NULL, the first token in lpCommandLine is taken as the application name.

The dwCreationFlags parameter is crucial for customizing process behavior. Common flags include:

CREATE_SUSPENDED: Creates the process in a suspended state.
DETACHED_PROCESS: Creates the process without a console.
CREATE_NEW_CONSOLE: Creates a new console for the process.

The STARTUPINFO structure allows you to set up standard input, output, and error handles, as well as define the appearance of the process's window if it's a GUI application.

The PROCESS_INFORMATION structure returned via lpProcessInformation contains the process identifier (PID) and thread identifier (TID) of the newly created process and its primary thread, along with handles to both.

Important: When using lpApplicationName, ensure it is a complete path to the executable or is in the system's PATH environment variable. If using lpCommandLine, the first argument is treated as the executable path.

For Unicode versions of this function, see CreateProcessW.

Example


#include <windows.h>
#include <stdio.h>

int main() {
    STARTUPINFOA si;
    PROCESS_INFORMATION pi;
    char commandLine[] = "notepad.exe"; // Command line to execute

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

    // Start the child process.
    if (!CreateProcessA(
        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
    ) {
        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);

    printf("Notepad process has exited.\n");

    return 0;
}

This example demonstrates creating a new instance of Notepad. It initializes the necessary structures, calls CreateProcessA, and then waits for the spawned process to terminate before closing the handles.

View Full API Documentation