diff --git a/descriptions/client_id.md b/descriptions/client_id.md index e69de29bb2d..4cdb54823a5 100644 --- a/descriptions/client_id.md +++ b/descriptions/client_id.md @@ -0,0 +1,5 @@ +This structure defines a pair of process and thread IDs. + +# Members + - `UniqueProcess` - the process ID value. + - `UniqueThread` - the thread ID value. diff --git a/descriptions/ntalertresumethread.md b/descriptions/ntalertresumethread.md index d6117002215..7686e8a40bd 100644 --- a/descriptions/ntalertresumethread.md +++ b/descriptions/ntalertresumethread.md @@ -1,22 +1,18 @@ -### ThreadHandle +Alerts and resumes the specified thread that previously entered an alertable wait and then was suspended. Once the suspension counter drops to zero, the thread wakes and returns `STATUS_ALERTED`. -Handle to thread object. +# Parameters + - `ThreadHandle` - a handle to a thread granting `THREAD_SUSPEND_RESUME` access. + - `PreviousSuspendCount` - an optional pointer to a variable that receives the previous value of the suspension counter of the thread. -### SuspendCount +# Remarks +Despite the name similarity, this function is unrelated to `NtAlertThreadByThreadId`. -Returns number of suspend request for thread `ThreadHandle` before call `NtAlertResumeThread`. If this number is *0*, \ -thread will continue execution. - -Difference between `AlertResumeThread` and `ResumeThread` it's the first one sets Thread Object to alerted state (so before thread will continue execution, all APC will be executed). - -# Documented by - -* Tomasz Nowak -* ReactOS +# Related Win32 API +This functionality is not exposed in Win32 API. # See also - -* `NtCreateThread` -* `NtOpenThread` -* `NtResumeThread` -* `NtSuspendThread` + - `NtAlertThread` + - `NtResumeThread` + - `NtDelayExecution` + - `NtWaitForSingleObject` + - `NtWaitForMultipleObjects` diff --git a/descriptions/ntalertthread.md b/descriptions/ntalertthread.md index 6b8afd438e3..49422347bec 100644 --- a/descriptions/ntalertthread.md +++ b/descriptions/ntalertthread.md @@ -1,17 +1,15 @@ -### ThreadHandle +Alerts and wakes the specified thread that previously entered an alertable wait, causing it to return `STATUS_ALERTED`. -Handle to opened Thread Object. +# Parameters + - `ThreadHandle` - a handle to a thread granting `THREAD_ALERT` access. ---- +# Remarks +Despite the name similarity, this function is unrelated to `NtAlertThreadByThreadId`. -`NtAlertThread` puts specified thread in alerted state. - -# Documented by - -* ReactOS -* Tomasz Nowak +# Related Win32 API +This functionality is not exposed in Win32 API. # See also - -* `NtAlertResumeThread` -* `NtTestAlert` + - `NtDelayExecution` + - `NtWaitForSingleObject` + - `NtWaitForMultipleObjects` diff --git a/descriptions/ntalertthreadbythreadid.md b/descriptions/ntalertthreadbythreadid.md index e69de29bb2d..48dc1c47d20 100644 --- a/descriptions/ntalertthreadbythreadid.md +++ b/descriptions/ntalertthreadbythreadid.md @@ -0,0 +1,17 @@ +Wakes another thread that previously called `NtWaitForAlertByThreadId`. + +# Parameters + - `ThreadId` - the ID of the thread to wake. The thread must belong to the same process as the caller. + +# Remarks +Despite the name, `NtAlertThread` and alertable waits via `NtDelayExecution` are unrelated to this functionality. + +# Related Win32 API + - [`WakeByAddressSingle`](https://learn.microsoft.com/en-us/windows/win32/api/synchapi/nf-synchapi-wakebyaddresssingle) + - [`WakeByAddressAll`](https://learn.microsoft.com/en-us/windows/win32/api/synchapi/nf-synchapi-wakebyaddressall) + +# Required OS version +This function was introduced in Windows 8. + +# See also + - `NtWaitForAlertByThreadId` diff --git a/descriptions/ntchangethreadstate.md b/descriptions/ntchangethreadstate.md index e69de29bb2d..cf14de9ce5f 100644 --- a/descriptions/ntchangethreadstate.md +++ b/descriptions/ntchangethreadstate.md @@ -0,0 +1,27 @@ +Adjusts the state of a thread via a thread state object. This function offers a more resilient alternative mechanism to suspending threads, tying the duration of the operation to the lifetime of the state object. + +# Parameters + - `ThreadStateChangeHandle` - a handle to the thread state object created via `NtCreateThreadStateChange`. The handle must grant `THREAD_STATE_CHANGE_STATE` access. + - `ThreadHandle` - a handle to the associated thread which state should be changed. For suspend and resume operations, this handle must grant `THREAD_SUSPEND_RESUME` access. + - `StateChangeType` - the type of the operation to perform. + - `ExtendedInformation` - an optional pointer to a buffer with request-specific information. Currently unused. + - `ExtendedInformationLength` - the size of the provided buffer. Currently unused. + - `Reserved` - this parameter is unused and should be set to zero. + +# Operation types +For the list of supported operations, see `THREAD_STATE_CHANGE_TYPE`. + +# Remarks +Closing the thread state object handle via `NtClose` releases the reference. When the reference counter drops to zero, the system automatically undoes the effect of the state changes on the associated thread. + +# Related Win32 API +This functionality is not exposed in Win32 API. + +# Required OS version +This function was introduced in Windows 11. + +# See also + - `NtCreateThreadStateChange` + - `NtOpenThread` + - `NtSuspendThread` + - `NtResumeThread` diff --git a/descriptions/ntcreatethread.md b/descriptions/ntcreatethread.md index 68e41a5bc16..c81fc94bf00 100644 --- a/descriptions/ntcreatethread.md +++ b/descriptions/ntcreatethread.md @@ -1,43 +1,27 @@ -### ThreadHandle +Creates a new thread in the specified process. This is a legacy function that requires manually allocating stack and preparing thread context. -Caller supplied storage for the resulting handle. +# Parameters + - `ThreadHandle` - a pointer to a variable that receives a handle to the new thread. + - `DesiredAccess` - the thread access mask to provide on the returned handle. This value is usually `THREAD_ALL_ACCESS`. + - `ObjectAttributes` - an optional pointer to an `OBJECT_ATTRIBUTES` structure that specifies attributes for the new object/handle, such as the security descriptor and handle inheritance. + - `ProcessHandle` - a handle to the process where the thread should be created. This can either be the `NtCurrentProcess` pseudo-handle or a handle with `PROCESS_CREATE_THREAD` access. + - `ClientId` - a pointer to a variable that receives the client ID of the new thread. + - `ThreadContext` - the initial context (a set of registers) for the thread. + - `InitialTeb` - the structure describing the thread stack. + - `CreateSuspended` - whether the new thread should be created in a suspended state or allowed to run immediately. When specifying `TRUE`, you can use `NtResumeThread` to resume the thread later. -### DesiredAccess +# Remarks +For the modern equivalent, see `NtCreateThreadEx`. -Specifies the allowed or desired access to the thread. +To avoid retaining unused resources, call `NtClose` to close the returned handle when it is no longer required. -### ObjectAttributes - -Initialized attributes for the object. - -### ProcessHandle - -Handle to the threads parent process. - -### ClientId - -Caller supplies storage for returned process id and thread id. - -### ThreadContext - -Initial processor context for the thread. - -### InitialTeb - -Initial user mode stack context for the thread. - -### CreateSuspended - -Specifies if the thread is ready for scheduling. See `NtContinue` for more information. - -# Documented by - -* ReactOS +# Related Win32 API +This functionality is not exposed in Win32 API. The closest alternative that uses the modern syscall is [`CreateRemoteThreadEx`](https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-createremotethreadex). # See also - -* `INITIAL_TEB` -* `NtContinue` -* `NtCreateProcess` -* `NtTerminateThread` -* `NtAlertResumeThread` + - `NtCreateThreadEx` + - `RtlCreateUserThread` + - `NtResumeThread` + - `NtOpenThread` + - `NtOpenProcess` + - `NtCreateProcess` diff --git a/descriptions/ntcreatethreadex.md b/descriptions/ntcreatethreadex.md index e69de29bb2d..f7334d34026 100644 --- a/descriptions/ntcreatethreadex.md +++ b/descriptions/ntcreatethreadex.md @@ -0,0 +1,49 @@ +Creates a new thread in the specified process. + +# Parameters + - `ThreadHandle` - a pointer to a variable that receives a handle to the new thread. + - `DesiredAccess` - the thread access mask to provide on the returned handle. This value is usually `THREAD_ALL_ACCESS`. + - `ObjectAttributes` - an optional pointer to an `OBJECT_ATTRIBUTES` structure that specifies attributes for the new object/handle, such as the security descriptor and handle inheritance. + - `ProcessHandle` - a handle to the process where the thread should be created. This can either be the `NtCurrentProcess` pseudo-handle or a handle with `PROCESS_CREATE_THREAD` access. + - `StartRoutine` - the function to execute on the new thread. + - `Argument` - a user-provided argument to pass to the thread start routine. + - `CreateFlags` - a bit mask that control the properties of the new thread or its creation. See below. + - `ZeroBits` - the number of high-order address bits that must be zero in the base address of the thread's stack. Note that when the value is larger than 32, it becomes a bit mask. + - `StackSize` - the initial size of the stack, in bytes. The system rounds this value up to the nearest page. If this parameter is zero, the new thread uses the default size for the executable. + - `MaximumStackSize` - the maximum size of the stack, in bytes. The system rounds this value up to the nearest page. If this parameter is zero, the new thread uses the default size for the executable. + - `AttributeList` - an optional pointer to a buffer that defines a list of `PS_ATTRIBUTE` structures that control various aspects of thread creation and allow retrieving information about the new thread. + +# Creation flags + - `THREAD_CREATE_FLAGS_CREATE_SUSPENDED` - create the thread in a suspended state instead of allowing it to execute immediately. + - `THREAD_CREATE_FLAGS_SKIP_THREAD_ATTACH` - the thread should skip calling loaded modules with `DLL_THREAD_ATTACH` reason. + - `THREAD_CREATE_FLAGS_HIDE_FROM_DEBUGGER` - suppress generation of debug events on the thread. + - `THREAD_CREATE_FLAGS_LOADER_WORKER` - set the corresponding flag in `TEB`. + - `THREAD_CREATE_FLAGS_SKIP_LOADER_INIT` - set the corresponding flag in `TEB`. + - `THREAD_CREATE_FLAGS_BYPASS_PROCESS_FREEZE` - the thread should not be suspended when the system suspends or freezes the process. + +Check the corresponding pages for more details. + +# Supported attributes + - `PS_ATTRIBUTE_CLIENT_ID` - allows retrieving the `CLIENT_ID` of the new thread. + - `PS_ATTRIBUTE_TEB_ADDRESS` - allows retrieving the `TEB` address of the new thread. + - `PS_ATTRIBUTE_IDEAL_PROCESSOR` - allows specifying the ideal processor for new thread. + - `PS_ATTRIBUTE_UMS_THREAD` - controls user-mode thread scheduling. + - `PS_ATTRIBUTE_ENABLE_OPTIONAL_XSTATE_FEATURES` - controls extended thread context features. + +Check the corresponding pages for more details. + +# Remarks +To avoid retaining unused resources, call `NtClose` to close the returned handle when it is no longer required. + +For the legacy equivalent of this function, see `NtCreateThread`. + +# Related Win32 API + - [`CreateRemoteThreadEx`](https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-createremotethreadex) + +# See also + - `NtCreateThread` + - `RtlCreateUserThread` + - `NtResumeThread` + - `NtOpenThread` + - `NtOpenProcess` + - `NtCreateUserProcess` diff --git a/descriptions/ntcreatethreadstatechange.md b/descriptions/ntcreatethreadstatechange.md index e69de29bb2d..662d60c1e61 100644 --- a/descriptions/ntcreatethreadstatechange.md +++ b/descriptions/ntcreatethreadstatechange.md @@ -0,0 +1,22 @@ +Creates a new thread state object. This object offers a more resilient alternative to suspending threads, tying the duration of the operation to the lifetime of the state object. To change the state of the thread state object, use `NtChangeThreadState`. + +# Parameters + - `ThreadStateChangeHandle` - a pointer to a variable that receives a handle to the new thread state object. + - `DesiredAccess` - the access mask to provide on the returned handle. This value is usually `THREAD_STATE_ALL_ACCESS`. + - `ObjectAttributes` - an optional pointer to an `OBJECT_ATTRIBUTES` structure that specifies attributes of the new object/handle. + - `ThreadHandle` - a handle to the associated thread. The handle must grant `THREAD_SET_INFORMATION` access. + - `Reserved` - this parameter is unused and should be set to zero. + +# Remarks +To avoid retaining unused resources, call `NtClose` to close the returned handle when it is no longer required. When the reference counter on the thread state object drops to zero, the system automatically undoes the effect of the state changes on the associated thread. + +# Related Win32 API +This functionality is not exposed in Win32 API. + +# Required OS version +This function was introduced in Windows 11. + +# See also + - `NtChangeThreadState` + - `NtOpenThread` + - `NtSuspendThread` diff --git a/descriptions/ntcurrentthread.md b/descriptions/ntcurrentthread.md index e69de29bb2d..c74d9a3f90e 100644 --- a/descriptions/ntcurrentthread.md +++ b/descriptions/ntcurrentthread.md @@ -0,0 +1 @@ +This macro is a native equivalent of the [`GetCurrentThread`](https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-getcurrentthread) function. It returns a pseudo-handle that grants `THREAD_ALL_ACCESS` to the current thread. diff --git a/descriptions/ntcurrentthreadid.md b/descriptions/ntcurrentthreadid.md index e69de29bb2d..db93c4704af 100644 --- a/descriptions/ntcurrentthreadid.md +++ b/descriptions/ntcurrentthreadid.md @@ -0,0 +1 @@ +This macro is a native equivalent of the [`GetCurrentThreadId`](https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-getcurrentthreadid) function. diff --git a/descriptions/ntdelayexecution.md b/descriptions/ntdelayexecution.md index b21d822d956..6b4178bed9d 100644 --- a/descriptions/ntdelayexecution.md +++ b/descriptions/ntdelayexecution.md @@ -1,18 +1,22 @@ -### Alertable +Initiates a sleep on the current thread. -If set, execution can break in a result of `NtAlertThread` call. +# Parameters + - `Alertable` - determines whether the sleep should be altertable. This allows external triggers (such as [APCs](https://learn.microsoft.com/en-us/windows/win32/sync/asynchronous-procedure-calls) or calls to `NtAlertThread`) to interrupt sleep prematurely. + - `DelayInterval` - a pointer to a variable that stores the wait internal. A negative value indicates relative timeout for the specified number of 100-nanosecond intervals. To sleep for a specific number of milliseconds, multiply them by `-10,000`. Positive values indicate an absolute time. -### DelayInterval +# Notable return values + - `STATUS_SUCCESS` - the thread woke due to the timeout. + - `STATUS_USER_APC` - the sleep was interrupted by an APC. + - `STATUS_ALERTED` - the sleep was interrupted by a call to `NtAlertThread`. -Delay in 100-ns units. Negative value means delay relative to current. +# Remarks +Despite the name, `NtAlertThreadByThreadId` is unrelated to alertable sleeps and cannot interrupt them. -# Documented by - -* Tomasz Nowak +# Related Win32 API + - [`SleepEx`](https://learn.microsoft.com/en-us/windows/win32/api/synchapi/nf-synchapi-sleepex) # See also - -* `NtAlertThread` -* `NtSignalAndWaitForSingleObject` -* `NtWaitForMultipleObjects` -* `NtWaitForSingleObject` + - `NtWaitForSingleObject` + - `NtWaitForMultipleObjects` + - `NtAlertThread` + - `NtQueueApcThread` diff --git a/descriptions/ntgetcontextthread.md b/descriptions/ntgetcontextthread.md index ab3b2b2603f..bc0e9ecdfc1 100644 --- a/descriptions/ntgetcontextthread.md +++ b/descriptions/ntgetcontextthread.md @@ -1,14 +1,16 @@ -### pContext +Retrieves the context (set of registers) of the specified thread. -See `` for information about `CONTEXT` structure usage. +# Parameters + - `ThreadHandle` - a handle to a thread granting `THREAD_GET_CONTEXT` access. + - `ThreadContext` - a pointer to a `CONTEXT` structure that receives the state of registers. **Note:** make sure to initialize the `ContextFlags` field of the structure with the bit mask defining which portion of the context to query. -# Documented by - -* Tomasz Nowak +# Related Win32 API + - [`GetThreadContext`](https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-getthreadcontext) # See also - -* `NtContinue` -* `NtCreateThread` -* `NtSetContextThread` -* `RtlInitializeContext` + - `RtlCopyContext` + - `RtlGetExtendedContextLength` + - `NtSetContextThread` + - `NtOpenThread` + - `NtQueryInformationThread` + - `NtSetInformationThread` diff --git a/descriptions/ntgetnextthread.md b/descriptions/ntgetnextthread.md index e69de29bb2d..f6d805fed9c 100644 --- a/descriptions/ntgetnextthread.md +++ b/descriptions/ntgetnextthread.md @@ -0,0 +1,31 @@ +This function allows iterating over threads in a process without incurring any race conditions inherent to enumerating or opening threads by ID. Call this function repeatedly to open threads one by one. + +# Parameters + - `ProcessHandle` - a handle to the process which threads should be enumerated. This can either be the `NtCurrentProcess` pseudo-handle or a handle with `PROCESS_QUERY_INFORMATION` access. + - `ThreadHandle` - a handle to the previous thread to continue enumeration from or `NULL` to restart enumeration. + - `DesiredAccess` - the thread access mask expected on the opened handle. + - `HandleAttributes` - flags that control the property of the handle, such as its inheritance (`OBJ_INHERIT`). + - `Flags` - this parameter is unused and should be set to zero. + - `NewThreadHandle` - a pointer to a variable that receives a handle to the opened thread. + +# Access masks +For the list of thread-specific access masks, see `NtOpenThread`. + +# Notable return values + - `STATUS_SUCCESS` - the function opened the next thread. + - `STATUS_NO_MORE_ENTRIES` - the function failed because there are no more accessible threads to enumerate. + +# Remarks +`NtGetNextThread` automatically skips inaccessible threads. In other words, it only enumerates threads for which it can return handles with the specified desired access. However, if there are no threads that can be returned at the start of enumeration (when the input handle is `NULL`), the function returns the error accordingly (usually `STATUS_ACCESS_DENIED`) instead of `STATUS_NO_MORE_ENTRIES`. + +To avoid retaining unused resources, call `NtClose` to close the returned handles when they are no longer required. + +This function bypasses some access checks if the caller has the `SeDebugPrivilege` enabled. + +# Related Win32 API +This functionality is not exposed in Win32 API. + +# See also + - `NtGetNextProcess` + - `NtOpenProcess` + - `NtOpenThread` diff --git a/descriptions/ntopenthread.md b/descriptions/ntopenthread.md index 701e133b7e8..3bdac93abea 100644 --- a/descriptions/ntopenthread.md +++ b/descriptions/ntopenthread.md @@ -1,25 +1,44 @@ -### ThreadHandle - -Pointer to received handle to thread object. - -### AccessMask - -Access mask. See `WinNT.h` for details. - -### ObjectAttributes - -Attributes of thread to open. For standard threads there are empty. - -### ClientId - -Pointer to `CLIENT_ID` structure. Only `UniqueThread` member is required (difference to `NtOpenProcess`). - -# Documented by - -* Tomasz Nowak +Opens a handle to an existing thread. + +# Parameters + - `ThreadHandle` - a pointer to a variable that receives a handle to the thread. + - `DesiredAccess` - the requested access mask. + - `ObjectAttributes` - a pointer to an `OBJECT_ATTRIBUTES` structure that specifies attributes of the handle. Use `InitializeObjectAttributes` to initialize this structure. + - `ClientId` - a pointer to the variable that indicates the client ID of the thread to open. You can omit the process part of the structure by specifying `NULL` in `UniqueProcess`. + +# Access masks + +Access mask | Use +---------------------------------- | ----- +`THREAD_TERMINATE` | Allows terminating the thread via `NtTerminateThread`. +`THREAD_SUSPEND_RESUME` | Allows suspending and resuming the thread via `NtSuspendThread` and `NtResumeThread`, respectively. +`THREAD_ALERT` | Allows waking the thread from an alertable wait via `NtAlertThread`. +`THREAD_GET_CONTEXT` | Allows retrieving the context (set of registers) of the thread via `NtGetContextThread`. +`THREAD_SET_CONTEXT` | Allows changing the context of the thread via `NtSetContextThread` and queuing APCs via `NtQueueApcThread`. +`THREAD_SET_INFORMATION` | Allows setting most information classes via `NtSetInformationThread`. +`THREAD_QUERY_INFORMATION` | Allows querying most information classes via `NtQueryInformationThread`. +`THREAD_SET_THREAD_TOKEN` | Allows setting thread impersonation token via `NtSetInformationThread` with `ThreadImpersonationToken`. +`THREAD_IMPERSONATE` | Allows using the thread as a server during direct impersonation via `NtImpersonateThread`. +`THREAD_DIRECT_IMPERSONATION` | Allows using the thread as a client during direct impersonation via `NtImpersonateThread`. +`THREAD_SET_LIMITED_INFORMATION` | Allows setting some information classes via `NtSetInformationThread`. The system automatically includes this right if the caller requested `THREAD_SET_INFORMATION`. +`THREAD_QUERY_LIMITED_INFORMATION` | Allows querying some information classes via `NtQueryInformationThread`. The system automatically includes this right if the caller requested `THREAD_QUERY_INFORMATION`. +`THREAD_RESUME` | Allows resuming the thread via `NtResumeThread`. The system automatically includes this right if the caller requested `THREAD_SUSPEND_RESUME`. +`THREAD_ALL_ACCESS` | All of the above plus standard rights. + +# Remarks +This function bypasses some access checks if the caller has the `SeDebugPrivilege` enabled. + +To avoid retaining unused resources, call `NtClose` to close the returned handle when it is no longer required. + +Instead of opening the current thread, consider using the `NtCurrentThread` pseudo-handle. + +# Related Win32 API + - [`OpenThread`](https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-openthread) # See also - -* `NtCreateThread` -* `NtOpenProcess` -* `NtTerminateThread` + - `NtCurrentThread` + - `NtQueryInformationThread` + - `NtSetInformationThread` + - `NtResumeThread` + - `NtSuspendThread` + - `NtCreateThreadEx` diff --git a/descriptions/ntqueryinformationthread.md b/descriptions/ntqueryinformationthread.md index b223afeb033..6a9dbaf83df 100644 --- a/descriptions/ntqueryinformationthread.md +++ b/descriptions/ntqueryinformationthread.md @@ -1,36 +1,31 @@ -This function is [documented in Windows SDK](https://learn.microsoft.com/en-us/windows/win32/api/winternl/nf-winternl-ntqueryinformationthread). - ---- - -### ThreadHandle - -Handle to Thread Object opened with `THREAD_QUERY_INFORMATION` access. - -### ThreadInformationClass - -Information class defined in `THREAD_INFORMATION_CLASS` enumerated type. - -### ThreadInformation - -Caller's allocated buffer for results. - -### ThreadInformationLength - -Length of buffer, in bytes. - -### ReturnLength - -Optional pointer to required buffer length. - ---- - -See `THREAD_INFORMATION_CLASS` for more information. - -# Documented by - -* Tomasz Nowak +Queries various information about the specified thread. This function is partially documented in [Windows Driver Kit](https://learn.microsoft.com/en-us/previous-versions/windows/hardware/kernel/mt629133%28v=vs.85%29) and [Winodws SDK](https://learn.microsoft.com/en-us/windows/win32/api/winternl/nf-winternl-ntqueryinformationthread). + +# Parameters + - `ThreadHandle` - a handle to the thread or the `NtCurrentThread` pseudo-handle. For most information classes, the handle must grant either `THREAD_QUERY_INFORMATION` or `THREAD_QUERY_LIMITED_INFORMATION` access. + - `ThreadInformationClass` - the type of information to retrieve. + - `ThreadInformation` - a pointer to user-allocated buffer that receives the requested information. + - `ThreadInformationLength` - the size of the provided buffer in bytes. + - `ReturnLength` - an optional pointer to a variable that receives the number of bytes written when the function succeeds or the number of bytes requires when the buffer is too small. + +# Information classes +For the list of supported info classes and required thread access, see `THREADINFOCLASS`. + +# Notable return values + - `STATUS_BUFFER_TOO_SMALL` and `STATUS_INFO_LENGTH_MISMATCH` indicate that the requested information does not fit into the provided buffer. + +# Related Win32 API + - [`GetThreadInformation`](https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-getthreadinformation) + - [`GetThreadId`](https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-getthreadid) + - [`GetProcessIdOfThread`](https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-getprocessidofthread) + - [`GetExitCodeThread`](https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-getexitcodethread) + - [`GetThreadDescription`](https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-getthreaddescription) + - [`GetThreadIOPendingFlag`](https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-getthreadiopendingflag) + - [`GetThreadPriority`](https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-getthreadpriority) + - [`GetThreadTimes`](https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-getthreadtimes) + - [`Wow64GetThreadContext`](https://learn.microsoft.com/en-us/windows/win32/api/wow64apiset/nf-wow64apiset-wow64getthreadcontext) # See also - -* `NtSetInformationThread` -* `THREAD_INFORMATION_CLASS` + - `NtOpenThread` + - `NtSetInformationThread` + - `NtQueryInformationProcess` + - `NtSetInformationProcess` diff --git a/descriptions/ntqueueapcthread.md b/descriptions/ntqueueapcthread.md index 380f934d205..28f933c0e1a 100644 --- a/descriptions/ntqueueapcthread.md +++ b/descriptions/ntqueueapcthread.md @@ -1,32 +1,27 @@ -### ThreadHandle +Queues a user-mode Asynchronous Procedure Call (APC) on the specified thread. -Open handle to any Thread Object, including caller's thread. +# Parameters + - `ThreadHandle` - a handle the the thread granting the `THREAD_SET_CONTEXT` access. + - `ApcRoutine` - the address of the function to invoke. + - `ApcArgument1` - the first argument to pass to the APC routine. + - `ApcArgument2` - the second argument to pass to the APC routine. + - `ApcArgument3` - the third argument to pass to the APC routine. -### ApcRoutine +# Remarks +To execute the APC, the thread must first enter an alertable wait via `NtDelayExecution` (or a similar function) or call `NtTestAlert`. -Entry point to user *APC* routine. +To queue a WoW64 APC, encode the `ApcRoutine` parameter using the `Wow64EncodeApcRoutine` macro or use `RtlQueueApcWow64Thread`. -### ApcRoutineContext +To specify the reserve object or use special user-mode APCs, see `NtQueueApcThreadEx` and `NtQueueApcThreadEx2`. -User defined parameter for `ApcRoutine`. +Note that user APCs on the Native API level have three parameters in contrast with the [Win32 APCs](https://learn.microsoft.com/en-us/windows/win32/api/winnt/nc-winnt-papcfunc) that only have one. -### ApcStatusBlock - -??? - -### ApcReserved - -??? - ---- - -Function adds user defined routine to thread's APC queue. This routine will be executed when thread will be signaled. You can manually empty APC queue by calling `NtTestAlert`. - -# Documented by - -* Tomasz Nowak +# Related Win32 API + - [`QueueUserAPC`](https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-queueuserapc) # See also - -* `KiUserApcDispatcher` -* `NtTestAlert` + - `NtQueueApcThread` + - `NtQueueApcThreadEx2` + - `RtlQueueApcWow64Thread` + - `NtOpenThread` + - `NtTestAlert` diff --git a/descriptions/ntqueueapcthreadex.md b/descriptions/ntqueueapcthreadex.md index e69de29bb2d..64878802f09 100644 --- a/descriptions/ntqueueapcthreadex.md +++ b/descriptions/ntqueueapcthreadex.md @@ -0,0 +1,30 @@ +Queues a user-mode Asynchronous Procedure Call (APC) on the specified thread. + +# Parameters + - `ThreadHandle` - a handle the the thread granting the `THREAD_SET_CONTEXT` access. + - `ReserveHandle` - an optional handle to the reserve object (see `NtAllocateReserveObject`) or a `QUEUE_USER_APC_SPECIAL_USER_APC` constant. + - `ApcRoutine` - the address of the function to invoke. + - `ApcArgument1` - the first argument to pass to the APC routine. + - `ApcArgument2` - the second argument to pass to the APC routine. + - `ApcArgument3` - the third argument to pass to the APC routine. + +# Remarks +This function has three modes of operation: + +1. When `ReserveHandle` is `NULL`, the function behaves identically to `NtQueueApcThread`. To execute the APC, the thread must first enter an alertable wait via `NtDelayExecution` (or a similar function) or call `NtTestAlert`. +2. When `ReserveHandle` is a handle to the reserve object, the function uses this object to avoid additional memory allocations. Otherwise, the behavior is identical to option 1. +3. When `ReserveHandle` is the `QUEUE_USER_APC_SPECIAL_USER_APC` value, the function queues a *special user-mode APC* that does not require the thread to enter an alertable state. The APC will be executed on the next thread's transition to user mode. This flag is supported on Windows 10 RS5 (1809) and above. Because execution of special APCs is not synchronized with the target thread + +To queue a WoW64 APC, encode the `ApcRoutine` parameter using the `Wow64EncodeApcRoutine` macro or use `RtlQueueApcWow64Thread`. + +Note that user APCs on the Native API level have three parameters in contrast with the [Win32 APCs](https://learn.microsoft.com/en-us/windows/win32/api/winnt/nc-winnt-papcfunc) that only have one. + +# Related Win32 API + - [`QueueUserAPC2`](https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-queueuserapc2) + +# See also + - `NtQueueApcThread` + - `NtQueueApcThreadEx2` + - `RtlQueueApcWow64Thread` + - `NtOpenThread` + - `NtTestAlert` diff --git a/descriptions/ntqueueapcthreadex2.md b/descriptions/ntqueueapcthreadex2.md index e69de29bb2d..41904f83fb6 100644 --- a/descriptions/ntqueueapcthreadex2.md +++ b/descriptions/ntqueueapcthreadex2.md @@ -0,0 +1,33 @@ +Queues a user-mode Asynchronous Procedure Call (APC) on the specified thread. + +# Parameters + - `ThreadHandle` - a handle the the thread granting the `THREAD_SET_CONTEXT` access. + - `ReserveHandle` - an optional handle to the reserve object (see `NtAllocateReserveObject`) to avoid memory allocations. + - `ApcFlags` - the flags that control properties of the APC. + - `ApcRoutine` - the address of the function to invoke. + - `ApcArgument1` - the first argument to pass to the APC routine. + - `ApcArgument2` - the second argument to pass to the APC routine. + - `ApcArgument3` - the third argument to pass to the APC routine. + +# Supported flags + - `QUEUE_USER_APC_FLAGS_NONE` - indicates that none of the flags listed below are used. The behavior defaults to regular APCs that require the thread to first enter an alertable wait via `NtDelayExecution` (or a similar function) or call `NtTestAlert`. + - `QUEUE_USER_APC_FLAGS_SPECIAL_USER_APC` - queue a *special user-mode APC* that does not require the thread to enter an alertable state. The APC will be executed on the next thread's transition to user mode. + - `QUEUE_USER_APC_CALLBACK_DATA_CONTEXT` - let the callback routine receive the context (set of registers) that was interrupted when the thread was directed to call the APC function. + +# Remarks +To queue a WoW64 APC, encode the `ApcRoutine` parameter using the `Wow64EncodeApcRoutine` macro or use `RtlQueueApcWow64Thread`. + +Note that user APCs on the Native API level have three parameters in contrast with the [Win32 APCs](https://learn.microsoft.com/en-us/windows/win32/api/winnt/nc-winnt-papcfunc) that only have one. + +# Related Win32 API + - [`QueueUserAPC2`](https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-queueuserapc2) + +# Required OS version +This function was introduced in Windows 11. + +# See also + - `NtQueueApcThread` + - `NtQueueApcThreadEx2` + - `RtlQueueApcWow64Thread` + - `NtOpenThread` + - `NtTestAlert` diff --git a/descriptions/ntresumethread.md b/descriptions/ntresumethread.md index c21ada1d3cd..c79cc00b407 100644 --- a/descriptions/ntresumethread.md +++ b/descriptions/ntresumethread.md @@ -1,12 +1,14 @@ -See `AlertResumeThread`. +Resumes a previously suspended thread. -# Documented by +# Parameters + - `ThreadHandle` - a handle to a thread granting either `THREAD_SUSPEND_RESUME` or `THREAD_RESUME` access. + - `PreviousSuspendCount` - an optional pointer to a variable that receives the previous value of the suspension counter of the thread. -* Tomasz Nowak -* ReactOS +# Related Win32 API + - [`ResumeThread`](https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-resumethread) # See also - -* `NtAlertResumeThread` -* `NtCreateThread` -* `NtSuspendThread` + - `NtOpenThread` + - `NtSuspendThread` + - `NtSuspendProcess` + - `NtResumeProcess` diff --git a/descriptions/ntsetcontextthread.md b/descriptions/ntsetcontextthread.md index f22ac826796..43e3640c640 100644 --- a/descriptions/ntsetcontextthread.md +++ b/descriptions/ntsetcontextthread.md @@ -1,18 +1,16 @@ -### ThreadHandle +Changes the context of the specified thread. -Handle to Thread Object opened with `THREAD_SET_CONTEXT` access flag. +# Parameters + - `ThreadHandle` - a handle to a thread granting `THREAD_SET_CONTEXT` access. + - `ThreadContext` - a pointer to a `CONTEXT` structure that contains the context to be set in the specified thread. **Note:** the value of the `ContextFlags` field specifies which portions of a thread's context to set. -### Context - -Context to set to thread. - -# Documented by - -* Tomasz Nowak +# Related Win32 API + - [`SetThreadContext`](https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-setthreadcontext) # See also - -* `NtContinue` -* `NtCreateThread` -* `NtGetContextThread` -* `RtlInitializeContext` + - `NtGetContextThread` + - `RtlCopyContext` + - `RtlGetExtendedContextLength` + - `NtOpenThread` + - `NtQueryInformationThread` + - `NtSetInformationThread` diff --git a/descriptions/ntsetinformationthread.md b/descriptions/ntsetinformationthread.md index e03db764274..3aaec15c456 100644 --- a/descriptions/ntsetinformationthread.md +++ b/descriptions/ntsetinformationthread.md @@ -1,32 +1,25 @@ -This function is documented in Windows Driver Kit [here](https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/ntddk/nf-ntddk-zwsetinformationthread) and [here](https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/ntifs/nf-ntifs-ntsetinformationthread). - ---- - -### ThreadHandle - -Handle to Thread Object opened with `THREAD_SET_INFORMATION` access. - -### ThreadInformationClass - -Information class to set to. See `THREAD_INFORMATION_CLASS` for detailed description of use. - -### ThreadInformation - -Pointer to value to set. - -### ThreadInformationLength - -Length of value to set. - ---- - -See `THREAD_INFORMATION_CLASS` for more information. - -# Documented by - -* Tomasz Nowak +Sets various information about the specified thread. This function is partially documented in Windows Driver Kit [here](https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/ntddk/nf-ntddk-zwsetinformationthread) and [here](https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/ntifs/nf-ntifs-ntsetinformationthread). + +# Parameters + - `ThreadHandle` - a handle to the thread or the `NtCurrentThread` pseudo-handle. For most information classes, the handle must grant either `THREAD_SET_INFORMATION` or `THREAD_SET_LIMITED_INFORMATION` access. + - `ThreadInformationClass` - the type of information to set. + - `ThreadInformation` - a pointer to the buffer with the data specific to the request. + - `ThreadInformationLength` - the size of the provided buffer in bytes. + +# Information classes +For the list of supported info classes and required thread access, see `THREADINFOCLASS`. + +# Related Win32 API + - [`SetThreadInformation`](https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-setthreadinformation) + - [`SetThreadIdealProcessor`](https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-setthreadidealprocessor) + - [`SetThreadIdealProcessorEx`](https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-setthreadidealprocessorex) + - [`SetThreadDescription`](https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-setthreaddescription) + - [`SetThreadPriorityBoost`](https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-setthreadpriorityboost) + - [`SetThreadToken`](https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-setthreadtoken) + - [`Wow64SetThreadContext`](https://learn.microsoft.com/en-us/windows/win32/api/wow64apiset/nf-wow64apiset-wow64setthreadcontext) # See also - -* `NtQueryInformationThread` -* `THREAD_INFORMATION_CLASS` + - `NtOpenThread` + - `NtQueryInformationThread` + - `NtQueryInformationProcess` + - `NtSetInformationProcess` diff --git a/descriptions/ntsetthreadexecutionstate.md b/descriptions/ntsetthreadexecutionstate.md index e69de29bb2d..4bfeec2a9ea 100644 --- a/descriptions/ntsetthreadexecutionstate.md +++ b/descriptions/ntsetthreadexecutionstate.md @@ -0,0 +1,21 @@ +Sets the execution state for the current thread and manages the corresponding power requests that prevent the system from dimming the display or entering sleep. + +# Parameters + - `NewFlags` - a bit mask containing flags that + - `PreviousFlags` - a pointer to a variable that receives the previous execution state. + +# Supported flags + - `ES_SYSTEM_REQUIRED` - prevents the system from going to sleep. + - `ES_DISPLAY_REQUIRED` - forces the display to be on. + - `ES_USER_PRESENT` - this flag is not supported. + - `ES_AWAYMODE_REQUIRED` - enables the away mode that allows the computer appear to be sleeping while being active, + - `ES_CONTINUOUS` - the state should remain in effect until the next call that uses this flag. + +# Remarks +You can view the power requests created via this and other APIs via `powercfg /requests`. + +# Related Win32 API + - [`SetThreadExecutionState`](https://learn.microsoft.com/en-us/windows/win32/api/winbase/nf-winbase-setthreadexecutionstate + +# See also + - `NtPowerInformation` diff --git a/descriptions/ntsuspendthread.md b/descriptions/ntsuspendthread.md index cad778c6c38..44a4533eec9 100644 --- a/descriptions/ntsuspendthread.md +++ b/descriptions/ntsuspendthread.md @@ -1,13 +1,15 @@ -### PreviousSuspendCount +Suspends a thread. -Suspend count for `ThreadHandle` thread before function call. +# Parameters + - `ThreadHandle` - a handle to a thread granting `THREAD_SUSPEND_RESUME` access. + - `PreviousSuspendCount` - an optional pointer to a variable that receives the previous value of the suspension counter of the thread. -# Documented by - -* ReactOS -* Tomasz Nowak +# Related Win32 API + - [`SuspendThread`](https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-suspendthread) # See also - -* `NtAlertResumeThread` -* `NtResumeThread` + - `NtOpenThread` + - `NtResumeThread` + - `NtSuspendProcess` + - `NtResumeProcess` + - `NtDelayExecution` diff --git a/descriptions/ntterminatethread.md b/descriptions/ntterminatethread.md index 3d00193970e..4ee419a234a 100644 --- a/descriptions/ntterminatethread.md +++ b/descriptions/ntterminatethread.md @@ -1,17 +1,17 @@ -### ThreadHandle +Forcefully terminates a thread. -Open handle to thread object. +# Parameters + - `ThreadHandle` - a handle to a thread granting `THREAD_TERMINATE` access. If this value is `NULL`, the calling thread is terminated. + - `ExitStatus` - the value to set as the exist status of the thread. -### ExitStatus +# Notable return values + - `STATUS_CANT_TERMINATE_SELF` - indicates that a thread attempted to terminate itself by default (called `NtTerminateThread` with `NULL`) and it was the last thread in the current process. -Result of thread, as `NTSTATUS`. - -# Documented by - -* Tomasz Nowak +# Related Win32 API + - [`TerminateThread`](https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-terminatethread) # See also - -* `NtCreateThread` -* `NtOpenThread` -* `NtTerminateProcess` + - `RtlExitUserThread` + - `NtOpenThread` + - `NtSuspendThread` + - `NtTerminateProcess` diff --git a/descriptions/ntwaitforalertbythreadid.md b/descriptions/ntwaitforalertbythreadid.md index e69de29bb2d..5f9a5b37fdc 100644 --- a/descriptions/ntwaitforalertbythreadid.md +++ b/descriptions/ntwaitforalertbythreadid.md @@ -0,0 +1,21 @@ +Waits on the specified address to be alerted-by-ID by another thread. + +# Parameters + - `Address` - the user-provided value that serves as a key. + - `Timeout` - an optional pointer to a timeout for the wait. A negative value indicates relative timeout for the specified number of 100-nanosecond intervals. To wait for a specific number of milliseconds, multiply them by `-10,000`. Positive values indicate an absolute time.` + +# Notable return values + - `STATUS_ALERTED` - the thread woke due to a call to `NtAlertThreadByThreadId`. + - `STATUS_TIMEOUT` - the thread woke due to the timeout. + +# Remarks +Despite the name, the wait this function enters is not alertable and, thus, cannot be interrupted by APCs or `NtAlertThread`. Alertable waits via `NtDelayExecution` are unrelated to this functionality. + +# Related Win32 API + - [`WaitOnAddress`](https://learn.microsoft.com/en-us/windows/win32/api/synchapi/nf-synchapi-waitonaddress) + +# Required OS version +This function was introduced in Windows 8. + +# See also + - `NtAlertThreadByThreadId` diff --git a/descriptions/pps_apc_routine.md b/descriptions/pps_apc_routine.md index e69de29bb2d..562ee9bcea7 100644 --- a/descriptions/pps_apc_routine.md +++ b/descriptions/pps_apc_routine.md @@ -0,0 +1,10 @@ +This prototype defines the function to use as an [APC](https://learn.microsoft.com/en-us/windows/win32/sync/asynchronous-procedure-calls) routine. + +# Applicable to + - `NtQueueApcThread` + - `NtQueueApcThreadEx` + - `NtQueueApcThreadEx2` + - `RtlQueueApcWow64Thread` + +# Remarks +Note that user APCs on the Native API level have three parameters in contrast with the [Win32 APCs](https://learn.microsoft.com/en-us/windows/win32/api/winnt/nc-winnt-papcfunc) that only have one. diff --git a/descriptions/ps_attribute.md b/descriptions/ps_attribute.md index e69de29bb2d..d993beab25a 100644 --- a/descriptions/ps_attribute.md +++ b/descriptions/ps_attribute.md @@ -0,0 +1,15 @@ +This structure defines a process or thread creation attribute. + +# Members + - `Attribute` - a numerical identifier of the type of entry. + - `Size` - the size of the value in bytes. + - `Value`/`ValuePtr` - the additional input/output data attached to the attribute either in-place or as a pointer to a buffer. + - `ReturnLength` - an optional pointer to a variable that receives the number of bytes that has been written to the buffer (for attributes that return data). + +# Known attributes +For the list of know attributes, see the documentation of `PS_ATTRIBUTE_NUM`. + +# See also + - `PS_ATTRIBUTE_LIST` + - `NtCreateThreadEx` + - `NtCreateUserProcess` diff --git a/descriptions/ps_attribute_client_id.md b/descriptions/ps_attribute_client_id.md index e69de29bb2d..0229e15659c 100644 --- a/descriptions/ps_attribute_client_id.md +++ b/descriptions/ps_attribute_client_id.md @@ -0,0 +1,15 @@ +This attribute allows the caller to request the client ID of the new thread to be returned upon its creation. + +# Parameters + - `Attribute` - `PS_ATTRIBUTE_CLIENT_ID` (numeric value `0x10003`). + - `Size` - `sizeof(CLIEND_ID)`. + - `ValuePtr` - a pointer to a `CLIEND_ID` buffer that receives the ID of the new thread. + +# Applicable to + - `NtCreateThreadEx` + - `NtCreateUserProcess` + +# See also + - `CLIEND_ID` + - `NtOpenThread` + - `PS_ATTRIBUTE_NUM` diff --git a/descriptions/ps_attribute_list.md b/descriptions/ps_attribute_list.md index e69de29bb2d..df7cf882504 100644 --- a/descriptions/ps_attribute_list.md +++ b/descriptions/ps_attribute_list.md @@ -0,0 +1,11 @@ +This structure defines a list of process or thread creation attributes. + +# Members + - `TotalLength` - the size of the entire structure in bytes, including the header. To store `N` attributes, the value should be `sizeof(PS_ATTRIBUTE_LIST) + (N - 1) * sizeof(PS_ATTRIBUTE)` due to the header including one attribute by default. + - `Attributes` - the array of `PS_ATTRIBUTE` structures. + +# See also + - `PS_ATTRIBUTE` + - `PS_ATTRIBUTE_NUM` + - `NtCreateThreadEx` + - `NtCreateUserProcess` diff --git a/descriptions/ps_attribute_num.md b/descriptions/ps_attribute_num.md index e69de29bb2d..e194ee18e71 100644 --- a/descriptions/ps_attribute_num.md +++ b/descriptions/ps_attribute_num.md @@ -0,0 +1,42 @@ +This enumeration defines indexes for process and thread creation attributes. The `PsAttributeValue` macro is used convert them into usable attribute values. + +# Known attributes + - `PS_ATTRIBUTE_PARENT_PROCESS` - specifies the handle to the parent process during process creation. + - `PS_ATTRIBUTE_DEBUG_OBJECT` - specifies the handle to the debug object to attach to the new process. + - `PS_ATTRIBUTE_TOKEN` - specifies the token to the use as the primary token of the new process. + - `PS_ATTRIBUTE_CLIENT_ID` - allows retrieving the client ID of the new/initial thread. + - `PS_ATTRIBUTE_TEB_ADDRESS` - allows retrieving the `TEB` address of the new/initial thread. + - `PS_ATTRIBUTE_IMAGE_NAME` - provides an NT filename of the executable image to use for the new process. + - `PS_ATTRIBUTE_IMAGE_INFO` - allows retrieving information about the executable image used during process creation. + - `PS_ATTRIBUTE_MEMORY_RESERVE` + - `PS_ATTRIBUTE_PRIORITY_CLASS` + - `PS_ATTRIBUTE_ERROR_MODE` - sets the default error mode for the process. + - `PS_ATTRIBUTE_STD_HANDLE_INFO` - specifies which standard (console) handles to inherit in the new process. + - `PS_ATTRIBUTE_HANDLE_LIST` - indicates a subset of inheritable handles to be inherited by the new process. + - `PS_ATTRIBUTE_GROUP_AFFINITY` + - `PS_ATTRIBUTE_PREFERRED_NODE` + - `PS_ATTRIBUTE_IDEAL_PROCESSOR` - allows specifying the ideal processor for new thread. + - `PS_ATTRIBUTE_UMS_THREAD` - controls user-mode thread scheduling. + - `PS_ATTRIBUTE_MITIGATION_OPTIONS` - controls which mitigation policies should be applied to the new process. + - `PS_ATTRIBUTE_PROTECTION_LEVEL` - specifies which the protection level to use when creating protected/PPL processes. + - `PS_ATTRIBUTE_SECURE_PROCESS` + - `PS_ATTRIBUTE_JOB_LIST` - specifies the list of handles to job objects to put the new process into. + - `PS_ATTRIBUTE_CHILD_PROCESS_POLICY` - specifies whether the new process should be allowed to create child processes. + - `PS_ATTRIBUTE_ALL_APPLICATION_PACKAGES_POLICY` - specifies whether the new process should run in LPAC sandbox. + - `PS_ATTRIBUTE_WIN32K_FILTER` + - `PS_ATTRIBUTE_SAFE_OPEN_PROMPT_ORIGIN_CLAIM` - specifies safe origin claims; used by SmartScreen. + - `PS_ATTRIBUTE_BNO_ISOLATION` - controls BNO isolation for the new process. + - `PS_ATTRIBUTE_DESKTOP_APP_POLICY` + - `PS_ATTRIBUTE_CHPE` - controls CHPE settings on ARM machines. + - `PS_ATTRIBUTE_MITIGATION_AUDIT_OPTIONS` + - `PS_ATTRIBUTE_MACHINE_TYPE` + - `PS_ATTRIBUTE_COMPONENT_FILTER` + - `PS_ATTRIBUTE_ENABLE_OPTIONAL_XSTATE_FEATURES` - controls extended thread context features. + +Check the corresponding pages for more details. + +# See also + - `PS_ATTRIBUTE` + - `PS_ATTRIBUTE_LIST` + - `NtCreateThreadEx` + - `NtCreateUserProcess` diff --git a/descriptions/ps_attribute_teb_address.md b/descriptions/ps_attribute_teb_address.md index e69de29bb2d..c6c604cda21 100644 --- a/descriptions/ps_attribute_teb_address.md +++ b/descriptions/ps_attribute_teb_address.md @@ -0,0 +1,15 @@ +This attribute allows the caller to request the `TEB` address of the new thread to be returned upon its creation. + +# Parameters + - `Attribute` - `PS_ATTRIBUTE_TEB_ADDRESS` (numeric value `0x10004`). + - `Size` - `sizeof(PVOID)`. + - `ValuePtr` - a pointer to a `PTEB` variable that receives the `TEB` address of the new thread. + +# Applicable to + - `NtCreateThreadEx` + - `NtCreateUserProcess` + +# See also + - `TEB` + - `PS_ATTRIBUTE_NUM` + - `NtCurrentTeb` diff --git a/descriptions/psattributevalue.md b/descriptions/psattributevalue.md index e69de29bb2d..538de6743c8 100644 --- a/descriptions/psattributevalue.md +++ b/descriptions/psattributevalue.md @@ -0,0 +1,43 @@ +This macro allows constructing a process/thread creation attribute value based on its index. + +# Known values + - `PS_ATTRIBUTE_PARENT_PROCESS` = 0x60000; + - `PS_ATTRIBUTE_DEBUG_PORT` = 0x60001; + - `PS_ATTRIBUTE_TOKEN` = 0x60002; + - `PS_ATTRIBUTE_CLIENT_ID` = 0x10003; + - `PS_ATTRIBUTE_TEB_ADDRESS` = 0x10004; + - `PS_ATTRIBUTE_IMAGE_NAME` = 0x20005; + - `PS_ATTRIBUTE_IMAGE_INFO` = 0x00006; + - `PS_ATTRIBUTE_MEMORY_RESERVE` = 0x20007; + - `PS_ATTRIBUTE_PRIORITY_CLASS` = 0x20008; + - `PS_ATTRIBUTE_ERROR_MODE` = 0x20009; + - `PS_ATTRIBUTE_STD_HANDLE_INFO` = 0x2000A; + - `PS_ATTRIBUTE_HANDLE_LIST` = 0x2000B; + - `PS_ATTRIBUTE_GROUP_AFFINITY` = 0x3000C; + - `PS_ATTRIBUTE_PREFERRED_NODE` = 0x2000D; + - `PS_ATTRIBUTE_IDEAL_PROCESSOR` = 0x3000E; + - `PS_ATTRIBUTE_UMS_THREAD` = 0x3000F; + - `PS_ATTRIBUTE_MITIGATION_OPTIONS` = 0x20010; + - `PS_ATTRIBUTE_PROTECTION_LEVEL` = 0x60011; + - `PS_ATTRIBUTE_SECURE_PROCESS` = 0x20012; + - `PS_ATTRIBUTE_JOB_LIST` = 0x20013; + - `PS_ATTRIBUTE_CHILD_PROCESS_POLICY` = 0x20014; + - `PS_ATTRIBUTE_ALL_APPLICATION_PACKAGES_POLICY` = 0x20015; + - `PS_ATTRIBUTE_WIN32K_FILTER` = 0x20016; + - `PS_ATTRIBUTE_SAFE_OPEN_PROMPT_ORIGIN_CLAIM` = 0x20017; + - `PS_ATTRIBUTE_BNO_ISOLATION` = 0x20018; + - `PS_ATTRIBUTE_DESKTOP_APP_POLICY` = 0x20019; + - `PS_ATTRIBUTE_CHPE` = 0x6001A; + - `PS_ATTRIBUTE_MITIGATION_AUDIT_OPTIONS` = 0x2001B; + - `PS_ATTRIBUTE_MACHINE_TYPE` = 0x6001C; + - `PS_ATTRIBUTE_COMPONENT_FILTER` = 0x2001D; + - `PS_ATTRIBUTE_ENABLE_OPTIONAL_XSTATE_FEATURES` = 0x3001E; + +Check the corresponding pages for more details. + +# See also + - `PS_ATTRIBUTE` + - `PS_ATTRIBUTE_LIST` + - `PS_ATTRIBUTE_NUM` + - `NtCreateThreadEx` + - `NtCreateUserProcess` diff --git a/descriptions/puser_thread_start_routine.md b/descriptions/puser_thread_start_routine.md index e69de29bb2d..58d846938c2 100644 --- a/descriptions/puser_thread_start_routine.md +++ b/descriptions/puser_thread_start_routine.md @@ -0,0 +1,5 @@ +This prototype defines the function to use as a thread main routine. + +# Applicable to + - `NtCreateThreadEx` + - `RtlCreateUserThread` diff --git a/descriptions/queue_user_apc_callback_data_context.md b/descriptions/queue_user_apc_callback_data_context.md index e69de29bb2d..8844e0288af 100644 --- a/descriptions/queue_user_apc_callback_data_context.md +++ b/descriptions/queue_user_apc_callback_data_context.md @@ -0,0 +1,11 @@ +This flags indicates that the callback routine should receive the context (set of registers) that was interrupted when the thread was directed to call the APC function. The the documentation for [the corresponding Win32 flags](https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/ne-processthreadsapi-queue_user_apc_flags) for more details. + +# Applicable to + - `NtQueueApcThreadEx2` + +# Related flags + - `QUEUE_USER_APC_FLAGS_NONE` + - `QUEUE_USER_APC_FLAGS_SPECIAL_USER_APC` + +# Required OS version +This flag was introduced in Windows 11. diff --git a/descriptions/queue_user_apc_flags_none.md b/descriptions/queue_user_apc_flags_none.md index e69de29bb2d..c782646076a 100644 --- a/descriptions/queue_user_apc_flags_none.md +++ b/descriptions/queue_user_apc_flags_none.md @@ -0,0 +1,11 @@ +This flags indicates the absence of other APC flags. The behavior defaults to regular APCs that require the thread to first enter an alertable wait via `NtDelayExecution` (or a similar function) or call `NtTestAlert`. + +# Applicable to + - `NtQueueApcThreadEx2` + +# Related flags + - `QUEUE_USER_APC_FLAGS_SPECIAL_USER_APC` + - `QUEUE_USER_APC_CALLBACK_DATA_CONTEXT` + +# Required OS version +This flag was introduced in Windows 11. diff --git a/descriptions/queue_user_apc_flags_special_user_apc.md b/descriptions/queue_user_apc_flags_special_user_apc.md index e69de29bb2d..7a1677b9c84 100644 --- a/descriptions/queue_user_apc_flags_special_user_apc.md +++ b/descriptions/queue_user_apc_flags_special_user_apc.md @@ -0,0 +1,14 @@ +This flags indicates the use of a *special user-mode APC* that does not require the thread to enter an alertable state. The APC will be executed on the next thread's transition to user mode. + +# Applicable to + - `NtQueueApcThreadEx2` + +# Related flags + - `QUEUE_USER_APC_FLAGS_NONE` + - `QUEUE_USER_APC_CALLBACK_DATA_CONTEXT` + +# Remarks +For the introduction to special user-mode APCs, see [this blog post](https://repnz.github.io/posts/apc/user-apc/#ntqueueapcthreadex-meet-special-user-apc). + +# Required OS version +This flag was introduced in Windows 11. diff --git a/descriptions/queue_user_apc_special_user_apc.md b/descriptions/queue_user_apc_special_user_apc.md index e69de29bb2d..d4f898cc616 100644 --- a/descriptions/queue_user_apc_special_user_apc.md +++ b/descriptions/queue_user_apc_special_user_apc.md @@ -0,0 +1,10 @@ +This constant defines a special value for `ReserveHandle` that allows queuing *special user-mode APCs*. + +# Applicable to + - `NtQueueApcThreadEx` + +# Remarks +For the introduction to special user-mode APCs, see [this blog post](https://repnz.github.io/posts/apc/user-apc/#ntqueueapcthreadex-meet-special-user-apc). + +# Required OS version +This flag was introduced in Windows 10 RS5 (1809). diff --git a/descriptions/rtlcreateuserthread.md b/descriptions/rtlcreateuserthread.md index dcd7cb7ee0b..7c69d724afb 100644 --- a/descriptions/rtlcreateuserthread.md +++ b/descriptions/rtlcreateuserthread.md @@ -1,18 +1,30 @@ -### StackZeroBits +Creates a new thread in the specified process. -How many older bits must be clear while allocating thread stack. See `INITIAL_TEB`. +# Parameters + - `ProcessHandle` - a handle to the process where the thread should be created. This can either be the `NtCurrentProcess` pseudo-handle or a handle with `PROCESS_CREATE_THREAD` access. + - `ThreadSecurityDescriptor` - a security descriptor to protect the new thread with. + - `CreateSuspended` - whether the new thread should be created in a suspended state or allowed to run immediately. When specifying `TRUE`, you can use `NtResumeThread` to resume the thread later. + - `ZeroBits` - the number of high-order address bits that must be zero in the base address of the thread's stack. Note that when the value is larger than 32, it becomes a bit mask. + - `MaximumStackSize` - the maximum size of the stack, in bytes. The system rounds this value up to the nearest page. If this parameter is zero, the new thread uses the default size for the executable. + - `CommittedStackSize` - the initial size of the stack, in bytes. The system rounds this value up to the nearest page. If this parameter is zero, the new thread uses the default size for the executable. + - `StartAddress` - the function to execute on the new thread. + - `Parameter` - a user-provided argument to pass to the thread start routine. + - `ThreadHandle` - an optional pointer to a variable that receives a handle to the new thread. + - `ClientId` - an optional pointer to a variable that receives the client ID of the new thread. -### StartAddress +# Remarks +To avoid retaining unused resources, call `NtClose` to close the returned handle when it is no longer required. -Thread start routine address. +# Implementation details +This function is a wrapper over `NtCreateThreadEx`. -# Documented by - -* ReactOS -* Tomasz Nowak +# Related Win32 API + - [`CreateRemoteThreadEx`](https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-createremotethreadex) # See also - -* `INITIAL_TEB` -* `NtCreateThread` -* `NtTerminateThread` + - `NtCreateThreadEx` + - `NtCreateThread` + - `NtResumeThread` + - `NtOpenThread` + - `NtOpenProcess` + - `RtlCreateUserProcess` diff --git a/descriptions/rtlexituserthread.md b/descriptions/rtlexituserthread.md index e69de29bb2d..30a7c4ef3aa 100644 --- a/descriptions/rtlexituserthread.md +++ b/descriptions/rtlexituserthread.md @@ -0,0 +1,12 @@ +Gracefully ends the current thread. + +# Parameters + - `ExitStatus` - the value to set as the exist status of the thread. + +# Related Win32 API + - [`ExitThread`](https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-exitthread) + +# See also + - `RtlExitUserProcess` + - `NtTerminateThread` + - `NtTerminateProcess` diff --git a/descriptions/rtlgetthreaderrormode.md b/descriptions/rtlgetthreaderrormode.md index e69de29bb2d..af49778309b 100644 --- a/descriptions/rtlgetthreaderrormode.md +++ b/descriptions/rtlgetthreaderrormode.md @@ -0,0 +1,10 @@ +Returns the error mode for the current thread. The value controls how the system should handle serious errors. + +# Implementation details +This function reads the `HardErrorMode` field from `TEB`. + +# Related Win32 API + - [`GetThreadErrorMode`](https://learn.microsoft.com/en-us/windows/win32/api/errhandlingapi/nf-errhandlingapi-getthreaderrormode) + +# See also + - `RtlSetThreadErrorMode` diff --git a/descriptions/rtliscurrentthread.md b/descriptions/rtliscurrentthread.md index e69de29bb2d..03d9460b4b7 100644 --- a/descriptions/rtliscurrentthread.md +++ b/descriptions/rtliscurrentthread.md @@ -0,0 +1,14 @@ +Determines whether the specified handle is a handle to the current thread. + +# Parameters + - `ThreadHandle` - a thread handle with any access mask. + +# Implementation details +This function is a wrapper over `NtCompareObjects`. + +# Related Win32 API +This functionality is not exposed in Win32 API. + +# See also + - `NtCompareObjects` + - `NtOpenThread` diff --git a/descriptions/rtliscurrentthreadattachexempt.md b/descriptions/rtliscurrentthreadattachexempt.md index e69de29bb2d..17cd4a376cb 100644 --- a/descriptions/rtliscurrentthreadattachexempt.md +++ b/descriptions/rtliscurrentthreadattachexempt.md @@ -0,0 +1,11 @@ +Determines whether the current thread is supposed to skip calling [DllMain](https://learn.microsoft.com/en-us/windows/win32/dlls/dllmain) with `DLL_THREAD_ATTACH` reason on loaded modules. + +# Implementation details +The function checks for `SkipThreadAttach` and `RanProcessInit` flags in `TEB`. + +# Related Win32 API +This functionality is not exposed in Win32 API. + +# See also + - `THREAD_CREATE_FLAGS_SKIP_THREAD_ATTACH` + - `LDRP_DONT_CALL_FOR_THREADS` diff --git a/descriptions/rtlqueueapcwow64thread.md b/descriptions/rtlqueueapcwow64thread.md index e69de29bb2d..8192990407a 100644 --- a/descriptions/rtlqueueapcwow64thread.md +++ b/descriptions/rtlqueueapcwow64thread.md @@ -0,0 +1,28 @@ +Queues a WoW64 user-mode Asynchronous Procedure Call (APC) on the specified thread. + +# Parameters + - `ThreadHandle` - a handle the the thread granting the `THREAD_SET_CONTEXT` access. + - `ApcRoutine` - the WoW64 address of the function to invoke. + - `ApcArgument1` - the first argument to pass to the APC routine. + - `ApcArgument2` - the second argument to pass to the APC routine. + - `ApcArgument3` - the third argument to pass to the APC routine. + +# Remarks +To execute the APC, the thread must first enter an alertable wait via `NtDelayExecution` (or a similar function) or call `NtTestAlert`. Note that user APCs on the Native API level have three parameters in contrast with the Win32 APCs that only have one. + +To specify the reserve object or use special user-mode APCs, see `NtQueueApcThreadEx` and `NtQueueApcThreadEx2`. + +Note that user APCs on the Native API level have three parameters in contrast with the [Win32 APCs](https://learn.microsoft.com/en-us/windows/win32/api/winnt/nc-winnt-papcfunc) that only have one. + +# Implementation details +This function uses `Wow64EncodeApcRoutine` and then calls `NtQueueApcThread`. + +# Related Win32 API + - [`QueueUserAPC`](https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-queueuserapc) + +# See also + - `NtQueueApcThread` + - `NtQueueApcThreadEx` + - `NtQueueApcThreadEx2` + - `NtOpenThread` + - `NtTestAlert` diff --git a/descriptions/rtlsetthreaderrormode.md b/descriptions/rtlsetthreaderrormode.md index e69de29bb2d..17554b22b8a 100644 --- a/descriptions/rtlsetthreaderrormode.md +++ b/descriptions/rtlsetthreaderrormode.md @@ -0,0 +1,20 @@ +Changes the error mode for the current thread. The value controls how the system should handle serious errors. + +# Parameters + - `NewMode` - a bit mask with flags defining the new behavior. + - `OldMode` - a pointer to a variable that receives the previous error mode. + +# Supported flags + - `SEM_FAILCRITICALERRORS` - the system does not display the dialog on critical errors and lets the thread handle them. + - `SEM_NOGPFAULTERRORBOX` - The system does not display the Windows Error Reporting dialog. + - `SEM_NOALIGNMENTFAULTEXCEPT` - automatically fix alignment faults. + - `SEM_NOOPENFILEERRORBOX` - OpenFile does not display a message box when it fails to find a file. + +# Implementation details +This function sets the `HardErrorMode` field in `TEB`. + +# Related Win32 API + - [`SetThreadErrorMode`](https://learn.microsoft.com/en-us/windows/win32/api/errhandlingapi/nf-errhandlingapi-setthreaderrormode) + +# See also + - `RtlGetThreadErrorMode` diff --git a/descriptions/thread_create_flags_bypass_process_freeze.md b/descriptions/thread_create_flags_bypass_process_freeze.md index e69de29bb2d..3f4075a1b81 100644 --- a/descriptions/thread_create_flags_bypass_process_freeze.md +++ b/descriptions/thread_create_flags_bypass_process_freeze.md @@ -0,0 +1,16 @@ +This flags indicates that the thread should not be suspended when the system suspends or freezes the process. See [this post](https://secret.club/2021/01/04/thread-stuff.html) for more details about the flag. For the differences between suspension, freezing, and deep freezing, see [this repository](https://github.com/diversenok/Suspending-Techniques). + +# Applicable to + - `NtCreateThreadEx` + +# Related flags + - `THREAD_CREATE_FLAGS_NONE` + - `THREAD_CREATE_FLAGS_CREATE_SUSPENDED` + - `THREAD_CREATE_FLAGS_SKIP_THREAD_ATTACH` + - `THREAD_CREATE_FLAGS_HIDE_FROM_DEBUGGER` + - `THREAD_CREATE_FLAGS_LOADER_WORKER` + - `THREAD_CREATE_FLAGS_SKIP_LOADER_INIT` + +# See also + - `NtSuspendProcess` + - `NtResumeProcess` diff --git a/descriptions/thread_create_flags_create_suspended.md b/descriptions/thread_create_flags_create_suspended.md index e69de29bb2d..73617b809af 100644 --- a/descriptions/thread_create_flags_create_suspended.md +++ b/descriptions/thread_create_flags_create_suspended.md @@ -0,0 +1,17 @@ +This flags indicates that the thread should be created in a suspended state instead of being allowed to execute immediately. + +# Applicable to + - `NtCreateThreadEx` + - `NtCreateUserProcess` + +# Related flags + - `THREAD_CREATE_FLAGS_NONE` + - `THREAD_CREATE_FLAGS_SKIP_THREAD_ATTACH` + - `THREAD_CREATE_FLAGS_HIDE_FROM_DEBUGGER` + - `THREAD_CREATE_FLAGS_LOADER_WORKER` + - `THREAD_CREATE_FLAGS_SKIP_LOADER_INIT` + - `THREAD_CREATE_FLAGS_BYPASS_PROCESS_FREEZE` + +# See also + - `NtResumeThread` + - `NtSuspendThread` diff --git a/descriptions/thread_create_flags_hide_from_debugger.md b/descriptions/thread_create_flags_hide_from_debugger.md index e69de29bb2d..b97469a4ea4 100644 --- a/descriptions/thread_create_flags_hide_from_debugger.md +++ b/descriptions/thread_create_flags_hide_from_debugger.md @@ -0,0 +1,16 @@ +This flags indicates that the system should not notify debuggers attached to the target process about thread creation. This option also suppresses other debug events on the target thread for the entirety of its lifetime. + +# Applicable to + - `NtCreateThreadEx` + +# Related flags + - `THREAD_CREATE_FLAGS_NONE` + - `THREAD_CREATE_FLAGS_CREATE_SUSPENDED` + - `THREAD_CREATE_FLAGS_SKIP_THREAD_ATTACH` + - `THREAD_CREATE_FLAGS_LOADER_WORKER` + - `THREAD_CREATE_FLAGS_SKIP_LOADER_INIT` + - `THREAD_CREATE_FLAGS_BYPASS_PROCESS_FREEZE` + +# See also + - `NtSetInformationThread` with `ThreadHideFromDebugger` + - `NtWaitForDebugEvent` diff --git a/descriptions/thread_create_flags_loader_worker.md b/descriptions/thread_create_flags_loader_worker.md index e69de29bb2d..4f5fc7d9ea7 100644 --- a/descriptions/thread_create_flags_loader_worker.md +++ b/descriptions/thread_create_flags_loader_worker.md @@ -0,0 +1,15 @@ +This flags indicates that the system should set the `LoaderWorker` flag in `TEB`. Used internally. + +# Applicable to + - `NtCreateThreadEx` + +# Related flags + - `THREAD_CREATE_FLAGS_NONE` + - `THREAD_CREATE_FLAGS_CREATE_SUSPENDED` + - `THREAD_CREATE_FLAGS_SKIP_THREAD_ATTACH` + - `THREAD_CREATE_FLAGS_HIDE_FROM_DEBUGGER` + - `THREAD_CREATE_FLAGS_SKIP_LOADER_INIT` + - `THREAD_CREATE_FLAGS_BYPASS_PROCESS_FREEZE` + +# See also + - `TEB` diff --git a/descriptions/thread_create_flags_none.md b/descriptions/thread_create_flags_none.md index e69de29bb2d..7f0aa5ad9d6 100644 --- a/descriptions/thread_create_flags_none.md +++ b/descriptions/thread_create_flags_none.md @@ -0,0 +1,13 @@ +This flags indicates the absence of other thread creation flags. + +# Applicable to + - `NtCreateThreadEx` + - `NtCreateUserProcess` + +# Related flags + - `THREAD_CREATE_FLAGS_CREATE_SUSPENDED` + - `THREAD_CREATE_FLAGS_SKIP_THREAD_ATTACH` + - `THREAD_CREATE_FLAGS_HIDE_FROM_DEBUGGER` + - `THREAD_CREATE_FLAGS_LOADER_WORKER` + - `THREAD_CREATE_FLAGS_SKIP_LOADER_INIT` + - `THREAD_CREATE_FLAGS_BYPASS_PROCESS_FREEZE` diff --git a/descriptions/thread_create_flags_skip_loader_init.md b/descriptions/thread_create_flags_skip_loader_init.md index e69de29bb2d..f634d1bcf6a 100644 --- a/descriptions/thread_create_flags_skip_loader_init.md +++ b/descriptions/thread_create_flags_skip_loader_init.md @@ -0,0 +1,15 @@ +This flags indicates that the system should set the `SkipLoaderInit` flag in `TEB`. Used internally. + +# Applicable to + - `NtCreateThreadEx` + +# Related flags + - `THREAD_CREATE_FLAGS_NONE` + - `THREAD_CREATE_FLAGS_CREATE_SUSPENDED` + - `THREAD_CREATE_FLAGS_SKIP_THREAD_ATTACH` + - `THREAD_CREATE_FLAGS_HIDE_FROM_DEBUGGER` + - `THREAD_CREATE_FLAGS_LOADER_WORKER` + - `THREAD_CREATE_FLAGS_BYPASS_PROCESS_FREEZE` + +# See also + - `TEB` diff --git a/descriptions/thread_create_flags_skip_thread_attach.md b/descriptions/thread_create_flags_skip_thread_attach.md index e69de29bb2d..d36254e8e7e 100644 --- a/descriptions/thread_create_flags_skip_thread_attach.md +++ b/descriptions/thread_create_flags_skip_thread_attach.md @@ -0,0 +1,19 @@ +This flags indicates that the new thread should not call any [DllMain](https://learn.microsoft.com/en-us/windows/win32/dlls/dllmain) callbacks with `DLL_THREAD_ATTACH` reason on loaded modules. Keep in mind that this flags might introduce compatibility issues because threads started with it have some of their state not initialized. See [this blog post](https://m417z.com/A-guest-in-another-process-a-story-of-a-remote-thread-crash/) for more details. + +# Applicable to + - `NtCreateThreadEx` + +# Implementation details +Using this flag sets the `SkipThreadAttach` flag in the `TEB` of the new thread. + +# Related flags + - `THREAD_CREATE_FLAGS_NONE` + - `THREAD_CREATE_FLAGS_CREATE_SUSPENDED` + - `THREAD_CREATE_FLAGS_HIDE_FROM_DEBUGGER` + - `THREAD_CREATE_FLAGS_LOADER_WORKER` + - `THREAD_CREATE_FLAGS_SKIP_LOADER_INIT` + - `THREAD_CREATE_FLAGS_BYPASS_PROCESS_FREEZE` + +# See also + - `RtlIsCurrentThreadAttachExempt` + - `LDRP_DONT_CALL_FOR_THREADS` diff --git a/descriptions/thread_state_change_type.md b/descriptions/thread_state_change_type.md index e69de29bb2d..8d3b79a7188 100644 --- a/descriptions/thread_state_change_type.md +++ b/descriptions/thread_state_change_type.md @@ -0,0 +1,28 @@ +This enumeration defines types of operations that can be performed on thread state objects. + +# Applicable to + - `NtChangeThreadState` + +# Members + +## ThreadStateChangeSuspend (0) +Suspends the associated thread. + +| | Change +| --------------- | ------ +| Extra bufffer | void (zero size) +| Required access | `THREAD_SUSPEND_RESUME` + +### See also + - `NtSuspendThread` + +## ThreadStateChangeResume (1) +Resumes the associated thread. + +| | Change +| --------------- | ------ +| Extra bufffer | void (zero size) +| Required access | `THREAD_SUSPEND_RESUME` + +### See also + - `NtResumeThread` diff --git a/descriptions/threadinfoclass.md b/descriptions/threadinfoclass.md index e69de29bb2d..15eac4a51e0 100644 --- a/descriptions/threadinfoclass.md +++ b/descriptions/threadinfoclass.md @@ -0,0 +1,414 @@ +This enumeration defines types of information that can be queried or set for threads. + +# Applicable to + - `NtQueryInformationThread` + - `NtSetInformationThread` + +# Members + +## ThreadBasicInformation (0) +Retrieves basic information about the thread such as its exit status, `TEB` address, and `CLIENT_ID`. + +| | Query | Set +| --------------- | ---------------------------------- | --- +| Type | `THREAD_BASIC_INFORMATION` | N/A +| Required access | `THREAD_QUERY_LIMITED_INFORMATION` | N/A + +### Related Win32 API + - [`GetExitCodeThread`](https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-getexitcodethread) + - [`GetThreadId`](https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-getthreadid) + - [`GetProcessIdOfThread`](https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-getprocessidofthread) + - [`GetThreadPriority`](https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-getthreadpriority) + +### See also + - `NtCurrentTeb` + +## ThreadTimes (1) +Retrieves creation and executions times for the thread. + +| | Query | Set +| --------------- | ---------------------------------- | --- +| Type | `KERNEL_USER_TIMES` | N/A +| Required access | `THREAD_QUERY_LIMITED_INFORMATION` | N/A + +### Related Win32 API + - [`GetThreadTimes`](https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-getthreadtimes) + +## ThreadPriority (2) +Adjusts the priority of the thread. + +| | Query | Set +| ------------------ | ----- | --- +| Type | N/A | `KPRIORITY` +| Required access | N/A | `THREAD_SET_LIMITED_INFORMATION` +| Required privilege | None | `SeIncreaseBasePriorityPrivilege` + +## ThreadBasePriority (3) +Adjusts the base priority of the thread. + +| | Query | Set +| --------------- | ----- | --- +| Type | N/A | `KPRIORITY` +| Required access | N/A | `THREAD_SET_LIMITED_INFORMATION` + +## ThreadAffinityMask (4) +Limits on which processors the thread is allowed to run. + +| | Query | Set +| --------------- | ----- | --- +| Type | N/A | `KAFFINITY` +| Required access | N/A | `THREAD_SET_LIMITED_INFORMATION` + +## ThreadImpersonationToken (5) +Sets thread impersonation token. Note that if the token of the target process does not have `SeImpersonatePrivilege` enabled, the system might downgrade the assigned token to the identification level of impersonation. + +| | Query | Set +| --------------- | ----- | --- +| Type | N/A | Token `HANDLE` with `TOKEN_IMPERSONATE` access +| Required access | N/A | `THREAD_SET_THREAD_TOKEN` + +### Related Win32 API + - [`SetThreadToken`](https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-setthreadtoken) + +### See also + - `NtOpenThreadToken` + +## ThreadDescriptorTableEntry (6) + +| | Query | Set +| --------------- | ---------------------------------------------------------- | --- +| Type | `DESCRIPTOR_TABLE_ENTRY` or `WOW64_DESCRIPTOR_TABLE_ENTRY` | N/A +| Required access | `THREAD_QUERY_INFORMATION` | N/A + +## ThreadEnableAlignmentFaultFixup (7) + +| | Query | Set +| --------------- | ----- | --- +| Type | N/A | `BOOLEAN` +| Required access | N/A | `THREAD_SET_INFORMATION` + +## ThreadEventPair (8) + +## ThreadQuerySetWin32StartAddress (9) +Retrieves the start address of a Win32 thread. + +| | Query | Set +| --------------- | -------------------------- | --- +| Type | `PVOID` or `ULONG_PTR` | N/A +| Required access | `THREAD_QUERY_INFORMATION` | N/A + +## ThreadZeroTlsCell (10) +Zeros out the specified TLS cell indicated by index. + +| | Query | Set +| --------------- | ----- | --- +| Type | N/A | `ULONG` +| Required access | N/A | `THREAD_SET_INFORMATION` + +## ThreadPerformanceCount (11) + +| | Query | Set +| --------------- | -------------------------- | --- +| Type | `LARGE_INTEGER` | N/A +| Required access | `THREAD_QUERY_INFORMATION` | N/A + +## ThreadAmILastThread (12) +Determines if the thread is the only one in the process. + +| | Query | Set +| --------------- | ---------------------------------- | --- +| Type | `ULONG` or `BOOL` | N/A +| Required access | `THREAD_QUERY_LIMITED_INFORMATION` | N/A + +## ThreadIdealProcessor (13) +Adjusts the number of the ideal (preferred) processor for the thread. This info class only supports the current processor group. To set the ideal processor from another group, use `ThreadIdealProcessorEx` (info class 33). + +| | Query | Set +| --------------- | ----- | --- +| Type | N/A | `ULONG` +| Required access | N/A | `THREAD_SET_INFORMATION` + +### Related Win32 API + - [`SetThreadIdealProcessor`](https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-setthreadidealprocessor) + +## ThreadPriorityBoost (14) +Queries, enables, or disables priority boosting for the thread + +| | Query | Set +| --------------- | ---------------------------------- | --- +| Type | `ULONG` or `BOOL` | `ULONG` or `BOOL` +| Required access | `THREAD_QUERY_LIMITED_INFORMATION` | `THREAD_SET_LIMITED_INFORMATION` + +### Related Win32 API + - [`SetThreadPriorityBoost`](https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-setthreadpriorityboost) + +## ThreadSetTlsArrayAddress (15) + +## ThreadIsIoPending (16) +Determines if the thread has any pending I/O requests. + +| | Query | Set +| --------------- | -------------------------- | --- +| Type | `ULONG` or `BOOL` | N/A +| Required access | `THREAD_QUERY_INFORMATION` | N/A + +## ThreadHideFromDebugger (17) +Queries or enables suppression of debug events generated on the thread. Threads that do not generate debug events are essentially invisible to debuggers. + +| | Query | Set +| --------------- | -------------------------- | --- +| Type | `BOOLEAN` | void (zero-size) +| Required access | `THREAD_QUERY_INFORMATION` | `THREAD_SET_INFORMATION` + +### See also + - `THREAD_CREATE_FLAGS_HIDE_FROM_DEBUGGER` + - `NtWaitForDebugEvent` + +## ThreadBreakOnTermination (18) +Marks the thread as critical, causing a BSOD if it terminates. + +| | Query | Set +| ------------------ | -------------------------- | --- +| Type | `ULONG` or `BOOL` | `ULONG` or `BOOL` +| Required access | `THREAD_QUERY_INFORMATION` | `THREAD_SET_INFORMATION` +| Required privilege | None | `SeDebugPrivilege` + +### See also + - `RtlSetThreadIsCritical` + - `NtRaiseHardError` + +## ThreadSwitchLegacyState (19) + +## ThreadIsTerminated (20) +Determines if the thread has already terminated. The result is similar to a no-timeout wait on the handle via `NtWaitForSingleObject` but requires a different access mask. + +| | Query | Set +| --------------- | ---------------------------------- | --- +| Type | `ULONG` or `BOOL` | N/A +| Required access | `THREAD_QUERY_LIMITED_INFORMATION` | N/A + +### See also + - `NtWaitForSingleObject` + - `NtTerminateThread` + - `NtTerminateProcess` + +## ThreadLastSystemCall (21) +Queries the information about the last syscall performed by the thread. + +| | Query | Set +| --------------- | --------------------------------- | --- +| Type | `THREAD_LAST_SYSCALL_INFORMATION` | N/A +| Required access | `THREAD_GET_CONTEXT` | N/A + +## ThreadIoPriority (22) +Determines or adjusts I/O priority for the thread. + +| | Query | Set +| ------------------ | ---------------------------------- | --- +| Type | `IO_PRIORITY_HINT` | `IO_PRIORITY_HINT` +| Required access | `THREAD_QUERY_LIMITED_INFORMATION` | `THREAD_SET_INFORMATION` +| Required privilege | None | `SeIncreaseBasePriorityPrivilege` + +## ThreadCycleTime (23) +Determines the number of cycles spent by the thread. + +| | Query | Set +| --------------- | ---------------------------------- | --- +| Type | `THREAD_QUERY_LIMITED_INFORMATION` | N/A +| Required access | `THREAD_QUERY_LIMITED_INFORMATION` | N/A + +## ThreadPagePriority (24) +Determines or adjusts paging priority for the thread. + +| | Query | Set +| --------------- | ---------------------------------- | --- +| Type | `PAGE_PRIORITY_INFORMATION` | `PAGE_PRIORITY_INFORMATION` +| Required access | `THREAD_QUERY_LIMITED_INFORMATION` | `THREAD_SET_INFORMATION` + +## ThreadActualBasePriority (25) +Adjusts the base priority of the thread. + +| | Query | Set +| ------------------ | ----- | --- +| Type | N/A | `LONG` +| Required access | N/A | `THREAD_SET_LIMITED_INFORMATION` +| Required privilege | None | `SeIncreaseBasePriorityPrivilege` + +## ThreadTebInformation (26) +Allows reading a portion of the thread's TEB. + +| | Query | Set +| --------------- | ------------------------------------------- | --- +| Type | `THREAD_TEB_INFORMATION` | N/A +| Required access | `THREAD_GET_CONTEXT` + `THREAD_SET_CONTEXT` | N/A + +## ThreadCSwitchMon (27) + +## ThreadCSwitchPmu (28) + +## ThreadWow64Context (29) +Gets and sets the WoW64 context (set of registers) for 32-bit threads running on 64-bit systems. + +| | Query | Set +| --------------- | -------------------- | --- +| Type | `WOW64_CONTEX` | `WOW64_CONTEX` +| Required access | `THREAD_GET_CONTEXT` | `THREAD_SET_CONTEXT` + +### Related Win32 API + - [`Wow64GetThreadContext`](https://learn.microsoft.com/en-us/windows/win32/api/wow64apiset/nf-wow64apiset-wow64getthreadcontext) + - [`Wow64SetThreadContext`](https://learn.microsoft.com/en-us/windows/win32/api/wow64apiset/nf-wow64apiset-wow64setthreadcontext) + +### See also + - `RtlWow64GetThreadContext` + - `RtlWow64SetThreadContext` + +## ThreadGroupInformation (30) +Queries or adjusts the processor group for the thread. + +| | Query | Set +| --------------- | ---------------------------------- | --- +| Type | `GROUP_AFFINITY` | `GROUP_AFFINITY` +| Required access | `THREAD_QUERY_LIMITED_INFORMATION` | `THREAD_SET_INFORMATION` + +## ThreadUmsInformation (31) + +## ThreadCounterProfiling (32) + +## ThreadIdealProcessorEx (33) +Queries or the number of the ideal (preferred) processor for the thread. + +| | Query | Set +| --------------- | ---------------------------------- | --- +| Type | `PROCESSOR_NUMBER` | `PROCESSOR_NUMBER` +| Required access | `THREAD_QUERY_LIMITED_INFORMATION` | `THREAD_SET_INFORMATION` + +### Related Win32 API + - [`SetThreadIdealProcessorEx`](https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-setthreadidealprocessorex) + +## ThreadCpuAccountingInformation (34) + +## ThreadSuspendCount (35) +Queries the current suspension counter of the thread. Note that the value is incremented by one for frozen threads. If the value is zero, the thread is allowed to run. + +| | Query | Set +| --------------- | ---------------------------------- | --- +| Type | `ULONG` | N/A +| Required access | `THREAD_QUERY_LIMITED_INFORMATION` | N/A +| Minimal version | Windows 8.1 | N/A + +### See also + - `NtSuspendThread` + - `NtResumeThread` + +## ThreadHeterogeneousCpuPolicy (36) +Determines heterogeneous (big.LITTLE) scheduling policy for the thread. + +| | Query | Set +| --------------- | ---------------------------------- | --- +| Type | `KHETERO_CPU_POLICY` | N/A +| Required access | `THREAD_QUERY_LIMITED_INFORMATION` | N/A +| Minimal version | Windows 10 TH1 (1507) | N/A + +## ThreadContainerId (37) +Queries the job container ID attached to the thread. + +| | Query | Set +| --------------- | ---------------------------------- | --- +| Type | `GUID` | N/A +| Required access | `THREAD_QUERY_LIMITED_INFORMATION` | N/A +| Minimal version | Windows 10 TH1 (1507) | N/A + +## ThreadNameInformation (38) +Queries or sets the thread description string. + +| | Query | Set +| --------------- | ---------------------------------- | --- +| Type | `THREAD_NAME_INFORMATION` | `THREAD_NAME_INFORMATION` +| Required access | `THREAD_QUERY_LIMITED_INFORMATION` | `THREAD_SET_LIMITED_INFORMATION` +| Minimal version | Windows 10 TH1 (1507) | Windows 10 TH1 (1507) + +### Related Win32 API + - [`GetThreadDescription`](https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-getthreaddescription) + - [`SetThreadDescription`](https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-setthreaddescription) + +## ThreadSelectedCpuSets (39) + +## ThreadSystemThreadInformation (40) +Queries various information (exit status, times, priority, etc.) for the thread, returning the same structure as used when enumerating processes/threads via `NtQuerySystemInformation`. + +| | Query | Set +| --------------- | ---------------------------------- | --- +| Type | `SYSTEM_THREAD_INFORMATION` | N/A +| Required access | `THREAD_QUERY_LIMITED_INFORMATION` | N/A +| Minimal version | Windows 10 TH1 (1507) | N/A + +## ThreadActualGroupAffinity (41) + +| | Query | Set +| --------------- | ---------------------------------- | --- +| Type | `GROUP_AFFINITY` | N/A +| Required access | `THREAD_QUERY_LIMITED_INFORMATION` | N/A +| Minimal version | Windows 10 TH2 (1511) | N/A + +## ThreadDynamicCodePolicyInfo (42) +Checks or applies exemptions for dynamic code policy (the [Arbitrary Code Guard](https://learn.microsoft.com/en-us/microsoft-365/security/defender-endpoint/exploit-protection-reference?view=o365-worldwide#arbitrary-code-guard) mitigation). + +| | Query | Set +| --------------- | ---------------------------------- | --- +| Type | `ULONG` or `BOOL` | `ULONG` or `BOOL` +| Required access | `THREAD_QUERY_LIMITED_INFORMATION` | N/A (`NtCurrentThread` only) +| Minimal version | Windows 10 TH2 (1511) | Windows 10 TH2 (1511) + +## ThreadExplicitCaseSensitivity (43) +Configures explicit case-sensitivity for the thread. + +| | Query | Set +| ------------------ | ---------------------------------- | --- +| Type | `ULONG` or `BOOL` | `ULONG` or `BOOL` +| Required access | `THREAD_QUERY_LIMITED_INFORMATION` | `THREAD_SET_INFORMATION` +| Required privilege | None | `SeDebugPrivilege` +| Minimal version | Windows 10 TH2 (1511) | Windows 10 TH2 (1511) + +## ThreadWorkOnBehalfTicket (44) + +## ThreadSubsystemInformation (45) +Determines the subsystem of the thread. + +| | Query | Set +| --------------- | ---------------------------------- | --- +| Type | `SUBSYSTEM_INFORMATION_TYPE` | N/A +| Required access | `THREAD_QUERY_LIMITED_INFORMATION` | N/A +| Minimal version | Windows 10 RS2 (1703) | N/A + +## ThreadDbgkWerReportActive (46) +Enables or disables Windows Error Reporting on the thread. + +| | Query | Set +| --------------- | ----- | --- +| Type | N/A | `ULONG` or `BOOL` +| Required access | N/A | `THREAD_SET_INFORMATION` +| Minimal version | N/A | Windows 10 RS2 (1703) + +## ThreadAttachContainer (47) + +| | Query | Set +| --------------- | ----- | --- +| Type | N/A | Job `HANDLE` with `JOB_OBJECT_IMPERSONATE` access +| Required access | N/A | N/A (`NtCurrentThread` only) +| Minimal version | N/A | Windows 10 RS2 (1703) + +## ThreadManageWritesToExecutableMemory (48) + +## ThreadPowerThrottlingState (49) + +## ThreadWorkloadClass (50) + +## ThreadCreateStateChange (51) + +## ThreadApplyStateChange (52) + +## ThreadStrongerBadHandleChecks (53) + +## ThreadEffectiveIoPriority (54) + +## ThreadEffectivePagePriority (55) diff --git a/descriptions/wow64decodeapcroutine.md b/descriptions/wow64decodeapcroutine.md index e69de29bb2d..5d97b3443fa 100644 --- a/descriptions/wow64decodeapcroutine.md +++ b/descriptions/wow64decodeapcroutine.md @@ -0,0 +1,4 @@ +This macro decodes pointers previously encoded with `Wow64EncodeApcRoutine`. + +# See also + - `RtlQueueApcWow64Thread` diff --git a/descriptions/wow64encodeapcroutine.md b/descriptions/wow64encodeapcroutine.md index e69de29bb2d..d11c45a302e 100644 --- a/descriptions/wow64encodeapcroutine.md +++ b/descriptions/wow64encodeapcroutine.md @@ -0,0 +1,6 @@ +This macro encodes the function pointer and indicates to `NtQueueApcThread`, `NtQueueApcThreadEx`, or `NtQueueApcThreadEx2` that the APC should be executed in the WoW64 mode. + +To decode the pointer back, use `Wow64DecodeApcRoutine`. + +# See also + - `RtlQueueApcWow64Thread`