Using Symbols with WDEB386

With WDEB386, all symbols are maintained into one single namespace. Symbols are explicitly manageed using w, wr, and wa. You can selectively enable and disable entire symbol files. When disabled, the debugger ignores all symbols that belong to a symbol file ("map").

The w command lists all the maps that are loaded, both enabled and disabled.

The wr command disables a symbol file ("removes a map").

The wa command enables a symbol file ("adds a map").

For example, wr explorer will remove the explorer map from the debugger's symbol table. Keeping only the maps relevant to your project is important because the debugger's symbol table doesn't understand memory contexts.

As a shortcut, the asterisk means "all maps". So wr * disables all maps, and wa * re-enables them. Disabling all maps is useful if you want to discard all the symbolic information because the user is running with the wrong symbols.

Every symbol is mapped to a linear address, and that becomes its identity. In particular, the memory context and CPU mode are not factors in looking up a matching symbol. As a consequence, if you are running Win32 code, and you try to resolve an address that happens to match that of a Win16 driver or a DOS application, then you get symbols displayed that are irrelevant to the context of your code.

To search the active maps for symbols, you can us the ls (list symbols) or lse (list symbols by regular expression) commands. The argument is either a DOS-style (ls) or a UNIX-style (lse) pattern that will be looked up in all active maps. These are useful if you have the same symbol in multiple files and the debugger keeps picking the wrong one, and you choose not to go and disable all the maps that contain the bogus ones.

If you type a partial symbol name (at least five characters) and no perfect match is found, Wdeb386 will search for symbols that start with the characters you specify and present them in a list. You can then pick the one you really want and continue onwards.

If, in spite of everything, Wdeb386 can't find a symbol to match your address, it will search internal OS data structures, hoping to find something. If it has some Win16 address, it will walk the Win16 module list, checking to see if the selector is a code or data segment that belongs to any module in memory. If so, then it displays the address in the form MODULE!(n), where MODULE is the module name and n is the object number (1-based).

If the address lives in VxD space, then Wdeb386 will look at the list of in-memory VxDs and try to figure out which (if any) VxD contains the address. If found, the address is given in the form DDB(n)+zzzz, where DDB is the VxD DDB name, n is the object number, and zzzz is the offset within the object.

If the selector lives on the 16-bit global heap, but Wdeb386 can figure out which task allocated the memory, it will display the address in the form TASK!, where TASK! is the module name of the owner.

If the address lives in the Win32 memory space, then Wdeb386 will look at the page table entries and figure out which module table entry the memory belongs to. It will then display the address in the form IMTEnnnn+zzzz, where nnnn is the module table entry index, and zzzz is the rva. If Wdeb386 can find the Win32 module table on its own, then it will do the conversion of the IMTE into a module name and display the result in the form MODULE.DLL+zzzz, where MODULE.DLL is the name of the module and zzzz is the rva.

In summary:

If the symbol address is listed with an @-sign, it means that the module associated with the symbol is not in memory (or at least, is not in memory as far as Wdeb386 can determine). You can set a breakpoint on it. When the module finally gets loaded, Wdeb386 will instantiate the breakpoint.