In 16-bit versions of Windows (1.x, 2.x, 3.x), each module (application or DLL) typically has its own data segment (DGROUP) limited to 64 KB. This segment contains the stack, the local heap, and the atom table. Local heap functions manage memory within this segment using near pointers (offsets). They are exported by the kernel (KRNL386.EXE). Internally, the local heap is managed through a set of data structures that reside inside the segment itself.

A key part of this management is the Instance Data (also called the NULL segment) located at the very beginning of DGROUP, which holds pointers to the heap, atom table, and stack information. The field at offset 6 (pLocalHeap) contains a near pointer to the HeapInfo structure that heads the local heap. This pointer is set by LocalInit() and must be validated by checking the signature word (li_sig) at offset 22h (Standard mode) or 28h (KRNL386) within the presumed heap.

The local heap itself is organized as a series of arenas (headers) that precede each block. The two low bits of the la_prev field in an arena are used as flags: bit 0 indicates whether the block is in use (1) or free (0); bit 1 indicates whether the block is MOVEABLE (1) or FIXED (0). Free blocks are linked via la_free_prev and la_free_next. For MOVEABLE blocks, a separate handle table (pointed to by hi_htable in HeapInfo) stores the actual address, lock count, and flags; each handle is an offset into this table.

The first 16 (10h) bytes of the default data segment (DGROUP) are reserved for system use and are collectively referred to as the Instance Data or NULL segment. This area is present only if the first WORD at offset 0 is zero; otherwise, the structure is not present. The layout is as follows:

Important Notes: * The field at offset 6 (pLocalHeap) is the primary way to locate the local heap structures given only the DGROUP selector. * When LocalInit() is called on a globally allocated block (non‑DGROUP), the WORD at offset 6 of that block is also set to point to the local heap information structure for that block. * Similarly, if InitAtomTable() is called on a global block, offset 8 points to the atom table, and offset 6 will point to the associated local heap (since atoms are stored in the local heap).

Every local heap begins with an instance of the HeapInfo structure, which is identical to the one used by the global heap and is defined in WINKERN.INC. Its location is given by the pLocalHeap field at offset 6 of the Instance Data. Immediately following the HeapInfo structure are additional fields that, together with HeapInfo, form the LocalInfo structure.

In the enhanced mode (krnl386), the HeapInfo structure occupies 1Eh bytes and has the following format (according to “Windows Internals” documentation, Table 2-2):

In standard mode (krnl286), the HeapInfo structure occupies 18h bytes. Due to the 16‑bit segmented architecture, near pointers are used instead of far pointers, and all size fields are limited to 64 KB. The layout is as follows:

Note: In krnl286, all pointer fields are near (16‑bit offsets) because the local heap resides in a single 64‑KB segment.

For krnl386 (HeapInfo size of 1Eh), the LocalInfo structure has the following layout:

For krnl286, the LocalInfo structure immediately follows the HeapInfo structure and contains additional fields that manage heap notifications, locking, sizing, and a signature word. Its layout begins at offset 18h from the start of the local heap information block:

Important: In krnl286, the li_sig field is located at offset 22h from the beginning of the combined HeapInfo + LocalInfo structure.

The total size of the local heap information block (HeapInfo + LocalInfo) for krnl286 is therefore 24h bytes (18h + 0Ch), though only the first 22h bytes are used up to the signature. The signature itself occupies bytes 22h–23h.

Every block in the local heap is preceded by an arena (header) that contains management information. Arenas always start on a 4‑byte boundary, so the two low bits of every arena address are zero. These bits are reused as flags in the la_prev field of each arena. The two low bits of la_prev have the following meaning:

* Bit 0 (least significant): Set if the block is in use (FIXED or MOVEABLE); cleared if the block is free. * Bit 1: Set if the block is MOVEABLE; cleared if the block is FIXED (only meaningful when bit 0 is set).

Thus, to obtain the real address of the previous arena, the two low bits must be masked off.

There are three arena formats, corresponding to the three possible block states:

For a FIXED block, the handle is the address of the block itself. The arena can be found by subtracting 4 from the block address.

The la_handle field provides two‑way mapping between a MOVEABLE block and its handle table entry. Given the block address, subtract 6 to get the arena; the la_handle field gives the offset of the handle entry. Given a handle entry, the first field (lhe_address) gives the block address.

Free blocks are threaded in a doubly linked list using la_free_prev and la_free_next. The start of this free list is stored in the la_free_next field of the first block in the heap (see below).

The first block in the local heap is special. It resides in memory before the LocalInfo structure. Although its la_prev field has the low bit set (indicating a FIXED, in‑use arena), the local heap routines treat this arena as if it were free. The la_free_next field of this first block points to the first truly free block in the heap.

For MOVEABLE blocks, handles are offsets into a handle table that resides in its own local heap blocks. The first handle table is located via the hi_htable field in the HeapInfo structure. Each handle table begins with a WORD specifying how many handle entries follow. After all entries, the last WORD is the offset of the next handle table (or 0 if none). Free handle entries are linked together for quick allocation.

Format of Handle Table Entries (in-use):

Format of Handle Table Entries (free):

* Allocation (LocalAlloc) walks the free list, splitting blocks if necessary, and sets up the appropriate arena. For MOVEABLE blocks, it also allocates a handle table entry. * Compaction (LocalCompact) coalesces adjacent free blocks and may move or discard unlocked MOVEABLE blocks. When a block is moved, its lhe_address is updated. * Locking (LocalLock/LocalUnlock) manipulates the lhe_count field of the handle entry for MOVEABLE blocks; for FIXED blocks, no count is maintained. * Discarding (LocalDiscard) frees the memory of a MOVEABLE block but keeps the handle entry alive with the LHE_DISCARDED flag set.

Atom tables provide a mechanism for efficiently storing and sharing strings (atoms) in 16-bit Windows. Each module may have its own local atom table located in its local heap. In addition, there is a single global atom table that serves the entire system.

The field at offset 08h in the Instance Data (`pAtomTable`) contains a near pointer to the atom table header for the current module. This pointer is initialized by calling `InitAtomTable()`. If no atom table exists, `pAtomTable` is zero.

Physically, an atom table resides inside the local heap of some data segment . Therefore, before creating an atom table, the segment must be initialized as a local heap by calling `LocalInit()`.

Windows supports two fundamentally different types of atoms: string atoms and integer atoms.

Integer atoms are a special category of atoms that are not stored in an atom table and therefore do not have an associated `ATOMENTRY` structure.

* Range: `0x0001` to `0xBFFF` . * Reference count: Not applicable, as they are not allocated from the heap . * String representation: When passed to functions that expect a string (e.g., `GetAtomName`), an integer atom is converted to a string of the form `“#dddd”`, where `dddd` is the decimal representation of the number. For example, atom `0x8001` becomes `“#32769”` . Leading zeros are not included. * Purpose: Used for predefined system objects to avoid wasting memory on storing strings. Classic examples are built-in window classes such as the dialog box class `“#32770”` . Other known values: `#32768` (PopupMenu), `#32769` (Desktop), `#32771` (WinSwitch), `#32772` (IconTitle) .

Important consequence: Functions like `GlobalAddAtom`, when passed a string of the form `“#1234”`, will return the integer atom `0x04D2` instead of creating a new table entry .

These are the “classic” atoms created when `AddAtom` or `GlobalAddAtom` is called with an ordinary string.

* Range: `0xC000` to `0xFFFF` . * Physical memory representation: Each string atom is represented by an `ATOMENTRY` structure located in the local heap. The atom value itself (type `ATOM`) is an encoded near pointer to this structure .

This is a direct implementation feature of 16-bit Windows : 1. Alignment: All blocks in the local heap are aligned on a 4-byte boundary. The low 2 bits of any pointer to an `ATOMENTRY` structure are always zero. 2. Encoding: To obtain a 16-bit atom from the 14 significant bits of the pointer, Windows shifts the pointer right by 2 bits (making room for flags) and sets the two high bits to 1. This guarantees that all string atoms fall into the range `0xC000…0xFFFF`. 3. Decoding: To convert an atom back to a pointer (`GetAtomHandle`), the system clears the two high bits and shifts the value left by 2 bits. 4. Range separation: This scheme leaves the range `0x0001…0xBFFF` for integer atoms, allowing functions to quickly distinguish atom types by value.

The `ATOMENTRY` structure is the exact layout of a string atom in the heap. It is defined in the SDK file `WINEXP.H` and has the following form:

In C/C++: ```c typedef struct atomstruct {

  struct atomstruct near *next;  /* Next entry in collision chain */
  WORD usage;                    /* Reference count */
  BYTE len;                      /* Length of string */
  BYTE name;                     /* Start of string */

} ATOMENTRY; ```

Important: The `name` field is a flexible array member. Memory for the structure is allocated with enough space to hold the actual string. There are no flags or other hidden fields in this structure.

An atom table is a hash table implemented as an array of “buckets”. It is placed directly in the local heap .

In simplified C: ```c typedef struct {

  WORD numEntries;
  ATOMENTRY near *hashtab[];

} ATOMTABLE; ```

* Local atom tables: Bound to a specific data segment (e.g., an application's DGROUP). Created by calling `InitAtomTable()`. Used for a module's internal needs. Access is only possible when the DS register points to that segment. * Global atom table: A system-wide table accessible to all applications via `GlobalAddAtom`, `GlobalFindAtom`, and `GlobalDeleteAtom` . Physically, it resides not in an application's data segment but in a special USER data segment (part of the so-called “global atom and text heap”) . Its structure is identical to a local atom table. The `Global…` functions internally switch DS to the USER segment and call the ordinary `AddAtom`/`FindAtom`.

Since all atom operations (`AddAtom`, `FindAtom`, etc.) work with the current segment pointed to by DS, you can create and use an atom table in any arbitrary data segment by following three steps :

1. Create a local heap in the target segment using `LocalInit(Selector, Start, End)`. 2. Switch the DS register to that segment. 3. Call `InitAtomTable(size)` to initialize the atom table in the newly created heap.

After that, any subsequent call to `AddAtom`, `FindAtom`, etc., will operate on the custom table if DS is temporarily set to the correct segment .

Example in assembly: ```asm ; Assume a local heap already exists in segment CUST_SEG push ds mov ax, CUST_SEG mov ds, ax push 37 ; hash table size call InitAtomTable ; create atom table in this segment pop cx pop ds ```

A convenience wrapper in C: ```c ATOM BasedAddAtom(WORD wSeg, LPCSTR lpString) {

  ATOM ret;
  _asm push ds
  _asm mov  ds, wSeg
  ret = AddAtom(lpString);
  _asm pop  ds
  return ret;

} ```

Although each module typically has a default local heap in its DGROUP, it is possible to create additional local heaps in other segments or in globally allocated memory. This is useful for managing private memory pools within a large global block, or for creating atom tables in separate memory areas.

The `LocalInit()` function initializes a local heap within a specified segment. Its prototype is:

```c WORD LocalInit(WORD wSegment, WORD pStart, WORD pEnd); ```

* `wSegment` – Selector of the segment where the heap will be created. * `pStart` – Offset of the first byte of the heap area (must be paragraph‑aligned, i.e., a multiple of 16). * `pEnd` – Offset of the last byte of the heap area (inclusive). The heap will manage memory from `pStart` to `pEnd`.

If successful, `LocalInit()` returns a non‑zero value. It sets up the `HeapInfo` and `LocalInfo` structures at the beginning of the heap area (starting at `pStart`) and updates the segment’s instance data at offset 06h (`pLocalHeap`) to point to that `HeapInfo` structure. However, if the segment is not a default data segment (i.e., not DGROUP), the instance data at offset 0 must also contain a zero word to indicate that the NULL segment structure is present; otherwise, the heap may not be recognized by some routines.

Example: Creating a local heap in a globally allocated block of memory:

```asm ```

After this call, the global block can be used with local heap functions (`LocalAlloc`, `LocalFree`, etc.) by using the selector in `DX` and near pointers (offsets) within that segment.

Important Considerations: - The heap structures themselves occupy space at the beginning of the heap area. The first block (sentinel) resides at `pStart + size of (LocalInfo)`. - The segment’s instance data (at offset 0) must be properly set up, especially the zero word at offset 0, to avoid confusion with other structures. - Custom local heaps are not automatically enlarged if they run out of space; they are limited to the range specified in `LocalInit`. - The `HEAPSIZE` setting in the module’s .DEF file only affects the default DGROUP heap.

As already described in the atom section, to create an atom table in an arbitrary memory area, you must first initialize a local heap there (as above) and then, after switching DS, call `InitAtomTable`. This technique allows fully isolated atom tables for special purposes.

- Use `LocalInit` on a segment to establish a local heap anywhere in memory. - The segment must have a valid NULL segment structure (zero word at offset 0) for the heap to be recognized. - After `LocalInit`, you can use `LocalAlloc`, `LocalLock`, etc., with near pointers within that segment. - To create an atom table in a custom heap, switch DS to that segment and call `InitAtomTable`. - All subsequent atom operations must be performed with DS set appropriately (or via wrapper functions). - Custom heaps and atom tables are useful for isolating memory pools, implementing resource managers, or working with large data structures without polluting the default DGROUP.

1. Schulman, A., Maxey, D., Pietrek, M. Undocumented Windows. Addison-Wesley, 1992. 2. Pietrek, M. Windows Internals. Addison-Wesley, 1993. 3. Chen, R. The Old New Thing (blog). Microsoft Developer Blogs. 4. Microsoft OS/2 Programmer's Reference, Volume 1.