Microsoft Learn / MSDN Documentation / Windows / API Reference / Fundamentals / Processes / CreateProcessW

CreateProcessW function

processthreadsapi.h header

Creates a new process and its primary thread in the calling process's address space. Each new process is created with a single thread that serves as the process's main thread.

Syntax

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
);

Parameters

Parameter	Description
`lpApplicationName`	The name of the module to be executed. This string must be a fully qualified path. If this parameter is NULL, the module name is taken from the first token in the lpCommandLine string.
`lpCommandLine`	The command line string for the new process. This string must include the program name and any arguments. The program name can be in the same string or in a separate string pointed to by lpApplicationName.
`lpProcessAttributes`	A pointer to a SECURITY_ATTRIBUTES structure that specifies the security descriptor for the new process. If NULL, the new process gets a default security descriptor.
`lpThreadAttributes`	A pointer to a SECURITY_ATTRIBUTES structure that specifies the security descriptor for the new process's primary thread. If NULL, the new process gets a default security descriptor for its primary thread.
`bInheritHandles`	If this parameter is TRUE, the calling process's handles are inherited by the new process. Otherwise, they are not. The handles are duplicated by the process-creation function. If this parameter is TRUE, each handle that is not explicitly marked as inherited must be closed by the new process.
`dwCreationFlags`	Flags that control the priority class and behavior of the new process. This parameter can be a combination of the following values: `CREATE_NEW_CONSOLE` `CREATE_NEW_PROCESS_GROUP` `CREATE_NO_WINDOW` `CREATE_SEPARATE_WOW_VDM` `CREATE_SHARED_WOW_VDM` `CREATE_SUSPENDED` `CREATE_UNICODE_ENVIRONMENT` `DEBUG_ONLY_THIS_PROCESS` `DEBUG_PROCESS` `DETACHED_PROCESS` `EXTENDED_STARTUPINFO_PRESENT` `INHERIT_CALLER_PRIORITY` `PROCESS_MODE_BACKGROUND_BEGIN` `PROCESS_MODE_BACKGROUND_END` `REALTIME_PRIORITY_CLASS` `HIGH_PRIORITY_CLASS` `ABOVE_NORMAL_PRIORITY_CLASS` `NORMAL_PRIORITY_CLASS` `BELOW_NORMAL_PRIORITY_CLASS` `IDLE_PRIORITY_CLASS`
`lpEnvironment`	A pointer to a null-terminated list of null-terminated strings, terminated by an additional NULL (i.e., 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 new process. If this parameter is NULL, the new process inherits the current directory of the calling process.
`lpStartupInfo`	A pointer to a STARTUPINFOW 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 information about the new process, such as its handle and identifier.

Return value

Value	Description
`TRUE`	The function returns nonzero if it is successful.
`FALSE`	The return value is zero if the specified file or command line is invalid. To get extended error information, call `GetLastError`.

Remarks

To create a process, you must specify the executable file for the new process and then call the CreateProcess function.

The system creates the new process and its primary thread. The new process inherits the security attributes, environment variables, and other attributes of the calling process.

If the dwCreationFlags parameter specifies CREATE_SUSPENDED, the primary thread of the new process is created in a suspended state, and does not execute until ResumeThread is called.

Example

C++

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

int main() {
    STARTUPINFOW si;
    PROCESS_INFORMATION pi;

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

    // Command line to start notepad.exe
    // Note: lpApplicationName is NULL, so the first token in lpCommandLine is used as the executable name.
    // It's good practice to pass the executable name in lpApplicationName if it's not within the command line.
    // For simplicity here, we use lpCommandLine for both.
    LPCWSTR commandLine = L"notepad.exe";

    // Start the child process.
    if (!CreateProcessW(
        NULL,           // No module name (use command line)
        const_cast<LPWSTR>(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 STARTUPINFOW 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;
}

using System;
using System.Diagnostics;
using System.Runtime.InteropServices;

public class ProcessCreator
{
    // Define the necessary Win32 API structures and constants
    [StructLayout(LayoutKind.Sequential)]
    public struct STARTUPINFOW
    {
        public int cb;
        [MarshalAs(UnmanagedType.LPWStr)]
        public string lpReserved;
        [MarshalAs(UnmanagedType.LPWStr)]
        public string lpDesktop;
        [MarshalAs(UnmanagedType.LPWStr)]
        public string lpTitle;
        public int dwX;
        public int dwY;
        public int dwXSize;
        public int dwYSize;
        public int dwXCountChars;
        public int dwYCountChars;
        public int dwFillAttribute;
        public int dwFlags;
        public short wShowWindow;
        public short cbReserved2;
        public IntPtr lpReserved2;
        public IntPtr hStdInput;
        public IntPtr hStdOutput;
        public IntPtr hStdError;
    }

    [StructLayout(LayoutKind.Sequential)]
    public struct PROCESS_INFORMATION
    {
        public IntPtr hProcess;
        public IntPtr hThread;
        public int dwProcessId;
        public int dwThreadId;
    }

    [DllImport("kernel32.dll", SetLastError = true, CharSet = CharSet.Unicode)]
    [return: MarshalAs(UnmanagedType.Bool)]
    static extern bool CreateProcessW(
        string lpApplicationName,
        string lpCommandLine,
        IntPtr lpProcessAttributes, // SECURITY_ATTRIBUTES (use IntPtr for simplicity)
        IntPtr lpThreadAttributes,   // SECURITY_ATTRIBUTES (use IntPtr for simplicity)
        bool bInheritHandles,
        uint dwCreationFlags,
        IntPtr lpEnvironment,       // Use IntPtr for simplicity, manage memory if needed
        string lpCurrentDirectory,
        ref STARTUPINFOW lpStartupInfo,
        out PROCESS_INFORMATION lpProcessInformation);

    [DllImport("kernel32.dll")]
    static extern uint WaitForSingleObject(IntPtr hHandle, uint dwMilliseconds);

    [DllImport("kernel32.dll")]
    [return: MarshalAs(UnmanagedType.Bool)]
    static extern bool CloseHandle(IntPtr hObject);

    const uint INFINITE = 0xFFFFFFFF;

    public static void Main(string[] args)
    {
        STARTUPINFOW si = new STARTUPINFOW();
        si.cb = Marshal.SizeOf(si);

        PROCESS_INFORMATION pi;

        string applicationName = null; // Can be null if specified in command line
        string commandLine = "notepad.exe";

        if (!CreateProcessW(
            applicationName,
            commandLine,
            IntPtr.Zero, // lpProcessAttributes
            IntPtr.Zero, // lpThreadAttributes
            false,       // bInheritHandles
            0,           // dwCreationFlags
            IntPtr.Zero, // lpEnvironment
            null,        // lpCurrentDirectory
            ref si,
            out pi))
        {
            Console.WriteLine($"CreateProcess failed ({Marshal.GetLastWin32Error()}).");
            return;
        }

        Console.WriteLine("Notepad process started.");

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

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

        Console.WriteLine("Notepad process has finished.");
    }
}

Requirements

Support	Details
Minimum supported client	Windows 2000 Professional [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Header	`processthreadsapi.h` (include `windows.h`)
Library	Use `Kernel32.lib`
DLL	`Kernel32.dll`
Unicode and ANSI versions	`CreateProcessA` (ANSI version) and `CreateProcessW` (Unicode version).