Jump to content
Setting up an AI agent? ReverseEngineering.wiki skill (works from the command line, no configuration): https://reverseengineering.wiki/skill/rewiki/SKILL.md · setup for every client, including MCP: https://reverseengineering.wiki/llms.txt · REWiki:Connect

Format:PE (Portable Executable)/TLS directory

From ReverseEngineering.wiki

Data directory 9 of a PE file: the IMAGE_TLS_DIRECTORY (24 bytes in PE32, 40 in PE32+) with the template of the thread-local data and a NULL-terminated array of TLS callbacks that the loader calls before the entry point and on every thread start and end.

Layout

The directory (data directory index 9, usually inside .rdata, symbol _tls_used in MSVC) is IMAGE_TLS_DIRECTORY32 (6 dwords, 24 bytes) or IMAGE_TLS_DIRECTORY64 (4 qwords + 2 dwords, 40 bytes). Unlike most PE pointers, the first four fields are virtual addresses (ImageBase + RVA), so they appear in the base relocation table and change with ASLR.

Field Meaning
StartAddressOfRawData VA of the first byte of the initial data template
EndAddressOfRawData VA of the byte after the template
AddressOfIndex VA of a dword where the loader stores the TLS index (_tls_index)
AddressOfCallBacks VA of an array of callback VAs, ended by a NULL pointer (0 means no callbacks)
SizeOfZeroFill number of zero bytes appended to the template (__declspec(thread) data without initialiser)
Characteristics reserved; bits 20-23 hold an IMAGE_SCN_ALIGN_* value for the alignment of the block

Each new thread gets a block made of the template (Start..End), then SizeOfZeroFill zero bytes. Code reaches it through the TEB: fs:[0x2C] (x86) or gs:[0x58] (x64) is ThreadLocalStoragePointer, an array indexed by the TLS index, so a typical access is mov eax, [tls_index]; mov ecx, fs:[2Ch]; mov ecx, [ecx+eax*4]; add ecx, offset.

Callbacks

A callback has the signature void NTAPI cb(PVOID DllHandle, DWORD Reason, PVOID Reserved), with the reasons DLL_PROCESS_ATTACH 1, DLL_PROCESS_DETACH 0, DLL_THREAD_ATTACH 2, DLL_THREAD_DETACH 3. The loader calls them for the process attach before the image entry point (before main and the CRT startup; for a DLL before DllMain), then on every thread creation and exit and at process exit. MSVC collects them from the CRT sections .CRT$XLA, .CRT$XLB ... .CRT$XLZ; the array is the part between the $XLA and $XLZ markers, so a C++ runtime (thread-local destructors, __dyn_tls_init) already puts at least one callback in many executables.

For reversers

  • Code in a TLS callback runs before the entry point, so a debugger that stops at the entry point misses it. Packers, protectors and malware use this for initialisation and anti-debugging; always list the callbacks (pefile: DIRECTORY_ENTRY_TLS.struct.AddressOfCallBacks; dumpbin /tls) before trusting the entry point. Break on the callback addresses, or set "break on TLS callbacks" in the debugger.
  • Compilers add benign callbacks too (MSVC __dyn_tls_init, __dyn_tls_dtor, MinGW __dyn_tls_init): recognise these by being tiny and calling the CRT before suspecting a hidden callback.
  • When parsing an unrelocated file, subtract ImageBase from every pointer; when parsing a loaded image they are already absolute. The array is NULL-terminated, not counted.
  • pefile rebases StartAddressOfRawData, EndAddressOfRawData, AddressOfIndex and AddressOfCallBacks when relocating (pefile.py, relocate_image), which confirms they are VAs.

Code & repositories

  • pefile structure formats __IMAGE_TLS_DIRECTORY_format__ / 64 (pefile.py lines 2713-2735).
  • Wine include/winnt.h: IMAGE_TLS_DIRECTORY32/64 (line 3963 ff), PIMAGE_TLS_CALLBACK (line 3959), DLL_PROCESS_ATTACH (line 692).

Evidence & references

  • Microsoft, "PE Format", section "The .tls Section" and "TLS Callback Functions" (learn.microsoft.com/en-us/windows/win32/debug/pe-format).
  • The TEB offsets fs:[2Ch] / gs:[58h] are from the documented TEB layout; Unverified in this wiki's tests (not run on a binary).