Was this page helpful?
Your feedback about this content is important. Let us know what you think.
Additional feedback?
1500 characters remaining
Export (0) Print
Expand All

RunOnceInitialization routine

The RunOnceInitialization routine performs a one-time initialization operation.


RTL_RUN_ONCE_INIT_FN RunOnceInitialization;

ULONG RunOnceInitialization(
  _Inout_ PRTL_RUN_ONCE RunOnce,
  _Inout_ PVOID         Parameter,
  _Out_   PVOID         *Context
{ ... }


RunOnce [in, out]

A pointer to the RTL_RUN_ONCE one-time initialization structure that the driver previously passed as a parameter to the RtlRunOnceExecuteOnce routine that called this RunOnceInitialization routine.

Parameter [in, out]

The Parameter value that the driver passed to the RtlRunOnceExecuteOnce routine that called this RunOnceInitialization routine.

Context [out]

A pointer to a PVOID variable to which the routine writes the initialization data.

Return value

The RunOnceInitialization routine returns a nonzero value to indicate success, and returns zero to indicate failure.


A driver-implemented RunOnceInitialization routine performs driver-specific initialization and then writes the initialization data to the memory location that the Context parameter points to. Drivers use the RtlRunOnceExecuteOnce routine to make a one-time call to a RunOnceInitialization routine. The operating system guarantees that the RunOnceInitialization routine is not called twice for the same value of the RunOnce parameter.

A small number of low-order bits in the location pointed to by the Context parameter are reserved for use by the operating system. Your driver's RunOnceInitialization routine should set these reserved bits to zero in the output value that it writes to *Context. The RTL_RUN_ONCE_CTX_RESERVED_BITS constant defined in Ntddk.h specifies the number of low-order bits that are reserved. Currently, RTL_RUN_ONCE_CTX_RESERVED_BITS is defined to be two, which means that the driver must set the two least significant bits of the PVOID value pointed to by Context to zero.


To define a RunOnceInitialization callback routine, you must first provide a function declaration that identifies the type of callback routine you're defining. Windows provides a set of callback function types for drivers. Declaring a function using the callback function types helps Code Analysis for Drivers, Static Driver Verifier (SDV), and other verification tools find errors, and it's a requirement for writing drivers for the Windows operating system.

For example, to define a RunOnceInitialization callback routine that is named MyRunOnceInitialization, use the RTL_RUN_ONCE_INIT_FN type as shown in this code example:

RTL_RUN_ONCE_INIT_FN MyRunOnceInitialization;

Then, implement your callback routine as follows:

    PRTL_RUN_ONCE  RunOnce,
    PVOID  Parameter,
    PVOID  *Context
      // Function body

The RTL_RUN_ONCE_INIT_FN function type is defined in the Wdm.h header file. To more accurately identify errors when you run the code analysis tools, be sure to add the _Use_decl_annotations_ annotation to your function definition. The _Use_decl_annotations_ annotation ensures that the annotations that are applied to the RTL_RUN_ONCE_INIT_FN function type in the header file are used. For more information about the requirements for function declarations, see Declaring Functions by Using Function Role Types for WDM Drivers. For information about _Use_decl_annotations_, see Annotating Function Behavior.


Target platform



Drivers can implement the RunOnceInitialization routine only on Windows Vista and later versions of Windows.


Ntddk.h (include Ntddk.h or Ntifs.h)


Called at IRQL <= APC_LEVEL.

See also




Send comments about this topic to Microsoft

© 2015 Microsoft