m417z · m417z · Aug 23, 2023 · Aug 23, 2023 · Aug 23, 2023
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -1,14 +1,16 @@
-### pContext
+Retrieves the context (set of registers) of the specified thread.
 
-See `<ntddk.h>` 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
@@ -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`
Original file line number	Diff line number	Diff line change
		@@ -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.