CreateProcessInternalW

The CreateProcessInternalW function creates a new process and its primary thread. The new process runs in the same logon session as the calling process.

Syntax

BOOL CreateProcessInternalW(
  [in]            HANDLE                  hToken,
  [in, optional]  LPWSTR                  lpCommandLine,
  [in, optional]  LPSECURITY_ATTRIBUTES   lpProcessAttributes,
  [in, optional]  LPSECURITY_ATTRIBUTES   lpThreadAttributes,
  [in]            BOOL                    bInheritHandles,
  [in]            DWORD                   dwCreationFlags,
  [in, optional]  LPVOID                  lpEnvironment,
  [in, optional]  LPCWSTR                 lpCurrentDirectory,
  [in]            LPSTARTUPINFOW          lpStartupInfo,
  [out]           LPPROCESS_INFORMATION   lpProcessInformation
);

Parameters

Parameter	Type	Description
`hToken`	`HANDLE`	A handle to the primary access token of the process to be created. This token must be enabled for impersonation. If this parameter is NULL, the new process inherits the primary access token of the calling process. This parameter is reserved for system use, and must be NULL.
`lpCommandLine`	`LPWSTR`	The command line for the process to be created. This parameter can be NULL. If it is NULL, the function returns `FALSE`. If this parameter is an empty string, the return value is `FALSE`. The recommended method for creating a process is to specify the application name and command-line arguments separately, for example: `cmd.exe /c myapp.exe -arg1 -arg2`
`lpProcessAttributes`	`LPSECURITY_ATTRIBUTES`	A pointer to a `STARTUPINFOW` structure that specifies the window station, desktop, standard handles, and appearance of the main window for the new process. This parameter can be NULL. If `lpProcessAttributes` is NULL, the new process gets a default set of security attributes. The inheritance of the handles parameter of the security attributes structure determines whether the new process can inherit the handles of the calling process. Similarly, if `lpThreadAttributes` is NULL, the new process gets a default set of security attributes for the thread.
`lpThreadAttributes`	`LPSECURITY_ATTRIBUTES`	A pointer to a `STARTUPINFOW` structure that specifies the window station, desktop, standard handles, and appearance of the main window for the new process. This parameter can be NULL.
`bInheritHandles`	`BOOL`	If this parameter is `TRUE`, the calling process transfers ownership of any handles it possesses to the new process. Otherwise, the handles are not inherited. If the calling process is running under a debugger, the debugger can override this parameter and specify whether the handles are inherited.
`dwCreationFlags`	`DWORD`	Flags that control the priority class and behavior of the new process. This parameter can be a combination of the following values: `CREATE_BREAK_FROM_DEBUGGER` `CREATE_DEFAULT_ERROR_MODE` `CREATE_NEW_CONSOLE` `CREATE_NEW_PROCESS_GROUP` `CREATE_NO_WINDOW` `CREATE_PROTECTED_PROCESS` `CREATE_PRESERVE_CODE_AUTHZ_LEVEL` `CREATE_SEPARATE_WOW_VDM` `CREATE_SHARED_WOW_VDM` `CREATE_SUSPENDED` `CREATE_THREAD_ACCESS` `DEBUG_ONLY_THIS_PROCESS` `DEBUG_PROCESS` `DETACHED_PROCESS` `EXTENDED_STARTUPINFO_PRESENT` `INHERIT_PARENT_ENDOFFILE` `INHERIT_PARENT_SHELLPORTS` `INHERIT_READONLY` `JOB_NOTIFY_CONTAINER_MAXIMIZED` `LOGON_WITH_PROFILE` `NORMAL_PRIORITY_CLASS` `REALTIME_PRIORITY_CLASS` `HIGH_PRIORITY_CLASS` `ABOVE_NORMAL_PRIORITY_CLASS` `BELOW_NORMAL_PRIORITY_CLASS` `IDLE_PRIORITY_CLASS`
`lpEnvironment`	`LPVOID`	A pointer to a null-terminated Unicode string that specifies the environment variables for the new process. If this parameter is NULL, the new process inherits the environment of the calling process. The environment block is a null-terminated array of null-terminated strings. Each string is of the form: `name=value` The last string in the block is followed by two null characters: one for the string terminator and one for the block terminator.
`lpCurrentDirectory`	`LPCWSTR`	A pointer to a null-terminated Unicode 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`	`LPSTARTUPINFOW`	A pointer to a `STARTUPINFOW` structure that specifies the window station, desktop, standard handles, and appearance of the main window for the new process. This parameter can be NULL.
`lpProcessInformation`	`LPPROCESS_INFORMATION`	A pointer to a `PROCESS_INFORMATION` structure that receives information about the new process, including a handle to the new process and its primary thread, and identifies.

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 CreateProcessInternalW function is the internal routine used by the operating system to create processes. It is generally recommended to use the CreateProcessW function for creating processes in user-mode applications.

If lpCommandLine is NULL, the function fails and returns FALSE.

If lpStartupInfo points to a STARTUPINFOW structure, the cb member of that structure must be set to the size of the structure.

The hToken parameter is reserved for system use and must be NULL.

If the calling process is a 32-bit application, it can create a 64-bit process if the operating system supports it. If the calling process is a 64-bit application, it can only create 64-bit processes.

The dwCreationFlags parameter can be used to control various aspects of the new process. For example, you can create a process in a suspended state by using the CREATE_SUSPENDED flag, and then resume it later using the ResumeThread function.

The environment block is inherited from the parent process by default. If you want to provide a custom environment block, you must format it correctly as a null-terminated array of null-terminated strings.

Requirements

Minimum supported client: Windows XP with SP2

Minimum supported server: Windows Server 2003 with SP1

Header: ProcessThreadsAPI.h

Library: Kernel32.lib

DLL: Kernel32.dll

Unicode and ANSI versions: CreateProcessInternalW (Unicode) and CreateProcessInternalA (ANSI) are available.

Win32 API