NtWaitForMultipleObjects - NtDoc

Native API online documentation, based on the System Informer (formerly Process Hacker) phnt headers
#ifndef _NTOBAPI_H
//
// Objects, handles
//
#if (PHNT_MODE != PHNT_MODE_KERNEL)

/**
 * Waits for one or all of an array of waitable objects. Use WaitAny to identify
 * the satisfied object, or WaitAll to acquire the complete set without partially
 * consuming available signals while other objects are not ready.
 *
 * \param Count Number of handles, from 1 through MAXIMUM_WAIT_OBJECTS (64).
 * \param Handles Array of Count pointer-sized handles, each requiring SYNCHRONIZE
 * (0x00100000). WaitAll rejects duplicate underlying dispatcher objects, including
 * distinct handle values obtained by duplicating a handle to the same object.
 * \param WaitType WaitAll (0) or WaitAny (1). WaitAny selects the lowest array
 * index among objects simultaneously eligible when the wait is evaluated.
 * \param Alertable TRUE permits an alert or ordinary user APC to interrupt the wait.
 * \param Timeout Optional 100-nanosecond deadline: NULL for no deadline, pointed-to
 * zero for polling, negative for a relative interval, positive for absolute NT system time.
 * \return WaitAny returns STATUS_WAIT_0 plus the selected zero-based index, or
 * STATUS_ABANDONED_WAIT_0 (0x80) plus that index when acquiring an abandoned mutant.
 * WaitAll returns STATUS_SUCCESS (0), or STATUS_ABANDONED (0x80) when the set is
 * acquired and includes an abandoned mutant; the latter does not identify an index.
 * STATUS_TIMEOUT (0x102), STATUS_USER_APC (0xC0) and STATUS_ALERTED (0x101) do not
 * establish acquisition. Test the status category, not just NT_SUCCESS.
 * \remarks On the native x64 and WoW64 paths, invalid Count returns
 * STATUS_INVALID_PARAMETER_1, invalid WaitType returns STATUS_INVALID_PARAMETER_3,
 * and WaitAll with duplicate objects returns STATUS_INVALID_PARAMETER_MIX.
 * All handles are referenced and access-checked before entering the dispatcher wait;
 * an inaccessible later handle fails even if an earlier object is already signaled.
 * A WaitAll timeout does not consume signals or acquire an abandoned mutant from
 * an incomplete set. A completion-port handle is rejected for WaitAll with
 * STATUS_INVALID_HANDLE. Cross-VM and special object paths
 * have additional restrictions; this is not a promise that any handle is waitable.
 * \sa https://learn.microsoft.com/en-us/windows/win32/api/synchapi/nf-synchapi-waitformultipleobjectsex
 */
_Kernel_entry_
NTSYSCALLAPI
NTSTATUS
NTAPI
NtWaitForMultipleObjects(
    _In_ ULONG Count,
    _In_reads_(Count) HANDLE Handles[],
    _In_ WAIT_TYPE WaitType,
    _In_ BOOLEAN Alertable,
    _In_opt_ PLARGE_INTEGER Timeout
    );

#endif
#endif

View code on GitHub
#ifndef _NTZWAPI_H

_Kernel_entry_
NTSYSCALLAPI
NTSTATUS
NTAPI
ZwWaitForMultipleObjects(
    _In_ ULONG Count,
    _In_reads_(Count) HANDLE Handles[],
    _In_ WAIT_TYPE WaitType,
    _In_ BOOLEAN Alertable,
    _In_opt_ PLARGE_INTEGER Timeout
    );

#endif

View code on GitHub

NtDoc

Waits for one or more objects to enter a signaled state.

Parameters

Notable return values

Remarks

Despite the name, NtAlertThreadByThreadId is unrelated to alertable waits and cannot interrupt them.

Related Win32 API

See also

NTinternals.net (undocumented.ntinternals.net)

ObjectCount

Number of objects in ObjectsArray array.

ObjectsArray

Pointer to array of HANDLE. Each must be opened with SYNCHRONIZE access.

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

See also