CreateRemoteThreadEx function (processthreadsapi.h)
Creates a thread that runs in the virtual address space of another process and optionally specifies extended attributes such as processor group affinity.
Syntax
HANDLE CreateRemoteThreadEx(
[in] HANDLE hProcess,
[in, optional] LPSECURITY_ATTRIBUTES lpThreadAttributes,
[in] SIZE_T dwStackSize,
[in] LPTHREAD_START_ROUTINE lpStartAddress,
[in, optional] LPVOID lpParameter,
[in] DWORD dwCreationFlags,
[in, optional] LPPROC_THREAD_ATTRIBUTE_LIST lpAttributeList,
[out, optional] LPDWORD lpThreadId
);
Parameters
[in] hProcess
A handle to the process in which the thread is to be created. The handle must have the PROCESS_CREATE_THREAD, PROCESS_QUERY_INFORMATION, PROCESS_VM_OPERATION, PROCESS_VM_WRITE, and PROCESS_VM_READ access rights. In Windows 10, version 1607, your code must obtain these access rights for the new handle. However, starting in Windows 10, version 1703, if the new handle is entitled to these access rights, the system obtains them for you. For more information, see Process Security and Access Rights.
[in, optional] lpThreadAttributes
A pointer to a SECURITY_ATTRIBUTES structure that specifies a security descriptor for the new thread and determines whether child processes can inherit the returned handle. If lpThreadAttributes is NULL, the thread gets a default security descriptor and the handle cannot be inherited. The access control lists (ACL) in the default security descriptor for a thread come from the primary token of the creator.
[in] dwStackSize
The initial size of the stack, in bytes. The system rounds this value to the nearest page. If this parameter is 0 (zero), the new thread uses the default size for the executable. For more information, see Thread Stack Size.
[in] lpStartAddress
A pointer to the application-defined function of type LPTHREAD_START_ROUTINE to be executed by the thread and represents the starting address of the thread in the remote process. The function must exist in the remote process. For more information, see ThreadProc.
[in, optional] lpParameter
A pointer to a variable to be passed to the thread function pointed to by lpStartAddress. This parameter can be NULL.
[in] dwCreationFlags
The flags that control the creation of the thread.
| Value | Meaning |
|---|---|
|
The thread runs immediately after creation. |
|
The thread is created in a suspended state and does not run until the ResumeThread function is called. |
|
The dwStackSize parameter specifies the initial reserve size of the stack. If this flag is not specified, dwStackSize specifies the commit size. |
[in, optional] lpAttributeList
An attribute list that contains additional parameters for the new thread. This list is created by the InitializeProcThreadAttributeList function.
[out, optional] lpThreadId
A pointer to a variable that receives the thread identifier.
If this parameter is NULL, the thread identifier is not returned.
Return value
If the function succeeds, the return value is a handle to the new thread.
If the function fails, the return value is NULL. To get extended error information, call GetLastError.
Remarks
The CreateRemoteThreadEx function causes a new thread of execution to begin in the address space of the specified process. The thread has access to all objects that the process opens. The lpAttribute parameter can be used to specify extended attributes such as processor group affinity for the new thread. If lpAttribute is NULL, the function's behavior is the same as CreateRemoteThread.
Prior to Windows 8, Terminal Services isolates each terminal session by design. Therefore, CreateRemoteThread fails if the target process is in a different session than the calling process.
The new thread handle is created with full access to the new thread. If a security descriptor is not provided, the handle may be used in any function that requires a thread object handle. When a security descriptor is provided, an access check is performed on all subsequent uses of the handle before access is granted. If the access check denies access, the requesting process cannot use the handle to gain access to the thread.
If the thread is created in a runnable state (that is, if the CREATE_SUSPENDED flag is not used), the thread can start running before CreateThread returns and, in particular, before the caller receives the handle and identifier of the created thread.
The thread is created with a thread priority of THREAD_PRIORITY_NORMAL. To get and set the priority value of a thread, use the GetThreadPriority and SetThreadPriority functions.
When a thread terminates, the thread object attains a signaled state, which satisfies the threads that are waiting for the object.
The thread object remains in the system until the thread has terminated and all handles to it are closed through a call to CloseHandle.
The ExitProcess, ExitThread, CreateThread, CreateRemoteThread functions, and a process that is starting (as the result of a CreateProcess call) are serialized between each other within a process. Only one of these events occurs in an address space at a time. This means the following restrictions hold:
- During process startup and DLL initialization routines, new threads can be created, but they do not begin execution until DLL initialization is done for the process.
- Only one thread in a process can be in a DLL initialization or detach routine at a time.
- ExitProcess returns after all threads have completed their DLL initialization or detach routines.
- It converts single-threaded applications into multithreaded applications.
- It changes the timing and memory layout of the process.
- It results in a call to the entry point of each DLL in the process.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 7 [desktop apps only] |
| Minimum supported server | Windows Server 2008 R2 [desktop apps only] |
| Target Platform | Windows |
| Header | processthreadsapi.h (include Windows.h on Windows Server 2008 Windows Server 2008 R2) |
| Library | Kernel32.lib |
| DLL | Kernel32.dll |