RtlFindClearRuns function (wdm.h)

Article
02/22/2024

The RtlFindClearRuns routine finds the specified number of runs of clear bits within a given bitmap.

Syntax

NTSYSAPI ULONG RtlFindClearRuns(
  [in]  PRTL_BITMAP     BitMapHeader,
  [out] PRTL_BITMAP_RUN RunArray,
  [in]  ULONG           SizeOfRunArray,
  [in]  BOOLEAN         LocateLongestRuns
);

Parameters

[in] BitMapHeader

A pointer to the RTL_BITMAP structure that describes the bitmap. This structure must have been initialized by the RtlInitializeBitMap routine.

[out] RunArray

Pointer to the first element in a caller-allocated array for the bit position and length of each clear run found in the given bitmap variable.

[in] SizeOfRunArray

Specifies the maximum number of clear runs to satisfy this request.

[in] LocateLongestRuns

If TRUE, specifies that the routine is to search the entire bitmap for the longest clear runs it can find. Otherwise, the routine stops searching when it has found the number of clear runs specified by SizeOfRunArray.

Return value

RtlFindClearRuns returns the number of clear runs found.

Remarks

If LocateLongestRuns is TRUE, the clear runs indicated at RunArray are sorted from longest to shortest. A clear run can consist of a single bit.

Callers of RtlFindClearRuns must be running at IRQL <= APC_LEVEL if the memory that contains the bitmap variable is pageable or the memory at BitMapHeader is pageable. Otherwise, RtlFindClearRuns can be called at any IRQL.

Requirements

Requirement	Value
Minimum supported client	Available starting with Windows 2000.
Target Platform	Universal
Header	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL (See Remarks section)