Format:PE (Portable Executable)/TLS directory
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).