RtlRunOnceBeginInitialize function (ntddk.h)

Article
02/22/2024

The RtlRunOnceBeginInitialize routine begins a one-time initialization.

Syntax

NTSYSAPI NTSTATUS RtlRunOnceBeginInitialize(
  [in, out] PRTL_RUN_ONCE RunOnce,
  [in]      ULONG         Flags,
  [out]     PVOID         *Context
);

Parameters

[in, out] RunOnce

Pointer to the RTL_RUN_ONCE one-time initialization structure.

[in] Flags

Drivers can optionally specify one or more of the following flags:

RTL_RUN_ONCE_ASYNC

Perform initialization asynchronously. The driver can perform multiple completion attempts in parallel. If this flag is used, subsequent calls to this routine will fail unless this flag is also specified.

RTL_RUN_ONCE_CHECK_ONLY

Do not begin initialization, but check to determine if initialization has already occurred. If RtlRunOnceBeginInitialize returns STATUS_SUCCESS, the initialization succeeded, and *Context contains the initialized data.

[out] Context

Specifies a pointer to a PVOID variable that receives the initialized data. The value of *Context is valid only when the routine returns STATUS_SUCCESS.

Return value

RtlRunOnceBeginInitialize returns one of the following NTSTATUS values:

Return code	Description
STATUS_SUCCESS	The one-time initialization has already completed. The initialized data is stored in the memory location that Context points to.
STATUS_PENDING	The caller has successfully begun one-time initialization. The caller now performs the driver-specific initialization steps and then calls RtlRunOnceComplete to complete the initialization.

Remarks

Drivers can alternatively perform one-time initialization by calling RtlRunOnceExecuteOnce and supplying a RunOnceInitialization routine.

Requirements

Requirement	Value
Minimum supported client	Available in Windows Vista and later versions of Windows.
Target Platform	Universal
Header	ntddk.h (include Ntddk.h)
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL