RtlInstallFunctionTableCallback function (winnt.h)

Article
07/27/2022

Adds a dynamic function table to the dynamic function table list.

Syntax

NTSYSAPI BOOLEAN RtlInstallFunctionTableCallback(
  [in] DWORD64                        TableIdentifier,
  [in] DWORD64                        BaseAddress,
  [in] DWORD                          Length,
  [in] PGET_RUNTIME_FUNCTION_CALLBACK Callback,
  [in] PVOID                          Context,
  [in] PCWSTR                         OutOfProcessCallbackDll
);

Parameters

[in] TableIdentifier

The identifier for the dynamic function table callback. The two low-order bits must be set. For example, BaseAddress|0x3.

[in] BaseAddress

The base address of the region of memory managed by the callback function.

[in] Length

The size of the region of memory managed by the callback function, in bytes.

[in] Callback

A pointer to the callback function that is called to retrieve the function table entries for the functions in the specified region of memory. For a definition of the PGET_RUNTIME_FUNCTION_CALLBACK type, see WinNT.h.

[in] Context

A pointer to the user-defined data to be passed to the callback function.

[in] OutOfProcessCallbackDll

An optional pointer to a string that specifies the path of a DLL that provides function table entries that are outside the process.

When a debugger unwinds to a function in the range of addresses managed by the callback function, it loads this DLL and calls the OUT_OF_PROCESS_FUNCTION_TABLE_CALLBACK_EXPORT_NAME function, whose type is POUT_OF_PROCESS_FUNCTION_TABLE_CALLBACK. For more information, see the definitions of these items in WinNT.h.

Return value

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

Remarks

Function tables are used on 64-bit Windows to determine how to unwind or walk the stack. These tables are usually generated by the compiler and stored as part of the image. However, applications must provide the function table for dynamically generated code. For more information about function tables, see the architecture guide for your system.

This function is useful for very dynamic code. The application specifies the memory range for the generated code, but does not need to generate a table until it is needed by an unwind request. At that time, the system calls the callback function with the Context and the control address. The callback function must return the runtime function entry for the specified address. Be sure to avoid creating a deadlock between the callback function and the code generator.

For code that is generated from a template or generated only once during the life of the process, use the RtlAddFunctionTable function.

Requirements

Requirement	Value
Target Platform	Windows
Header	winnt.h (include Windows.h)
Library	Kernel32.lib
DLL	Kernel32.dll