CreateProcessWithCPUWindows

The CreateProcessWithCPUWindows function creates a new process and its primary thread. The new process runs the specified executable. This function is specific to Windows and provides advanced control over process creation, including CPU affinity.

Syntax

BOOL CreateProcessWithCPUWindows(
              _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,
              _In_         DWORD                   dwAffinityMask
            );

Parameters

Parameter Type Description
lpApplicationName LPCTSTR The name of the module to be executed. This string must be a fully qualified path or a relative path. If the executable is in the system's PATH, you can specify the executable name without a path.

If lpCommandLine is not NULL, this parameter is typically NULL. The executable name is the first token in the lpCommandLine string.
lpCommandLine LPTSTR A null-terminated string that specifies the command line for the process to be executed. This string can contain an executable name and arguments.

If lpApplicationName is NULL, the first token of lpCommandLine must be the name of the executable.
lpProcessAttributes LPSECURITY_ATTRIBUTES A pointer to a SECURITY_ATTRIBUTES structure that specifies the security descriptor for the new process. If NULL, the process gets a default security descriptor.
lpThreadAttributes LPSECURITY_ATTRIBUTES A pointer to a SECURITY_ATTRIBUTES structure that specifies the security descriptor for the new process's primary thread. If NULL, the primary thread gets a default security descriptor.
bInheritHandles BOOL If this parameter is TRUE, the calling process's handles are inherited by the new process. Otherwise, they are not inherited.
dwCreationFlags DWORD Flags that control the priority class and behavior of the new process. Examples include CREATE_NEW_CONSOLE, CREATE_NO_WINDOW, HIGH_PRIORITY_CLASS.
lpEnvironment LPVOID A pointer to a block of memory that contains a null-terminated string list, separated by null characters, in the following format:
name1=value1\0name2=value2\0...\0\0
If this parameter is NULL, the new process inherits the environment of the calling process.
lpCurrentDirectory LPCTSTR A null-terminated string that specifies the full path of the current directory for the new process. If this parameter is NULL, the new process inherits the current directory of the calling process.
lpStartupInfo 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 LPPROCESS_INFORMATION A pointer to a PROCESS_INFORMATION structure that receives identification information about the new process and its primary thread.
dwAffinityMask DWORD A bitmask representing the affinity for the new process. Each bit corresponds to a logical processor. If a bit is set, the process is allowed to run on the processor corresponding to that bit.

For example, 0x00000001 allows the process to run on the first processor, 0x00000003 allows it to run on the first two processors.

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 dwAffinityMask parameter allows you to specify which processors a new process can run on. This is useful for performance tuning, especially on multi-processor systems, to ensure a process is confined to specific CPUs or to distribute load.

Note: The dwAffinityMask is applied to the hProcess member of the PROCESS_INFORMATION structure returned by the function.

To specify the executable name and its command-line arguments separately, use the lpApplicationName parameter for the executable and lpCommandLine for the command line. If lpApplicationName is NULL, the first token in lpCommandLine is treated as the executable name.

Consider using the CreateProcess function for simpler process creation scenarios if CPU affinity control is not required.

Tip: After you are finished with the process and thread handles returned in the PROCESS_INFORMATION structure, you should close them using CloseHandle to prevent resource leaks.

Requirements

Component Value
Minimum supported client Windows XP [desktop apps only]
Minimum supported server Windows Server 2003 [desktop apps only]
Target Platform Windows
Header processthreadsapi.h
Library Kernel32.lib
DLL Kernel32.dll

See Also