A2N maintains a database of modules and symbols and attempts to answer the following questions:
For the most part all the drudgery of using A2N is hidden by POST. A2N does export an API which allows a user to take advantage of A2N's functionality if they so desire. The API is described in a2n.h and is identical on all supported platforms.
A2N is distributed as a2n.dll on Windows.
Executable formats
A2N can only recognize and process PE executables, either 32 or 64-bit.Windows debug data formats
COFF ---- Not a Microsoft format. Documented. Well understood by A2N. Exists either in the executable image or in a separate file. Produces the highest quality symbols. * Harvested by A2N: Yes * Line number information: No CodeView -------- Microsoft format. Somewhat documented. Exists either in the executable image on in a separate file. It is also referred to in the Microsoft documentation as "CV". Produces very high quality symbols. * Harvested by A2N: Yes * Line number information: No MAP --- Generated by the linker. Exists only in a separate file. A2N reads MAP files produced by Visual C++ 5.0 and 6.0. Maps yield excellent symbol quality, equal to COFF/CodeView symbols. * Harvested by A2N: Yes * Line number information: No PDB --- Microsoft format. Undocumented. Exists only in a separate file. Symbols are harvested using the Microsoft symbol engine. Quality depends on the version of the Microsoft symbol engine (dbghelp.dll). * Harvested by A2N: Yes * Line number information: Yes (if available)Microsoft symbol engine
Microsoft provides an engine to harvest symbols (all formats) from images and/or symbol files. The engine is implemented in DBGHELP.DLL (which is re-distributable). The type of symbol information returned by DBGHELP.DLL depends on the version of the DLL. For example: sometimes you get statics, sometimes you don't. DBGHELP.DLL is shipped with the OS, in the %SystemRoot%\System32 directory. The most recent version can be downloaded from Microsoft as part of the "Debugging Tools for Windows" package. As of this writing the link to download the Debugging Tools is: http://www.microsoft.com/whdc/devtools/debugging/installx86.mspxA2N handles the following types of "symbol" files:
DBG --- DBG files contain the same debug information (COFF and CodeView) that would normally be included in the image. The information, however, has been removed from the image (using REBASE.EXE) and put into a DBG file. In general the A2N harvester follows the same rules as the Microsoft symbol engine (dbghelp.dll) when locating DBG symbol files. The harvester uses the "searchpath" (either user supplied or a default one) and appends "\symbols" and "\dll" (for .dll) or "\exe" (for .exe) or "\sys" (for .sys), etc., to each component of the search path. If "searchpath" is specified it overrides the default search order and the harvester only uses the "searchpath" to look for symbol files. See "A2N symbol search order" below for A2N's search algorithm. PDB --- PDB (Program Database File) is a Microsoft proprietary debug format. Its format/contents is not documented and the only way to access information in the file is to use the Microsoft symbol engine (aka. dbghelp.dll). See "A2N symbol search order" below for A2N's search algorithm. For PDB files the search order is different. The algorithm is determined by the functionality of the Microsoft symbol engine. By default, MSVC++ strips the symbols and places them in a separate PDB file in the same directory as the executable. The compiler also stores the absolute path to the PDB file in the executable. If the MS symbol engine can't find the PDB file in that location then the symbol engine will locate the file using the same rules used for locating DBG files. MAP --- MAP files are plain text files produced by the linker. They contain symbol information and layout of the executable image. A2N uses the same search order as for DBG files. EXPORTS ------- In the absence of any other symbols, and for DLL/SYS files, A2N will harvest the Exported symbols. They're not very high quality but they may give enough information in cases where no other symbols are available.A2N symbol search order
In general the A2N harvester follows the same rules as the Microsoft symbol engine (dbghelp.dll) when locating symbol files. The harvester uses the "searchpath" (either user supplied or a default one) and appends "\symbols" and "\dll" (for .dll) or "\exe" (for .exe) or "\sys" (for .sys), etc., to each component of the search path. If "searchpath" is specified it overrides the default search order and the harvester only uses the "searchpath" to look for symbol files. If no "searchpath" is specified then the harvester uses the following default search order: - Same directory as executable - Paths listed in the A2N_SEARCH_PATH environment variable - %SystemRoot%\symbols\<dll | exe | sys> - Paths listed in the _NT_SYMBOL_PATH environment variable - Paths listed in the _NT_ALT_SYMBOL_PATH environment variable - Paths listed in the _NT_ALTERNATE_SYMBOL_PATH environment variable For PDB files the search order is different. The algorithm is determined by the functionality of the Microsoft symbol engine. By default, MSVC++ strips the symbols and places them in a separate PDB file in the same directory as the executable. The compiler also stores the absolute path to the PDB file in the executable. If the MS symbol engine can't find the PDB file in that location then the symbol engine will locate the file using the same rules used for locating DBG files. Within each directory symbol files are searched in the following order: 1) MAP (image_name.map) 2) PDB (image_name.pdb) (only if symbols stripped) 3) DBG (image_name.dbg) (only if symbols stripped) The search stops on the first symbol file match in any directory.Compiler/Linker flags
When building your applications you want to generate debugging symbol information. The recommended compiler/linker options are: Compiler Linker ---------- ---------------------------------------- CodeView -Z7 -debug -debugtype:CV -pdb:NONE COFF and CodeView -Z7 -debug -debugtype:BOTH -pdb:NONE PDB -Zi -debug -debugtype:CV -pdb:"filename" COFF and PDB -Zi -debug -debugtype:BOTH -pdb:"filename"Where do I get symbols from?
* For the operating system you get the symbols from Microsoft. Here you have a couple of choices: 1) Download a very large file (50-70MB) containing the Symbols Package for a particular OS version and Service Pack level. You will be taken to the download page for available symbol packages. In most cases this is overkill. Typically you're only interested in a very small set of symbol files which you can download via method (2). 2) Download only the symbols you're interested in. In order to do this there are a couple of steps involved: a. Download the latest Debugging Tools for Windows. b. Make sure the directory where they were installed is listed in the PATH environment variable. c. Use the symget command included in the Performance Inspector™ for Windows Tools package. The command resides in the symtools directory. d. Use the symchk command included in the Microsoft Debugging Tools. * For non-operating system applications you get the symbols from the manufacturer. * For your own applications you generate the symbols using the appropriate compiler and linker flags. See the Visual C++ documentation.