Document handle/object operations

descriptions/initializeobjectattributes.md

@@ -0,0 +1 @@
+Initializes an `OBJECT_ATTRIBUTES` structure. This macro is [documented in Windows Driver Kit](https://learn.microsoft.com/en-us/windows/win32/api/ntdef/nf-ntdef-initializeobjectattributes).

descriptions/ntclose.md

@@ -1,8 +1,21 @@
-This function is documented in Windows Driver Kit [here](https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/ntifs/nf-ntifs-ntclose) and [here](https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/wdm/nf-wdm-zwclose).
+Closes the specified kernel handle. This function is documented in Windows Driver Kit [here](https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/ntifs/nf-ntifs-ntclose) and [here](https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/wdm/nf-wdm-zwclose).
 
----
+# Parameters
+ - `Handle` - a handle to a kernel object.
 
-### ObjectHandle
+# Notable return values
+ - `STATUS_INVALID_HANDLE` - an invalid handle value was specified.
+ - `STATUS_HANDLE_NOT_CLOSABLE` - the provided handle is marked as protected from closing. See `OBJ_PROTECT_CLOSE` for more details.
 
-Handle to open object. \
-If `ObjectHandle` is last reference to object in system, object will be removed from memory.
+# Remarks
+`NtClose` is one the few Native API functions that can raise exceptions instead of returning an error status code. See the [exploit protection reference](https://learn.microsoft.com/en-us/microsoft-365/security/defender-endpoint/exploit-protection-reference?view=o365-worldwide#validate-handle-usage) for a description of the mitigation that causes this behavior.
+
+# Related Win32 API
+ - [`CloseHandle`](https://learn.microsoft.com/en-us/windows/win32/api/handleapi/nf-handleapi-closehandle)
+
+# See also
+ - `OBJ_PROTECT_CLOSE`
+ - `NtMakeTemporaryObject`
+ - `NtDuplicateObject`
+ - `NtQueryObject`
+ - `NtSetInformationObject`

descriptions/ntcompareobjects.md

@@ -0,0 +1,22 @@
+Determines whether two handles point to the same kernel object.
+
+# Parameters
+ - `FirstObjectHandle` - a handle to the first object.
+ - `SecondObjectHandle` - a handle to the second object.
+
+The handles do not need to grant any specific access. Any of the handles can be a pseudo-handle to the current thread (`NtCurrentThread`) or the current process (`NtCurrentProcess`).
+
+# Notable return values
+ - `STATUS_SUCCESS` - the two handles point to the same underlying kernel object.
+ - `STATUS_NOT_SAME_OBJECT` - the handles point toward different objects.
+
+# Related Win32 API
+ - [`CompareObjectHandles`](https://learn.microsoft.com/en-us/windows/win32/api/handleapi/nf-handleapi-compareobjecthandles)
+
+# Required OS version
+This function was introduced in Windows 10 TH1 (1507).
+
+# See also
+ - `NtDuplicateObject`
+ - `RtlIsCurrentThread`
+ - `RtlIsCurrentProcess`

descriptions/ntcurrentprocess.md

@@ -0,0 +1,5 @@
+This macro is a native equivalent of the [`GetCurrentProcess`](https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-getcurrentprocess) function. It returns a pseudo-handle that grants `PROCESS_ALL_ACCESS` to the current process. You do not need to call `NtClose` on the returned handle.
+
+# See also
+ - `NtCurrentThread`
+ - `RtlIsCurrentProcess`

descriptions/ntcurrentthread.md

@@ -1 +1,5 @@
-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.
+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. You do not need to call `NtClose` on the returned handle.
+
+# See also
+ - `NtCurrentProcess`
+ - `RtlIsCurrentThread`

descriptions/ntdelayexecution.md

@@ -8,6 +8,7 @@ Initiates a sleep on the current thread.
  - `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`.
+ - `STATUS_NO_YIELD_PERFORMED` - a zero-timeout sleep did not cause switching to other threads.
 
 # Remarks
 Despite the name, `NtAlertThreadByThreadId` is unrelated to alertable sleeps and cannot interrupt them.

descriptions/ntduplicateobject.md

@@ -1,9 +1,33 @@
-This function is [documented in Windows Driver Kit](https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/ntifs/nf-ntifs-zwduplicateobject).
+Allows copying handles across process boundaries and opening additional handles pointing to the same underlying kernel object. This function is [documented in Windows Driver Kit](https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/ntifs/nf-ntifs-zwduplicateobject).
 
----
+# Parameters
+ - `SourceProcessHandle` - a handle to the source process. This can be the `NtCurrentProcess` pseudo-handle or a handle granting `PROCESS_DUP_HANDLE` access.
+ - `SourceHandle` - the source handle to duplicate. This value is meaningful in the context of the source process.
+ - `TargetProcessHandle` - a handle to the target process. This can be the `NtCurrentProcess` pseudo-handle or a handle granting `PROCESS_DUP_HANDLE` access.
+ - `TargetHandle` - an optional pointer to a variable that receives the new handle. This value is meaningful in the context of the target process.
+ - `DesiredAccess` - the access mask to grant on the new handle.
+ - `HandleAttributes` - the object attribute flags to set on the new handle. Supported flags are `OBJ_INHERIT` and `OBJ_PROTECT_CLOSE`.
+ - `Options` - the flags that control the behavior of the function described below.
 
-See *Microsoft SDK* for description of `DuplicateHandle` *Win32 API*.
+# Supported flags
+ - `DUPLICATE_CLOSE_SOURCE` - instructs the system to close the source handle. Note that this occurs regardless of any error status returned. The target handle parameter becomes optional when using this flag.
+ - `DUPLICATE_SAME_ACCESS` - instructs the system to ignore the `DesiredAccess` parameter and copy the access mask from the source handle.
+ - `DUPLICATE_SAME_ATTRIBUTES` - instructs the system to ignore the `HandleAttributes` parameter and copy the handle attributes from the source handle.
 
-# Documented by
+# Remarks
+This function offers a wide range of modes of operation:
 
-* Tomasz Nowak
+1. Duplicate or reopen handles within the calling process. This function allows making copies of existing handles with different access/attributes.
+2. Copying handles from other processes.
+3. Copying handles into other processes.
+4. Closing handles in other processes.
+
+Note that this function performs an access check against the security descriptor of the source handle only when the `Options` parameter does not include the `DUPLICATE_SAME_ACCESS` flag.
+
+# Related Win32 API
+ - [`DuplicateHandle`](https://learn.microsoft.com/en-us/windows/win32/api/handleapi/nf-handleapi-duplicatehandle)
+
+# See also
+ - `NtClose`
+ - `NtQueryObject`
+ - `NtSetInformationObject`

descriptions/ntmakepermanentobject.md

@@ -0,0 +1,13 @@
+Marks an object as permanent, extending its lifetime past the last closed handle. Calling this function requires having `SeCreatePermanentPrivilege` enabled. To undo the operation, use `NtMakeTemporaryObject`.
+
+# Parameters
+ - `Handle` - a handle to a kernel object. The handle does not need to grant any specific access.
+
+# Remarks
+To make new objects have permanent state from their creation, include `OBJ_PERMANENT` in `OBJECT_ATTRIBUTES`.
+
+# See also
+ - `NtMakeTemporaryObject`
+ - `OBJ_PERMANENT`
+ - `OBJECT_BASIC_INFORMATION`
+ - `NtQueryObject`

descriptions/ntmaketemporaryobject.md

@@ -1,20 +1,13 @@
-This function is [documented in Windows Driver Kit](https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/wdm/nf-wdm-zwmaketemporaryobject).
+Removes the permanent flag from the object, restoring its lifetime to be dependant on the number of handles. This function is [documented in Windows Driver Kit](https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/wdm/nf-wdm-zwmaketemporaryobject).
 
----
+# Parameters
+ - `Handle` - a handle to a kernel object. The handle must grant `DELETE` access.
 
-*(Also avaiable in Win2000 DDK)*
-
-Function clears object's *PERMANENT* flag, so it's live as long as the latest `HANDLE` is closed.
-
-### ObjectHandle
-
-`HANDLE` to object to make temporary.
-
-# Documented by
-
-* Tomasz Nowak
+# Remarks
+This function undoes the effects of `NtMakePermanentObject` and specifying `OBJ_PERMANENT` in `OBJECT_ATTRIBUTES`.
 
 # See also
-
-* `NtClose`
-* `NtQueryObject`
+ - `NtMakePermanentObject`
+ - `OBJ_PERMANENT`
+ - `OBJECT_BASIC_INFORMATION`
+ - `NtQueryObject`

descriptions/ntqueryobject.md

@@ -1,34 +1,21 @@
-This function is documented in Windows Driver Kit [here](https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/ntifs/nf-ntifs-ntqueryobject) and [here](https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/ntifs/nf-ntifs-zwqueryobject).
+Retrieves various information about kernel handles and the objects they point to. This function is partially documented in Windows Driver Kit [here](https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/ntifs/nf-ntifs-ntqueryobject) and [here](https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/ntifs/nf-ntifs-zwqueryobject).
 
----
+# Parameters
+ - `Handle` - a kernel handle to query information about. The handle does not need to grant any specific access.
+ - `ObjectInformationClass` - the type of information to retrieve.
+ - `ObjectInformation` - a pointer to a user-allocated buffer that receives the requested information.
+ - `ObjectInformationLength` - 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.
 
-Function `NtQueryObject` retrives some informations about any or all objects opened by calling process. It can be used with any type of object.
+# Information classes
+For the list of supported information classes, see `OBJECT_INFORMATION_CLASS`.
 
-### ObjectHandle
+# Notable return values
+ - `STATUS_BUFFER_TOO_SMALL` and `STATUS_INFO_LENGTH_MISMATCH` indicate that the requested information does not fit into the provided buffer.
 
-HANDLE to object.
-
-### ObjectInformationClass
-
-Kind of information to retrive. See `OBJECT_INFORMATION_CLASS` for possible values list.
-
-### ObjectInformation
-
-Output buffer allocated by caller.
-
-### Length
-
-Length of `ObjectInformation` buffer, in bytes.
-
-### ResultLength
-
-Pointer to `ULONG` value that contains required size of `ObjectInformation` buffer after function call.
-
-# Documented by
-
-* Tomasz Nowak
+# Related Win32 API
+ - [`GetHandleInformation`](https://learn.microsoft.com/en-us/windows/win32/api/handleapi/nf-handleapi-gethandleinformation)
 
 # See also
-
-* `NtSetInformationObject`
-* `OBJECT_INFORMATION_CLASS`
+ - `NtSetInformationObject`
+ - `NtQuerySecurityObject`

descriptions/ntqueueapcthread.md

@@ -20,7 +20,7 @@ Note that user APCs on the Native API level have three parameters in contrast wi
  - [`QueueUserAPC`](https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-queueuserapc)
 
 # See also
- - `NtQueueApcThread`
+ - `NtQueueApcThreadEx`
  - `NtQueueApcThreadEx2`
  - `RtlQueueApcWow64Thread`
  - `NtOpenThread`

descriptions/ntqueueapcthreadex.md

@@ -13,7 +13,7 @@ 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
+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 (which might happen to acquire locks), it is crucial to keep the amount and complexity of the code invoked by the special APC routine to a minimum.
 
 To queue a WoW64 APC, encode the `ApcRoutine` parameter using the `Wow64EncodeApcRoutine` macro or use `RtlQueueApcWow64Thread`.
 

descriptions/ntqueueapcthreadex2.md

@@ -27,7 +27,7 @@ This function was introduced in Windows 11.
 
 # See also
  - `NtQueueApcThread`
- - `NtQueueApcThreadEx2`
+ - `NtQueueApcThreadEx`
  - `RtlQueueApcWow64Thread`
  - `NtOpenThread`
  - `NtTestAlert`

descriptions/ntsetinformationobject.md

@@ -1,28 +1,19 @@
-### ObjectHandle
+Adjusts various information common to all types of kernel handles. 
 
-Open handle to any NT object.
+# Parameters
+ - `Handle` - a handle to set information on. The handle does not need to grant any specific access.
+ - `ObjectInformationClass` - the type of information to set.
+ - `ObjectInformation` - a pointer to the buffer with the data specific to the request.
+ - `ObjectInformationLength` - the size of the provided buffer in bytes.
 
-### ObjectInformationClass
+# Information classes
+For the list of supported information classes, see `OBJECT_INFORMATION_CLASS`.
 
-See `NtQueryObject` for detailed description of possible information classes.
-
-### ObjectInformation
-
-Buffor with data to set.
-
-### Length
-
-Length of `ObjectInformation` buffer, in bytes.
-
----
-
-Currently only one class in allowed in set mode: `ObjectDataInformation`. See description of `OBJECT_DATA_INFORMATION` structure.
-
-# Documented by
-
-* Tomasz Nowak
+# Related Win32 API
+ - [`SetHandleInformation`](https://learn.microsoft.com/en-us/windows/win32/api/handleapi/nf-handleapi-sethandleinformation)
 
 # See also
-
-* `NtQueryObject`
-* `OBJECT_DATA_INFORMATION`
+ - `NtQueryObject`
+ - `NtSetSecurityObject`
+ - `OBJ_INHERIT`
+ - `OBJ_PROTECT_CLOSE`

descriptions/ntsetthreadexecutionstate.md

@@ -15,7 +15,7 @@ Sets the execution state for the current thread and manages the corresponding po
 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
+ - [`SetThreadExecutionState`](https://learn.microsoft.com/en-us/windows/win32/api/winbase/nf-winbase-setthreadexecutionstate)
 
 # See also
  - `NtPowerInformation`

descriptions/ntwaitformultipleobjects.md

@@ -1,33 +1,27 @@
-### ObjectCount
+Waits for one or more object to enter a signaled state.
 
-Number of objects in `ObjectsArray` array.
+# Parameters
+ - `Count` - the number of handles passed in the `Handles` parameter, up to `MAXIMUM_WAIT_OBJECTS` (64).
+ - `Handles` - a pointer to an array of handles. Each handle must grant `SYNCHRONIZE` access.
+ - `WaitType` - the type of wait to perform, either `WaitAll` or `WaitAny`.
+ - `Alertable` - determines whether the wait 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 wait prematurely.
+ - `Timeout` - an optional pointer to a variable that stores the wait internal. A negative value indicates relative timeout for the specified number of 100-nanosecond intervals. To wait a specific number of milliseconds, multiply them by `-10,000`. Positive values indicate an absolute time. `NULL` indicates an infinite timeout.
 
-### ObjectsArray
+# Notable return values
+ - `STATUS_WAIT_0`..`STATUS_WAIT_63` - the thread woke due to the n'th object being signaled.
+ - `STATUS_ABANDONED_WAIT_0`..`STATUS_ABANDONED_WAIT_63` - the thread woke due to the n'th passed mutex becoming abandoned.
+ - `STATUS_TIMEOUT` - the thread woke due to the timeout.
+ - `STATUS_USER_APC` - the wait was interrupted by an APC.
+ - `STATUS_ALERTED` - the wait was interrupted by a call to `NtAlertThread`.
 
-Pointer to array of `HANDLE`. Each must be opened with `SYNCHRONIZE` access.
+# Remarks
+Despite the name, `NtAlertThreadByThreadId` is unrelated to alertable waits and cannot interrupt them.
 
-### WaitType
-
-Can be `WaitAllObjects` or `WaitAnyObject`.
-
-### Alertable
-
-If set, thread is signaled (*APC* routines queued for this thread are executed).
-
-### TimeOut
-
-Time-out interval.
-
----
-
-`NtWaitForMultipleObjects` is used typically to response for notyfications. For synchronization purposes you should use `NtWaitForSingleObject`.
-
-# Documented by
-
-* Tomasz Nowak
+# Related Win32 API
+ - [`WaitForMultipleObjectsEx`](https://learn.microsoft.com/en-us/windows/win32/api/synchapi/nf-synchapi-waitformultipleobjectsex)
 
 # See also
-
-* `NtSignalAndWaitForSingleObject`
-* `NtWaitForSingleObject`
-* `OBJECT_WAIT_TYPE`
+ - `NtWaitForSingleObject`
+ - `NtDelayExecution`
+ - `NtAlertThread`
+ - `NtQueueApcThread`

descriptions/ntwaitforsingleobject.md

@@ -1,24 +1,25 @@
-This function is [documented in Windows Driver Kit](https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/ntifs/nf-ntifs-zwwaitforsingleobject).
+Waits for the object to enter a signaled state. This function is [documented in Windows Driver Kit](https://learn.microsoft.com/en-us/windows-hardware/drivers/ddi/ntifs/nf-ntifs-zwwaitforsingleobject).
 
----
+# Parameters
+ - `Handle` - a handle granting `SYNCHRONIZE` access.
+ - `Alertable` - determines whether the wait 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 wait prematurely.
+ - `Timeout` - an optional pointer to a variable that stores the wait internal. A negative value indicates relative timeout for the specified number of 100-nanosecond intervals. To wait a specific number of milliseconds, multiply them by `-10,000`. Positive values indicate an absolute time. `NULL` indicates an infinite timeout.
 
-### ObjectHandle
+# Notable return values
+ - `STATUS_WAIT_0` - the thread woke due to the object being signaled.
+ - `STATUS_ABANDONED_WAIT_0` - the thread woke due to the passed mutex becoming abandoned.
+ - `STATUS_TIMEOUT` - the thread woke due to the timeout.
+ - `STATUS_USER_APC` - the wait was interrupted by an APC.
+ - `STATUS_ALERTED` - the wait was interrupted by a call to `NtAlertThread`.
 
-`HANDLE` to alertable object.
+# Remarks
+Despite the name, `NtAlertThreadByThreadId` is unrelated to alertable waits and cannot interrupt them.
 
-### Alertable
-
-If set, calling thread is signaled, so all queued *APC* routines are executed.
-
-### TimeOut
-
-Time-out interval, in microseconds. **NULL** means infinite.
-
-# Documented by
-
-* Tomasz Nowak
+# Related Win32 API
+ - [`WaitForSingleObjectEx`](https://learn.microsoft.com/en-us/windows/win32/api/synchapi/nf-synchapi-waitforsingleobjectex)
 
 # See also
-
-* `NtSignalAndWaitForSingleObject`
-* `NtWaitForMultipleObjects`
+ - `NtWaitForMultipleObjects`
+ - `NtDelayExecution`
+ - `NtAlertThread`
+ - `NtQueueApcThread`