LDR_DATA_TABLE_ENTRY

The LDR_DATA_TABLE_ENTRY structure is NTDLL’s record of how a DLL is loaded into a process.

Access

Each process has its own list of loaded modules. In some sense, it has three lists since 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 list 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 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.

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 NTDLL’s 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 inspection confirms that all but one member that was in use by then 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, see below  */
    };  
};

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

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;

If only for now, it seems the LDR_DLL_LOAD_REASON isn’t held elsewhere and may as well be enumerated here:

• 0 for LoadReasonStaticDependency;
• 1 for LoadReasonStaticForwarderDependency;
• 2 for LoadReasonDynamicForwarderDependency;
• 3 for LoadReasonDelayloadDependency;
• 4 for LoadReasonDynamicLoad;
• 5 for LoadReasonAsImageLoad;
• 6 for LoadReasonAsDataLoad;
• 7 for LoadReasonEnclavePrimary (1709 and higher);
• 8 for LoadReasonEnclaveDependency (1709 and higher);
• -1 for LoadReasonUnknown.

Appended for Windows 8.1

ULONG ImplicitPathOptions;

Appended for Windows 10

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

ULONG ReferenceCount;

ULONG DependentLoadFlags;

UCHAR SigningLevel;

Flags

Starting with version 6.2, what had just been a ULONG for Flags is elaborated formally as bit fields.

ULONG PackagedBinary : 1;

ULONG MarkedForRemoval : 1;

ULONG ImageDll : 1;

ULONG LoadNotificationsSent : 1;

ULONG TelemetryEntryProcessed : 1;

ULONG ProcessStaticImport : 1;

ULONG InLegacyLists : 1;

ULONG InIndexes : 1;

ULONG ShimDll : 1;

ULONG InExceptionTable : 1;

ULONG ReservedFlags1 : 2;

ULONG LoadInProgress : 1;

ULONG ReservedFlags2 : 1;

ULONG LoadConfigProcessed : 1;

ULONG EntryProcessed : 1;

ULONG ProtectDelayLoad : 1;

ULONG ReservedFlags3 : 3;

ULONG ReservedFlags3 : 2;

ULONG DontCallForThreads : 1;

ULONG ProcessAttachCalled : 1;

ULONG ProcessAttachFailed : 1;

ULONG CorDeferredValidate : 1;

ULONG CorImage : 1;

ULONG DontRelocate : 1;

ULONG CorILOnly : 1;

ULONG ChpeImage : 1;

ULONG ReservedFlags5 : 3;

ULONG ReservedFlags5 : 2;

ULONG Redirected : 1;

ULONG ReservedFlags6 : 2;

ULONG CompatDatabaseProcessed : 1;

In earlier versions, the Flags bits are presumably defined by macros. Names and values for some are known from the !dlls command as implemented in debugger extensions (KDEXTX86.DLL in versions 3.51 and 4.0, but EXTS.DLL for Windows XP and higher):