LDR_DATA_TABLE_ENTRY

The LDR_DATA_TABLE_ENTRY structure is NTDLL’s record of how a DLL is loaded into a process. In early Windows versions, this structure is similarly the kernel’s record of each module that is loaded for kernel-mode execution. The different demands of kernel and user modes eventually led to the separate definition of a KLDR_DATA_TABLE_ENTRY. For simplicity, though not historical completeness, this note on the LDR_DATA_TABLE_ENTRY is specialised to its user-mode handling.

Access

Each process has its own list of loaded modules. In some sense, it has three lists: although there is only the one LDR_DATA_TABLE_ENTRY structure for each module, each is linked in three different orders. The way to find the lists is well known, including to malware. The Ldr member of the process’s PEB points to the process’s PEB_LDR_DATA which contains the list heads as its members named InLoadOrderModuleList, InMemoryOrderModuleList and InInitializationOrderModuleList.

Less well known—or less well respected in real-world practice, even by programmers who aren’t writing malware—is that the links in these lists are not safe to follow while modules might be loaded and unloaded. That this can’t happen at the time can be hard enough to ensure even for the current process. Sadly, the preceding sentence is much too subtle for many hackers and even for many commentators who would not imagine that they might be thought of dismissively as hackers.

Documentation Status

In an ideal world, the LDR_DATA_TABLE_ENTRY might be opaque outside NTDLL. But various high-level modules supplied with Windows over the years have used at least one member of the LDR_DATA_TABLE_ENTRY, which eventually had to be disclosed. A new header, named WINTERNL.H, for previously internal APIs was added to the Software Development Kit (SDK) apparently in 2002, and remains to this day. Starting with the SDK for Windows 7, WINTERNL.H presents a modified LDR_DATA_TABLE_ENTRY that has just the InMemoryOrderLinks, DllBase, FullDllName, CheckSum and TimeDateStamp members, plus padding that gets these members to the same offsets as in the true structure. It seems unlikely that Microsoft will change the LDR_DATA_TABLE_ENTRY in any way that moves these members.

Layout

Indeed, given that LDR_DATA_TABLE_ENTRY at least started as an undocumented structure for internal use, it is surprisingly stable across Windows versions. Until a significant reworking for Windows 8, the structure grew only by extension and many of the original members—which happen to be the most useful in practice—keep their same positions through the whole history. The following table shows the changing sizes:

These sizes, and the offsets, types and names in the tables that follow, are from Microsoft’s symbol files for the kernel starting with Windows 2000 SP3 and for NTDLL starting with Windows XP. Symbol files for earlier versions do not contain type information for the LDR_DATA_TABLE_ENTRY, but type information for a smattering of earlier versions was published in statically linked libraries: GDISRVL.LIB from the Device Driver Kit (DDK) for Windows NT 3.51; and SHELL32.LIB from the DDK for Windows NT 4.0. Inspection of binaries anyway confirms that all but one member had near enough the same usage as far back as Windows NT 3.10.

Original

LIST_ENTRY InLoadOrderLinks;

LIST_ENTRY InMemoryOrderLinks;

LIST_ENTRY InInitializationOrderLinks;

union {
    LIST_ENTRY InInitializationOrderLinks;
    LIST_ENTRY InProgressLinks;
};

PVOID DllBase;

PVOID EntryPoint;

ULONG SizeOfImage;

UNICODE_STRING FullDllName;

UNICODE_STRING BaseDllName;

ULONG Flags;

union {
    UCHAR FlagGroup [4];
    ULONG Flags;
    struct {
        /*  bit fields, follow link  */
    };  
};

USHORT LoadCount;

USHORT ObsoleteLoadCount;

USHORT TlsIndex;

union {
    LIST_ENTRY HashLinks;
    struct {
        PVOID SectionPointer;
        ULONG CheckSum;
    };
};

LIST_ENTRY HashLinks;

A practical reason to know of this structure is for the debugging exercise of finding why a DLL did not get unloaded when expected or did get unloaded but by surprise. Both are questions of DLL reference counting. Before Windows 8, the LoadCount member of this structure is the reference count. The LDR_DATA_TABLE_ENTRY for the DLL in question is most easily found when the DLL has just loaded. A program’s loading and unloading of the DLL can then be tracked easily by setting a write-memory breakpoint on the LoadCount member. At each break to the debugger, look at what the count has changed to and look at a stack dump to see who made the change.

Appended for Windows NT 4.0

ULONG TimeDateStamp;

union {
    ULONG TimeDateStamp;
    PVOID LoadedImports;
};

ULONG TimeDateStamp;

Appended for Windows XP

PVOID EntryPointActivationContext;

PVOID PatchInformation;

PVOID Spare;

PVOID Lock;

Appended for Windows Vista

Insertion of the LDR_DATA_TABLE_ENTRY into three more lists for Windows Vista soon enough got undone when Windows 8 greatly reworked the tracking of DLLs as they get loaded and unloaded. These members’ positions have an entirely different use in Windows 8 and higher.

LIST_ENTRY ForwarderLinks;

LIST_ENTRY ServiceTagLinks;

LIST_ENTRY StaticLinks;

Redone for Windows 8

LDR_DDAG_NODE *DdagNode;

LIST_ENTRY NodeModuleLink;

LDRP_DLL_SNAP_CONTEXT *SnapContext;

LDRP_LOAD_CONTEXT *LoadContext;

PVOID ParentDllBase;

PVOID SwitchBackContext;

RTL_BALANCED_NODE BaseAddressIndexNode;

RTL_BALANCED_NODE MappingInfoIndexNode;

Appended for Windows 7

One addition for Windows 7 also got caught up in the reorganisation for Windows 8. Others are retained but shifted.

PVOID ContextInformation;

ULONG_PTR OriginalBase;

LARGE_INTEGER LoadTime;

Appended for Windows 8

ULONG BaseNameHashValue;

LDR_DLL_LOAD_REASON LoadReason;

Appended for Windows 8.1

ULONG ImplicitPathOptions;

Appended for Windows 10

When Windows 8 extended the LoadCount from its old 16 bits and moved it to the new LDR_DDAG_NODE, it defined a ReferenceCount, distinct from the LoadCount, and placed it in the LDR_DDAG_NODE with the new LoadCount. Windows 10 leaves the LoadCount there but moves the ReferenceCount here.

ULONG ReferenceCount;

ULONG DependentLoadFlags;

SE_SIGNING_LEVEL SigningLevel;